00de8107ea
public (wzorce/schematy, bez IP/portow/sciezek hostow): observer, capability-model, event-system, standards, agent-operating-procedures, service-model, action-approval-model. private: recon-multiagent, fleet-inventory, fleet-inventory-verify, kb-mail-pillar, kb-documents-pillar, topology, agent-system. deprecated (martwe stuby z 2026-04-15) — visibility private wg rozstrzygniecia 6: access-model, core-stack, legacy-services-list, networking. git mv + frontmatter, tresc nietknieta. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
---
|
|
okf: "0.1"
|
|
type: subsystem
|
|
visibility: private
|
|
status: active
|
|
updated: 2026-06-24
|
|
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 **JMAP** (read-only token). 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.
|
|
|
|
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: `jmap-poller` (Fastmail), `imap-poller` (Gmail), `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 → archiwum.
|
|
4. Gmail IMAP live sync → archiwum.
|
|
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** — ile realnie waży „All Mail"? (przesądza node/dysk archiwum).
|
|
- **Unifikacja adaptera** — jeden wspólny IMAP dla Fastmail + Gmail (mniej kodu) vs JMAP dla Fastmail + IMAP dla Gmail (JMAP bogatszy)?
|
|
- **Reguły filtra** — startowa lista blacklist domen/nagłówków.
|
|
- Vector store: pgvector **przyklepane** (spine).
|
|
- Embed model: bge-m3 **przyklepane**.
|