oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/docs/kb/modules/05-documents-ingest.md

3.1 KiB
Raw Blame History

Modul 5 — Ingest dokumentow -> koperta KB

Adapter obu zrodel (Paperless API + Nextcloud WebDAV) -> koperta KB. Domyka filar #2 w warstwie 2 (preprocess+index). Zalezy od: 2 (Paperless), 4 (Nextcloud).

Cel

Wciagnac dokumenty z Paperless i Nextcloud do spine KB (envelope w kb-postgres@PIHA), z OCR-textem + metadanymi, budujac pierwszy cross-source link (correspondent->maile).

Wymogi

  • jobs/documents-ingest/ — job CLI (wzorzec jak jobs/gmail-bulk-import/), pip install -e.
  • Dwa adaptery:
    • Paperless API: pobierz dokumenty (doc-id, correspondent, tags, created, OCR-content). raw_ref = REFERENCJA (doc-id) — Paperless=zrodlo prawdy. NIE kopiuj bajtow.
    • Nextcloud WebDAV: listuj pliki, pobierz. raw_ref = KOPIA do archiwum KB (snapshot, bo pliki znikaja). Wykrywaj zmiany (etag/mtime) -> nowa koperta (append).
  • Mapping -> koperta (packages/kb-mail wzorzec, moze packages/kb-documents):
    • source = paperless | nextcloud
    • id = stabilny (paperless doc-id | nextcloud fileid+etag)
    • ts = data dokumentu (Paperless: created/z tresci; Nextcloud: mtime)
    • geo = null (dokumenty zwykle bez geo; opcjonalnie z tresci pozniej)
    • raw_ref = referencja (paperless) | sciezka-archiwum (nextcloud)
    • entities[] = OCR-text (do embed), correspondent, tags, filename, content_type
  • Selektywny index (jak maile): archiwizuj/referuj wszystko, embeduj sensowne (OCR-text -> bge-m3 na SOLARIA -> pgvector). Pomijaj smiecie (puste skany? duplikaty?).

Graf encji (warstwa 3 — cienki start, PIERWSZY cross-source)

  • correspondent (Paperless: kto wystawil) = encja. Zmapuj do encji z maili (ten sam nadawca faktury i maila = ta sama osoba/firma). To DOWOD zasady kb-00 #7 (cienka warstwa 4 po drugim zrodle udowadnia cross-source linking).
  • Zapisz link w grafie encji (schema z warstwy 3 — jesli nie istnieje, cienki start tutaj).

Domkniecie dlugu z maili (faza-2-zalacznikow)

  • 70k zalacznikow z importu Gmaila (manifest w entities[] kopert mailowych).
  • Faktury/umowy/PDFy -> wyslij do Paperless (jego OCR + correspondent-detection), potem wciagnij z powrotem przez adapter Paperless. NIE osobny pipeline OCR.
  • Sizing: batch, partie (modul 3 OCR-worker na SOLARIA miele).

Do zweryfikowania przez CC

  • Paperless API: endpointy (documents, correspondents, tags), auth (token), paginacja.
  • Nextcloud WebDAV: listowanie rekurencyjne, etag, pobieranie, auth.
  • Czy packages/kb-mail da sie reuzyc czy potrzeba packages/kb-documents (koperta wspolna!).
  • Jak wykrywac zmiany w Nextcloud (polling etag? webhooks?) dla re-ingestu.
  • Deduplikacja: dokument w Paperless I jako zalacznik maila — ten sam? (sha256 match).

Kryteria ukonczenia

  • Dokumenty z Paperless + Nextcloud w tabeli envelope (kb-postgres@PIHA).
  • OCR-text zembedowany (pgvector), correspondent jako encja.
  • Min. jeden cross-source link correspondent<->mail zademonstrowany.
  • Idempotentny (re-run nie duplikuje — wzorzec z gmail-bulk-import ON CONFLICT).
  • Testy jednostkowe (wzorzec jobs/gmail-bulk-import/).
  • Faza-2-zalacznikow: przetestowana na probce (kilka faktur z maili -> Paperless -> ingest).