ae16deb8d3
Domkniecie Kroku 7. Realizuje Decyzje (d) reconu (host schedulera + korekta
kadencji indeksowania) i doklada dokumentacje wg konwencji OKF.
Scheduler (NIEAKTYWOWANY — wlacza operator):
- jobs/mail-imap-sync/systemd/{service,timer,run.sh} — wzorzec 1:1 z kb-ingest,
OnCalendar=hourly, Persistent=true, log do pliku (nigdy sam journal).
- hosts/piha/jobs.yaml — deklaracja jednostek host-level na PIHA. Nowy plik, bo
services.yaml jest dla kontenerow (supervisor dopasowuje jego wpisy do world-state
i wpis niekontenerowy dryfowalby wiecznie jako missing_service). Nic tego pliku
nie czyta — istnieje po to, zeby "shadow-deploy family" z otwartego pytania 5
reconu multiagentowego byla spisana, a nie tylko na nodzie.
Takt indeksowania (Decyzja (d), recon §3.3):
- kb-ingest.timer: 03:30 raz na dobe -> co 2 h. O 03:30 SOLARIA prawie na pewno spi
(potwierdzone odczytem kb_ingest_embed_skipped 1 z 2026-08-06), a tick dostaje
teraz etap mailowy: ~60 nowych chunkow na dobe pomijanych kazdej nocy sprawiloby,
ze backlog rosnie monotonicznie i KbEmbedBacklogGrowing zapala sie NA STALE.
Co 2 h zamiast stalej godziny — probe Ollamy sam wybiera okno, wiec ktorys tick
w nie trafi niezaleznie od nawykow operatora.
- cyclic_ingest: etap mailowy (mail_body_ingest --only-unchunked), import miekki,
wiec venv bez tego pakietu pomija etap zamiast wywracac wrapper. Predykat bledu
JEST luzniejszy niz wlasne main() tamtego joba i to jedyne takie miejsce w tym
wrapperze: pojedynczy trwale nieparsowalny mail nie moze zamrozic
last_success_timestamp i zapalic KbIngestStale na zawsze. Bledy per-mail sa
publikowane jako kb_ingest_mail_parse_errors, nie chowane.
Obserwowalnosc: KbMailSyncStale (6 h bez udanego ticku). Alert na cisze w skrzynce
ODRZUCONY (decyzja operatora, zgodna z reconem §3.4) — zero nowych maili to legalny
stan skrzynki, a alert zapalajacy sie na zdrowym systemie zostaje wyciszony
i przestaje dzialac wtedy, gdy jest potrzebny.
Dokumentacja:
- kb/services/job-mail-imap-sync.md (OKF), kb/runbooks/mail-sync-run.md — 9 krokow
pierwszego uruchomienia, w tym checklista 4 punktow [do weryfikacji na zywo]
z reconu (polityki dostawcow — do sprawdzenia, nie do zgadniecia) oraz pomiar
STATUS (MESSAGES) na Fastmailu, na ktorym zapada ODLOZONA decyzja o historii.
- kb-mail-pillar.md: KOREKTA JMAP -> IMAP dla Fastmaila jako decyzja 2026-08-06;
stary zapis zostaje jako historia z data. Zamkniete "unifikacja adaptera"
i "sizing Gmaila"; otwarte zostaje "sizing Fastmaila" — celowo, bo rozstrzyga
je pomiar, nie dyskusja.
- kb-m5-faza-mailowa.md: Krok 7 IN PROGRESS + tabela zakresu wdrozonego,
kb-m5-faza3.md: korekta harmonogramu i sekwencji wrappera,
pkg-kb-mail.md: rozpisany ze stubu, kb-postgres.md: lista migracji + 005.
Testy: 642 passed (calosc kb-mail, kb-retrieval i jobs). systemd-analyze verify
na timerze przechodzi, OnCalendar=0/2:00:00 normalizuje sie do co 2 h.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
129 lines
5.7 KiB
Markdown
129 lines
5.7 KiB
Markdown
---
|
|
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/<node>/runtime/<svc>/`.
|
|
- 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**.
|