--- okf: "0.1" type: subsystem visibility: private status: active updated: 2026-08-06 links: [] --- # Filar maili — projekt (homelab-codex · KB · projekt #1) > Pierwszy filar. Wzorzec referencyjny dla pozostałych (archiwum, embeddingi na SOLARIA, szkielet agenta, deploy). > Zasady przekrojowe: patrz `kb-00-overview.md`. --- ## 1. Rdzeń: archiwum, nie RAG Realna potrzeba to najpierw **archiwum**, nie „RAG nad mailami". Dwie warstwy, fundamentalnie różne: - **Archiwum** — surowe, niezmienne, kompletne `.eml` / Maildir, append-only. To, co chcesz mieć u siebie *na zawsze*, niezależnie od jakiegokolwiek AI. Asset. - **Indeks** — pochodny, odtwarzalny, wyrzucalny. Parse → chunk → embed → pgvector. Re-budowalny z archiwum przy lepszym modelu. --- ## 2. Dwa żywe źródła (zmiana względem pierwotnego planu) Gmail **nie jest porzucany** — zostaje jako konto śmieciowe / loginy / 2FA. Stąd maile mają dwa żywe wejścia: - **Fastmail** — `source: fastmail`, adapter **IMAP** (hasło aplikacji). Primary: tu ląduje sensowna poczta na przyszłość. - **Gmail** — `source: gmail`, adapter **IMAP** (protokół, nie Gmail API → przenośność). Ciągły sync żywej skrzynki. > **Korekta 2026-08-06 — Fastmail przez IMAP, nie JMAP.** Do tej daty ten dokument (i §7, §9 > oraz §10 planu fazy mailowej) przewidywał dla Fastmaila **JMAP** i osobny `jobs/fastmail-poller`. > Zapis historyczny: *„Fastmail — adapter JMAP (read-only token)"*, 2026-06-24. > > Decyzja z 2026-08-06 (recon `kb/audits/mail-sync-2026-08-06.md` Decyzja (b), zatwierdzona > przez operatora) domyka otwartą od czerwca decyzję „unifikacja adaptera" z §9 na rzecz > **jednego wspólnego IMAP-a dla obu kont**, w jednym jobie `jobs/mail-imap-sync`. Powody: > JMAP synchronizuje po `state` — elegancko i niepotrzebnie przy jednym ticku na godzinę > i ~37 mailach na dobę, skoro UIDVALIDITY/UIDNEXT rozwiązuje ten sam problem i tak trzeba go > zaimplementować dla Gmaila; jeden adapter to jeden zestaw testów, jedna klasa błędów i jedna > ścieżka hardeningu 8-bitowych nagłówków. JMAP nie jest zamknięty na zawsze — koperta > i archiwum są protokołowo obojętne, więc wymiana transportu nie dotyka danych. Plus jednorazowy **bulk historyczny Gmaila** (eksport „All Mail" / Takeout → surowy dump do archiwum). Operacja odwracalna i niezależna od reszty pipeline'u — robimy pierwsza. Urgency spadła (konto żyje), ale historia warta zassania od razu. --- ## 3. Koperta (kontrakt zamrożony) ``` id — stabilny identyfikator wiadomości source — fastmail | gmail ts — UTC (data wiadomości) geo — null dla maili (uzupełniane cross-source w warstwie 3) raw_ref — wskaźnik do .eml w archiwum entities[] — otwarte, wypełniane przy ingeście/enrich ``` Addytywna. Nic poza tym nie usztywniamy. --- ## 4. Filtr archiwum → indeks **Archiwizuj wszystko. Indeksuj selektywnie.** Gmail śmieciowy (login/2FA/notyfikacje/newslettery) to szum — wpuszczony do wektorów zaśmieca wyszukiwanie i pali GPU na SOLARII. Filtr na wejściu do indeksu: - whitelist/blacklist nadawców i nagłówków (`List-Unsubscribe`, `Auto-Submitted`, typowe domeny powiadomień), - progi (np. odrzuć czysto automatyczne), - surowiec zawsze leży w archiwum — filtr nie kasuje, tylko decyduje co trafia do embeddingów. Filtr jest częścią indeksu (odtwarzalny), nie archiwum. --- ## 5. Indexer `parse (.eml) → chunk → embed (bge-m3 na SOLARIA/ollama) → pgvector` Retrieval hybrydowy: wektor + filtry metadanych (nadawca, zakres dat, etykieta, source). Załączniki: **II tura** (MVP = czysty tekst + nagłówki). --- ## 6. Agent maili (dedykowany, cienki) - Hybrydowy retrieval: wektor + filtry metadanych. - Wystawia tool/API, które **agent interdyscyplinarny (warstwa 4)** woła — wzorzec federacji. - Reużywa szkieletu agenta z control-plane (to samo DNA). --- ## 7. Deploy - Wszystko w `homelab-codex`, przez Git na SATURN, konwencja override `hosts//runtime//`. - Usługi: `mail-imap-sync` (Fastmail + Gmail, jeden job — korekta 2026-08-06; wcześniej planowane jako osobne `jmap-poller` + `imap-poller`), `indexer`, embed (ollama na SOLARIA), `postgres+pgvector`, `mail-agent`; bulk importer jako one-shot job. - Deploy skryptem czytającym `inventory/topology.yaml`. --- ## 8. Kolejność budowy (w obrębie projektu) 1. ✅ Zamroź kopertę + postaw Postgres+pgvector. *(2026-06-17)* 2. ✅ **Bulk Gmail historyczny → archiwum** — `jobs/gmail-bulk-import/` — **KOD GOTOWY** *(2026-06-24)*; nie uruchomiony (Takeout ~27 GB na SOLARIA, do transferu na PIHA). 3. ~~Fastmail JMAP live ingest~~ → **Fastmail IMAP live sync** → archiwum. *(korekta 2026-08-06; kod gotowy, pierwszy żywy run po stronie operatora — `kb/runbooks/mail-sync-run.md`)* 4. Gmail IMAP live sync → archiwum. *(j.w. — ten sam job `jobs/mail-imap-sync`)* 5. Filtr archiwum→indeks. 6. Indexer (parse → chunk → embed bge-m3) → pgvector. 7. Cienki agent maili + tool dla warstwy 4. --- ## 9. Decyzje otwarte (do przyklepania przed/w trakcie startu) - ✅ **Sizing Gmaila** — ZAMKNIĘTE: 225 030 kopert, archiwum ~27 GB na PIHA (Etap B, 2026-08-06). - ✅ **Unifikacja adaptera** — ZAMKNIĘTE 2026-08-06 na rzecz **jednego IMAP-a** dla obu kont (Decyzja (b) reconu, uzasadnienie w §2 wyżej). - **Sizing Fastmaila** — OTWARTE, i celowo: przesądza o tym, czy ciągniemy historię konta czy tylko przyrost. Rozstrzyga pomiar `mail-imap-sync --measure`, nie zgadywanie — `kb/runbooks/mail-sync-run.md` §5. - **Reguły filtra** — startowa lista blacklist domen/nagłówków. - Vector store: pgvector **przyklepane** (spine). - Embed model: bge-m3 **przyklepane**.