homelab-codex-ws/docs/kb/modules/05-faza4-plan.md

# Moduł 5, faza 4 — kb-query + UI (RECON + PLAN)

> Status: RECON ZAKOŃCZONY (2026-07-22), plan DO ZATWIERDZENIA. Zero kodu, zero
> deployu, zero nowych kontenerów w ramach tego zadania — wyłącznie ten dokument.
>
> Kontynuacja `05-faza3-plan.md` (faza 3: filtr śmieci, dedup, streszczenia+tagi
> [claude-haiku-4-5], kaskada retrieval [PASS, N=10/k=5], cykliczny ingest [timer
> LIVE na PIHA], wiki-proof-of-concept [5 stron w `kb-wiki`] — **DOMKNIĘTA W CAŁOŚCI**
> 2026-07-21, `docs/sessions/2026-07-21.md`). Faza 4 = pierwszy user-facing punkt
> wejścia do KB: serwis `kb-query` (FastAPI, PIHA) opakowujący `cascade_query` w
> HTTP + minimalny UI wyszukiwania pod `kb.kapala.org`. **To wyszukiwarka, nie
> chat** — synteza odpowiedzi i eskalacja to faza 5, poza zakresem tego planu.

---

## 1. Stan faktyczny (recon, zweryfikowany w repo)

### 1.1 Baza i silnik retrievalu (dziedzictwo fazy 3, gotowe do reużycia)

- `envelope`: **225 221** (gmail + paperless), `document_chunk`: **2765** aktywnych +
  wykluczonych (`excluded_reason` IS NULL vs `'ocr_junk'`/`'duplicate'`),
  `document_summary`: **162** dla `model='claude-haiku-4-5'` (157 z pilota + 5
  dogonionych przez cykliczny ingest, `docs/sessions/2026-07-21.md`).
- Silnik retrievalu **już istnieje i jest przetestowany**:
  `jobs/documents-ingest/src/documents_ingest/retrieval.py` — `flat_query` /
  `cascade_query`, obie `query_text -> chunki z dist i source`, dzielą jeden embed
  zapytania (bge-m3 przez Ollamę). `cascade_query(N=10, k=5,
  summary_model='claude-haiku-4-5')` jest domyślną ścieżką (bramka §6 fazy 3, PASS).
  Zależy wewnętrznie od `embed_chunk` i `_vector_literal` z
  `documents_ingest/chunk_embed.py` (`jobs/documents-ingest/src/documents_ingest/chunk_embed.py:207,233`)
  — `embed_chunk(session, base_url, model, text) -> (embedding, elapsed)`, POST
  `{base_url}/api/embeddings`, **bez wbudowanego timeoutu/retry** (dziedziczy z
  `aiohttp.ClientSession(timeout=...)` wołającego), `raise_for_status()` propaguje
  `aiohttp.ClientError` gdy Ollama nieosiągalna.
- Bramka jakości ma już wersjonowany eval-set (`jobs/documents-ingest/eval/queries.yaml`,
  7 zapytań + 2 kontrole negatywne) i skrypt integracyjny
  (`jobs/documents-ingest/eval/retrieval_eval.py`) wołający `flat_query`/`cascade_query`
  **bezpośrednio przez DB+Ollama** — dziś nie ma trybu HTTP (§9 poniżej).
- `envelope.id` dla `paperless:<id>` = `f"paperless:{doc['id']}"`
  (`paperless_adapter.py:126`); dla gmaila = surowy nagłówek `Message-ID` (bez `<>`)
  lub `sha256-<hash>` gdy brak nagłówka (`gmail_bulk_import/importer.py:63-70`) —
  **Message-ID jest samym `envelope.id`, nie osobną encją**. `entities` gmaila:
  jeden obiekt `{"type":"headers","from":{...},"to":[...],"subject":...,"date_raw":...}`
  (`gmail_header_backfill/backfill.py:120-128`) + `{"type":"attachment",...}` per
  załącznik. `entities` paperless: `content`/`correspondent`/`tag`/`filename`/
  `content_type`, opcjonalnie `source_mail` (link do koperty gmail).

### 1.2 Ollama / embedding

- **SOLARIA** (GPU, `services/ollama/`): `bge-m3`, zmierzone 207 ms/embed GPU.
  `availability_target: medium` — planowe wyłączenia, cykliczny ingest już to toleruje
  (probe `GET /api/tags` + pomiń, nie fail). kb-query musi to samo, ale **w torze
  interaktywnym** (użytkownik czeka), stąd aktywny fallback zamiast "pomiń i nadrób
  w nocy" (§5).
- **PIHA**: kb-postgres, brak Ollamy. Node ma **arm64, 4 rdzenie, brak akceleracji**
  (`hosts/piha/capabilities.yaml`) — słabszy punkt startowy niż SOLARIA-CPU (790 ms/embed
  zmierzone na SOLARII, prawdopodobnie x86 z szerszym SIMD; RPi5 realnie wolniej,
  nieznana dokładna wartość — do zmierzenia, §5.3).

### 1.3 PIHA — budżet RAM (istotne dla decyzji D2 / lokalnego fallbacku)

- Audyt `docs/infra/piha-slim-audit-2026-07-02.md`: po "bezpiecznym usuń"
  (elasticsearch+diskover+stary llm-gateway) available rosło z **2.9Gi do ~3.8Gi**
  (na 8 GB total, +4 GB swap). To jest **jedyna zweryfikowana liczba w repo i ma
  3 tygodnie** — od tego dnia na PIHA doszły (GitOps, z `mem_limit`): paperless+db+broker
  (≤1.9 Gi worst-case, `hosts/piha/runtime/paperless/`), vikunja+db (768m+256m),
  kb-postgres (1g), llm-gateway (256m) — suma nowych ceilingów **≈4.4 Gi**, już dziś
  potencjalnie przy/za budżetem z audytu (ceilingi to worst-case, nie wszystkie
  jednocześnie uderzają, ale to nie jest budżet z dużym zapasem).
- PIHA hostuje też **poza GitOps** (shadow, host-level): Home Assistant (`localhost:8123`,
  cel `ha-diag-agent`), Immich ("zostaje na PIHA na stałe" — decyzja audytu), Forgejo
  (origin repo + IdP OIDC), host-owy mosquitto, prometheus, **oraz najprawdopodobniej
  NPM** (`npm@PIHA` — patrz §1.4) — żadne z nich nie ma zapisanego w GitOps `mem_limit`,
  więc ich realny ślad dziś jest nieznany z samego repo.
- **Wniosek**: liczba "ile RAM naprawdę wolne na PIHA dziś" nie jest wiarygodnie
  wyprowadzalna z repo — wymaga pomiaru na żywym hoście (`free -h`, `docker stats`)
  **przed**, nie po, decyzji o domyślnym włączeniu lokalnego fallbacku embed (§5.3).

### 1.4 Wzorce serwisów webowych (npm ingress + OIDC) — z istniejących serwisów

Trzy żywe precedensy o identycznym kształcie (`services/paperless/`, `services/vikunja/`,
`services/nextcloud/`), wszystkie **`exposure: private`** mimo publicznej-brzmiącej
domeny `*.kapala.org`:

- **NPM**: nie ten z `services/npm/` (ten jest `owner_node: vps`, publiczny ingres dla
  outline/joplin/agents — "drugi npm", `docs/sessions/2026-07-07-okit-wildcard.md`
  sekcja "NIE ruszone"). Istnieje **osobna, dziś poza-GitOps instancja `npm@PIHA`**
  (cert #51 *.okit.pl, cert osobny dla *.kapala.org — sesje ją tylko konfigurują
  ręcznie/SQL-em, nigdy nie deployują z repo). kb-query dogania się do tego samego
  wzorca: nowy vhost w `npm@PIHA`, TLS z **już istniejącego** wildcard `*.kapala.org`
  (pokrywa `paper.`/`cloud.`/`vikunja.kapala.org` — `docs/kb/modules/DECYZJE-do-podjecia.md`
  #6) — **żaden nowy certyfikat nie jest potrzebny**.
- **DNS — dwie warstwy, obie trzeba dotknąć** (lekcja `okit-cloudflare-migracja.md`
  §"WAZNE: split-horizon DNS"): (a) Cloudflare rekord A → Tailscale IP PIHA
  (`100.108.208.3`), DNS Only (nie proxied) — to jest "mesh, prywatne" (poza LAN
  trzeba być na tailnecie); (b) **Pi-hole Local DNS** na PIHA (`192.168.31.5:8888`,
  poza GitOps) nadpisuje tę samą nazwę na **LAN IP** (`192.168.31.5`) dla klientów
  w domu — bez tego LAN-owy klient robi zbędny hairpin przez Tailscale zamiast iść
  bezpośrednio po LAN. Oba kroki są ręczne (UI Pi-hole / Cloudflare), nie ma ich w
  repo — to zawsze było poza automatem, kb-query nie zmienia tego wzorca.
- **OIDC — wbudowane w apkę, nigdy forward-auth.** Paperless: `django-allauth
  openid_connect` (env `PAPERLESS_SOCIALACCOUNT_PROVIDERS`). Nextcloud: appka
  `user_oidc` (occ). Vikunja: natywny `openid` provider w `config.yml`. **Nie ma w
  repo żadnego wzorca forward-auth/reverse-proxy-level auth** (NPM community edition
  go zresztą nie ma) — logowanie zawsze robi sama aplikacja. Wspólny trik trzech
  precedensów: `extra_hosts: forgejo.kapala.org:192.168.31.5` (albo `.okit.pl` dla
  starszej Vikunji) w compose, żeby discovery OIDC szło po LAN zamiast przez
  potencjalnie kapryśny publiczny DNS. kb-query jest **pierwszą usługą FastAPI w
  repo z własnym loginem** — nie ma gotowego kodu do skopiowania, tylko wzorzec
  architektoniczny do powtórzenia w nowym frameworku (§8).
- **Kontrprzykład**: `llm-gateway` (jedyny inny FastAPI na PIHA) jest
  Tailscale-only, bez OIDC, bez npm — bo to API maszyna-maszyna, nie UI dla
  człowieka. kb-query jest bliżej paperless (człowiek w przeglądarce) niż
  llm-gateway (agent po API) — stąd pełny wzorzec npm+OIDC, nie skrót.

### 1.5 Telegram (dla bonusu §10)

Istnieje już bot: `services/agent-system/telegram-bot/bot.py` — `python-telegram-bot`,
**polling** (nie webhook), token w `TELEGRAM_BOT_TOKEN`, autoryzacja przez
`TELEGRAM_ALLOWED_USER_IDS` (self-registration przez `/start`, bez hardkodowanego
chat_id). Komendy dziś: `/status /summary /nodes /services /unhealthy /incidents
/actions /help` + stub free-text fallback (`ENABLE_LLM_FALLBACK`, dziś no-op). Bot
mówi do control-plane HTTP API (`CONTROL_PLANE_URL`), nie bezpośrednio do żadnej bazy.

### 1.6 packages/ vs jobs/ — konwencja z CLAUDE.md

`packages/<lib>/` = reużywalne biblioteki bez `docker-compose.yml`/`service.yaml`,
instalowane w serwisach przez `COPY packages/<lib>/ ...; RUN pip install`
(pierwszy przykład: `packages/kb-mail/`, już zależność `documents-ingest`). `jobs/`
= joby wsadowe instalowane **na hoście** (venv, nie Docker) — `jobs/documents-ingest`
ma w `pyproject.toml` zależność na `anthropic` (streszczenia) i skrypty CLI
(`documents-ingest-*`), z których kb-query nie potrzebuje ani jednego.

---

## 2. Otwarte decyzje dla Oskara (z rekomendacjami)

### Decyzja 1 — Reużycie `retrieval.py`: import z `documents-ingest` vs wydzielenie do `packages/`

**Rekomendacja: wydzielić do nowego `packages/kb-retrieval/`** (`retrieval.py` +
`embed.py` przeniesione z `chunk_embed.py`: `embed_chunk`, `_vector_literal`,
stałe `DEFAULT_MODEL`/`DEFAULT_OLLAMA_URL`), reużywane przez **oba** konsumentów:
`jobs/documents-ingest` (dodaje `kb-retrieval` do zależności, tak jak dziś `kb-mail`)
i `services/kb-query` (Dockerfile: `COPY packages/kb-retrieval/ ...`).

Uzasadnienie:
- **kb-query to długożyjący serwis Docker, `documents-ingest` to joby venv-owe na
  hoście** (§1.6) — nie ma naturalnego sposobu, żeby Dockerfile serwisu "zaimportował"
  kod z `jobs/` bez kopiowania całego drzewa jobu do obrazu, co ciągnie za sobą
  `anthropic` (streszczenia) i CLI-skrypty, których kb-query nigdy nie użyje —
  niepotrzebnie większy obraz i węższa granica odpowiedzialności.
- **Konwencja już istnieje i jest jednoznaczna**: `packages/kb-mail` robi dokładnie
  to samo (reużywalna biblioteka bez `service.yaml`, instalowana `pip install` do
  obrazu) — `kb-retrieval` to drugi taki pakiet, nie nowy wzorzec.
- **Kod przenosi się 1:1, bez zmian logiki** — `retrieval.py` już jest napisany jako
  "dwie czyste funkcje wejściowe pod przyszłe kb-query" (docstring modułu, cytowany
  w §6.3 fazy 3) — to wydzielenie było zaplanowane, nie jest nowym pomysłem.
- Odrzucona alternatywa: zostawić w `jobs/documents-ingest` i importować przez
  `sys.path`/instalację `-e` w obrazie kb-query. Działa technicznie (eval-skrypt tak
  dziś robi, `sys.path.insert` w `retrieval_eval.py:37`), ale ciągnie `anthropic` +
  CLI do obrazu serwisu i zaciera granicę jobs/vs services z CLAUDE.md.

**Zakres migracji (krok 0, przed resztą fazy)**: `chunk_embed.py` i `summarize.py`
(via `embed_chunk`) oraz `retrieval_eval.py` przechodzą na import z `kb_retrieval`;
`documents_ingest.retrieval` zostaje jako cienki re-export **albo** usuwa się
całkiem i `pyproject.toml` dostaje zależność `kb-retrieval` — do rozstrzygnięcia
technicznie przy implementacji (re-export bezpieczniejszy, zero ryzyka złamania
importów gdzie indziej w repo; usunięcie czystsze). Definition of Done z CLAUDE.md
(build/smoke + pytest) obowiązuje dla obu paczek po migracji.

### Decyzja 2 — Aktywny fallback embed: health-check + circuit breaker + lokalny embed PIHA

Architektura (health-check → przełącznik → fallback) jest **wiążąca z roadmapy**,
rekon rozstrzyga wyłącznie *jak* zaimplementować nogę "lokalny embed na PIHA" i
konkretne wartości parametrów.

**Maszyna stanów (w pamięci procesu kb-query, jeden globalny stan `sol_status`):**

| Krok | Zachowanie | Parametr (proponowany, do kalibracji) |
|---|---|---|
| 1. Cache ważny | Użyj zapamiętanego stanu (`up`/`down`) bez sondowania | TTL **30 s** |
| 2. Cache wygasł | `GET http://solaria:11434/api/tags` | timeout **500 ms** |
| 2a. Sukces | `sol_status = up`, cache na 30 s | — |
| 2b. Timeout/błąd | `sol_status = down`, cache na 30 s (ten sam TTL — brak dowodu na
    potrzebę osobnego backoffu, uprościć aż flapping pokaże inaczej) | — |
| 3. `sol_status = up` → embed | `POST solaria:11434/api/embeddings`, twardy timeout | **3 s** |
| 3a. Sukces | Zwróć wynik | — |
| 3b. Timeout/błąd **w trakcie realnego zapytania** (nie tylko probe'a) | **Jednorazowe przełączenie**: `sol_status = down` (cache 30 s) natychmiast, **to samo zapytanie** leci do kroku 4 zamiast zwracać błąd userowi | — |
| 4. `sol_status = down` → embed | Lokalnie na PIHA, `model='bge-m3'` (ten sam co §invariant) | — |

Efekt: pojedyncze zapytanie użytkownika **nigdy nie widzi błędu z powodu SOLARII**
poza pierwszym niefortunnym trafieniem w krok 3b (jeden dodatkowy 3 s timeout raz na
30 s okno, potem cache trzyma `down` i idzie prosto do lokalnego embedu).

**Twardy inwariant (embedding query = model document_chunk.model), egzekwowany dwa razy:**
- **Przy starcie** kb-query odpytuje `SELECT DISTINCT model FROM document_chunk WHERE
  excluded_reason IS NULL AND embedding IS NOT NULL` (i analogicznie
  `document_summary`); jeśli skonfigurowany `EMBED_MODEL` (env, domyślnie `bge-m3`)
  nie jest w tym zbiorze (albo zbiór jest pusty) — **serwis odmawia startu**
  (crash-loop, widoczny przez restart w monitoringu — świadomie głośno, nie cicho).
- **Per request**: zarówno ścieżka SOLARIA jak i PIHA-fallback wołają
  `embed_chunk(..., model=EMBED_MODEL)` z **tej samej stałej konfiguracyjnej** — nie
  ma dziś (i nie planujemy w fazie 4) per-request wyboru modelu przez usera, więc
  ryzyko dryfu jest wyłącznie konfiguracyjne (ktoś zmieni `EMBED_MODEL` bez migracji
  danych) — pokryte przez check startowy. Jeśli Ollama kiedyś zacznie zwracać w
  odpowiedzi faktycznie użyty model (dziś `/api/embeddings` tego nie robi), dodać
  asercję per-response — zanotowane jako przyszłe wzmocnienie, nie blokuje fazy 4.

**Lokalny embed na PIHA — feasibility (§1.3 RAM + §1.2 CPU):**

- `bge-m3` w Ollama: model ~1.2 GB na dysku (nieznana dokładna wartość dla tego
  builda — zweryfikować `ollama show bge-m3` na SOLARII przed pull na PIHA), rezydentny
  ślad RAM podczas inferencji szacunkowo **1.5–2 GB** w trakcie burst.
  `OLLAMA_KEEP_ALIVE=0` (wymagane w zadaniu) zwalnia model z RAM **natychmiast po
  każdym zapytaniu** — to nie jest stały koszt rezydentny, tylko krótki spike
  (idle Ollama binarnie to ~100 MB), co realnie zmienia bilans na lepszy niż "drugi
  stały kontener 2 GB".
- **Ale**: spike nakłada się w czasie dokładnie wtedy, gdy inne serwisy na PIHA są
  pod obciążeniem z tego samego powodu (np. paperless fallback-OCR też się budzi,
  gdy SOLARIA śpi — ten sam trigger). Przy nieznanym dziś realnym wolnym RAM
  (§1.3) nie da się z samego repo rozstrzygnąć "czy się zmieści" z pewnością.
- **CPU**: RPi5 (arm64, brak akceleracji) vs 790 ms zmierzone na SOLARIA-CPU (prawdopodobnie
  x86 z lepszym SIMD) — realny czas na PIHA jest niezmierzony, mógłby być
  kilkukrotnie wyższy (sekundy, nie setki ms). Dla ścieżki fallback (rzadkiej,
  awaryjnej) to akceptowalne, o ile nie jest to droga domyślna.

**Rekomendacja: budować mechanizm w pełni (health-check + circuit breaker + kontener
lokalnej Ollamy na PIHA), ale gate'ować go kalibracją na żywym hoście przed
włączeniem jako cichy domyślny fallback** — dokładnie ten sam wzorzec co "kalibracja
przed backfillem" z fazy 3 §3.1 (zmierz, obejrzyj, dopiero wtedy zaufaj progowi):
1. Zbudować i zdeployować kontener `ollama-piha` (nowy, `hosts/piha/runtime/`) +
   pull `bge-m3` + zmierzyć realny czas embedu i szczyt RAM na żywym PIHA (`docker
   stats` w trakcie, kilka powtórzeń).
2. Jeśli szczyt RAM + istniejące ceilingi mieszczą się z rozsądnym zapasem (≥500 MB
   wolnego po szczycie, analogicznie do marginesu z kb-postgres/paperless) i czas
   embedu jest w pojedynczych sekundach (nie dziesiątkach) → włączyć jako domyślny
   fallback z `mem_limit` na kontenerze `ollama-piha` jako twardy ceiling (np. 2.5g,
   do potwierdzenia pomiarem) — **cgroup OOM restartuje `ollama-piha`, nie zabiera
   RAM sąsiadom** (ten sam mechanizm co reszta PIHA).
3. Jeśli nie mieści się bezpiecznie → **jedyna sensowna alternatywa to jawna
   degradacja**: kb-query zwraca `503 {"error": "wyszukiwanie chwilowo
   niedostępne — SOLARIA offline, brak zapasowego embedu"}` zamiast cicho ryzykować
   OOM na współdzielonym hoście z Home Assistant. Inny model lokalny (mniejszy,
   szybszy) **nie jest opcją** — złamałby twardy inwariant (inny model = wektory
   nieporównywalne z istniejącym indeksem). Kolejkowanie/retry też odpada — search
   jest synchroniczne, użytkownik czeka przy przeglądarce, nie ma gdzie odłożyć
   zapytania na "SOLARIA wstanie za parę godzin".
- Krok kalibracji wchodzi do planu implementacji jako osobna pozycja (§11, krok 5) —
  **werdykt (włączyć domyślnie / zostawić za flagą / zrezygnować) jest wyjściem tego
  kroku, nie założeniem tego planu.**

### Decyzja 3 — Linki do źródeł: paperless vs gmail

**Paperless**: URL do dokumentu — **do zweryfikowania na żywym Paperless przed
implementacją** (repo nie ma zapisanego przykładu, `docs/kb/modules/02-paperless-service.md`
dokumentuje tylko subdomenę, nie ścieżkę). Kandydat wg konwencji paperless-ngx UI:
`https://paper.kapala.org/documents/<id>/details` (Angular routing) — `envelope_id`
`paperless:<id>` już niesie surowy `<id>` do wstawienia. Krok implementacji: jeden
ręczny `curl -I`/otwarcie w przeglądarce na żywym paperless przed zakodowaniem
formatu linku na stałe.

**Gmail — rekomendacja: skopiowalny Message-ID + metadane koperty, zero linku
(bo nie ma dokąd linkować).** `envelope_id` **jest** Message-ID (§1.1) — nic nie
trzeba dodatkowo wyciągać. Odpowiedź `/search` dla trafienia źródła gmail niesie:
`envelope_id` (message-id), `subject`/`from`/`date` z `entities[type=headers]`
(join do `envelope.entities` przy budowaniu odpowiedzi), **oraz pole
`mail_ui_url: null`** zarezerwowane celowo (nie usunięte, nie wypełnione) — gdy
powstanie przyszły mail-UI (kb-00 etap 6, poza zakresem tej fazy), wypełnienie tego
pola to zmiana w jednym miejscu, nie nowy kontrakt API. UI: przycisk "kopiuj
Message-ID" zamiast linku (§7).

### Decyzja 4 — Frontend: osobny build czy serwowany z FastAPI

**Rekomendacja: jeden serwis, zero osobnego node-builda.** Serwer renderuje szkielet
strony (Jinja2, wbudowane w FastAPI/Starlette) + jeden statyczny plik JS (vanilla,
`fetch()` do `/search`) + jeden CSS. Żadna inna usługa webowa w tym repo nie ma
frontendowego build stepu (paperless/nextcloud/vikunja to gotowe obrazy z własnym
frontendem; `llm-gateway` to czyste API bez UI) — kb-query jest pierwszym własnym UI
w repo, więc "najprostsze co działa" bije "jak zrobiliby to profesjonalnie
zewnętrzni autorzy frameworków". Wyszukiwarka (pole + lista wyników), nie chat —
brak stanu rozmowy do zarządzania, więc vanilla JS bez frameworka jest wystarczające,
nie tymczasowe uproszczenie do wymiany później.

Odrzucona alternatywa: SPA (React/Vue) + osobny kontener/build. Dokłada node
toolchain, Dockerfile multi-stage, i najbliższy precedens w repo (agent-system webui,
`services/agent-system/`) już pokazuje że osobny frontend-kontener to więcej
ruchomych części niż potrzeba dla jednego pola wyszukiwania.

### Decyzja 5 — Ingress: potwierdzenie wzorca z §1.4

**Rekomendacja: dokładnie wzorzec paperless/nextcloud** — `exposure: private` w
`service.yaml` (mimo domeny `kb.kapala.org` — to ta sama klasa co `paper.`/`cloud.`,
patrz §1.4), LAN bind (`LAN_BIND_IP`, nigdy `0.0.0.0`), vhost w `npm@PIHA` (ręczny
krok, poza GitOps, jak zawsze), TLS z istniejącego wildcard `*.kapala.org` (zero
nowych certów), OIDC wbudowane w apkę przez `authlib` (Starlette-natywna biblioteka
OIDC-client — pierwszy raz w repo dla FastAPI, ale ten sam wzorzec co
django-allauth/user_oidc/Vikunja-natywny: apka robi login sama, nie proxy),
`extra_hosts: forgejo.kapala.org:192.168.31.5` (trik z paperless/nextcloud — nowsza
domena `kapala.org`, nie `okit.pl` jak stara Vikunja). Rejestracja OAuth2 app w
Forgejo Settings > Applications — krok wykonawczy przy deployu, jak w pozostałych
trzech serwisach.

**DNS (§1.4, dwie warstwy — obie kroki implementacji, nie automat):**
1. Cloudflare: potwierdzić że `*.kapala.org` wildcard już pokrywa `kb.kapala.org`
   (powinien — to ten sam mechanizm co `paper.`/`cloud.`/`vikunja.kapala.org`) —
   jeśli tak, **zero nowego rekordu**; jeśli z jakiegoś powodu nie, dodać A →
   `100.108.208.3` (Tailscale PIHA), DNS Only.
2. Pi-hole Local DNS (`192.168.31.5:8888`, ręcznie w UI): `kb.kapala.org` →
   `192.168.31.5` (LAN IP PIHA) — LAN klienci idą bezpośrednio, nie przez Tailscale
   hairpin. Ten sam ręczny krok co dla `paper.`/`cloud.kapala.org`.

### Decyzja 6 — Bramka jakościowa fazy 4

**Rekomendacja: rozszerzyć `retrieval_eval.py` o tryb transportu HTTP, nie pisać
nowego skryptu.** Dodać `--transport {direct,http}` (domyślnie `direct`, zachowuje
dzisiejsze zachowanie) + `--base-url` dla trybu `http`, który woła `GET
kb-query/search?q=...&mode=cascade` zamiast bezpośrednio `cascade_query`. Kryterium:
**identyczne** (nie ±epsilon) `dist` dla trybu HTTP vs `direct` na tym samym żywym
SOLARII — to ta sama baza i ten sam kod, HTTP to tylko opakowanie, więc różnica
oznacza bug w serializacji/handlerze, nie w retrievalu.

**Test fallbacku (osobny, nowy przypadek — nie rozszerzenie powyższego):**
symulacja sol-down (np. tymczasowo błędny `OLLAMA_URL` w konfiguracji testowej kb-query,
albo zablokowanie portu 11434 do SOLARII na czas testu) → potwierdzenie że kb-query
przełącza się na lokalny embed PIHA i zwraca wyniki. Tu **±epsilon jest uzasadnione**
(nie identyczność) — SOLARIA-GPU i PIHA-CPU to dwa różne uruchomienia tego samego
modelu `bge-m3`, drobne różnice numeryczne w zmiennoprzecinkowej arytmetyce między
backendami są oczekiwane i nieszkodliwe (kolejność wyników top-k powinna być
identyczna, `dist` może różnić się w czwartym-piątym miejscu po przecinku).

### Decyzja 7 — Bonus: bot telegramowy

**Rekomendacja: doczepić `/kb <pytanie>` do istniejącego procesu
`services/agent-system/telegram-bot/`, nie nowy bot.** Reużywa: token bota, listę
`TELEGRAM_ALLOWED_USER_IDS`, pętlę pollingu — nowa komenda to jeden
`CommandHandler` wołający `GET kb-query/search` (HTTP, jak §"Decyzja 6" wyżej) i
formatujący top-3 z progami dystansu jako emoji (🟢/🟡/🔴, ten sam schemat co UI §7)
+ `envelope_id`/link źródła. **Wymaga**: kb-query osiągalny z hosta, na którym stoi
`agent-system` (dziś nieustalone z repo, gdzie dokładnie ten serwis biega — do
sprawdzenia przy implementacji; jeśli nie na PIHA, potrzebny dostęp po Tailscale,
analogicznie do `llm-gateway` osiągalnego jako `http://piha:8080`). Koszt: niski —
głównie okablowanie (jeden handler + jeden HTTP call), zero nowej infrastruktury,
zero nowego tokena. Szacunek: **0.5 sesji**, warunkowane tym że kb-query już stoi
i ma HTTP endpoint gotowy do wołania — nie robić równolegle z rdzeniem fazy 4.

---

## 3. Krok implementacji 0 — pakiet `packages/kb-retrieval`

Poprzedza wszystko inne (§2 Decyzja 1). Zakres:
- `packages/kb-retrieval/src/kb_retrieval/embed.py` — `embed_chunk`, `_vector_literal`,
  `DEFAULT_MODEL`, `DEFAULT_OLLAMA_URL` przeniesione z `chunk_embed.py` bez zmiany
  logiki. Dodać (nowe, potrzebne kb-query): `async def check_ollama_health(session,
  base_url, timeout_s) -> bool` (probe `/api/tags`) — generyczna, żeby health-check
  z §2 Decyzji 2 nie duplikował logiki HTTP.
- `packages/kb-retrieval/src/kb_retrieval/retrieval.py` — `flat_retrieve`,
  `cascade_retrieve`, `flat_query`, `cascade_query` przeniesione 1:1.
- `jobs/documents-ingest`: `pyproject.toml` dostaje zależność `kb-retrieval` (wzorem
  `kb-mail`); `chunk_embed.py`, `summarize.py`, `documents_ingest/retrieval.py`
  (re-export albo usunięcie — decyzja techniczna przy implementacji) przechodzą na
  import z `kb_retrieval`.
- `jobs/documents-ingest/eval/retrieval_eval.py`: import z `kb_retrieval` zamiast
  `documents_ingest.retrieval`.
- Testy: `packages/kb-retrieval/tests/` przejmuje istniejące testy z
  `jobs/documents-ingest/tests/test_retrieval.py` (mocki, bez żywej bazy). Definition
  of Done z CLAUDE.md: build/smoke + pytest dla obu paczek po migracji, żywy przebieg
  `retrieval_eval.py` na końcu jako regression check (te same wyniki co przed
  migracją — to czysty refactor, zero zmiany zachowania).

**Szacunek: 0.5 sesji.**

---

## 4. Krok 1 — serwis `services/kb-query` (szkielet)

Layout wg CLAUDE.md (`docker-compose.yml`, `service.yaml`, `README.md`,
`env.example`, `healthcheck.sh`) + `Dockerfile` (wzorem `llm-gateway`:
`python:3.12-slim`, `COPY packages/kb-mail/ packages/kb-retrieval/ ...; pip install`,
`uvicorn app.main:app`).

`service.yaml`: `owner_node: piha`, `exposure: private`, `dependencies: [kb-postgres,
forgejo]` (`ollama` na SOLARII jest zewnętrzny/opcjonalny — health-checkowany w
runtime, nie hard dependency, zgodnie z tolerancją na SOLARIA-offline z §1.2).

Endpointy:
- `GET /healthz` — `{"status": "ok"}` + (opcjonalnie) `sol_status` z cache (§2
  Decyzja 2) dla widoczności operacyjnej, wzorem `llm-gateway` `/`.
- `GET /search?q=<text>&mode=cascade|flat` (domyślnie `cascade`) — `query_text ->
  embed -> cascade_query/flat_query -> odpowiedź`:
  ```
  {
    "query": "...", "mode": "cascade", "sol_status": "up",
    "results": [
      {
        "envelope_id": "paperless:119", "source": "paperless",
        "dist": 0.3418, "chunk_index": 2, "text": "...",
        "link": "https://paper.kapala.org/documents/119/details"
      },
      {
        "envelope_id": "<Message-ID>", "source": "gmail",
        "dist": 0.44, "chunk_index": 0, "text": "...",
        "subject": "...", "from": "...", "date": "...",
        "link": null, "mail_ui_url": null
      }
    ]
  }
  ```
  `source` wyprowadzone z `envelope_id`/`envelope.source` (join do `envelope` po
  `chunks[].envelope_id` — potrzebny w kb-query, `retrieval.py` dziś zwraca tylko
  `document_chunk`, nie robi joina do `envelope`; to jest nowy kod w warstwie
  HTTP-handlera kb-query, nie zmiana w `kb_retrieval`).

`mem_limit`: FastAPI+uvicorn, ślad podobny do `llm-gateway` (~256m) — kontener
kb-query sam jest lekki; ciężar (jeśli włączony) jest w osobnym kontenerze
`ollama-piha` (§5), nie tutaj.

**Szacunek: 1 sesja** (endpoint + join do envelope + response shape + testy z mockiem DB).

---

## 5. Krok 2 — aktywny fallback embed

Implementacja maszyny stanów i inwariantu z §2 Decyzja 2. Podkroki:

1. Health-check + cache + circuit breaker w kb-query (używa `check_ollama_health`
   z `kb_retrieval.embed`, §3).
2. Walidacja startowa modelu (`SELECT DISTINCT model FROM document_chunk/document_summary`).
3. Nowy kontener `ollama-piha` (`hosts/piha/runtime/ollama-piha/` **lub** nowy wpis w
   `services/` jeśli traktowany jako pełny serwis GitOps — do rozstrzygnięcia: to
   jest infrastrukturalny dodatek specyficzny dla PIHA, prawdopodobnie bliżej
   `services/ollama/` sklonowanego z `owner_node: piha` + `OLLAMA_KEEP_ALIVE=0` niż
   czegoś nowego). `ollama pull bge-m3` na PIHA.
4. **Kalibracja na żywym PIHA** (gate, nie formalność — analogicznie do sweep N z
   fazy 3 §6.3): kilka pomiarów czasu embedu + `docker stats` w trakcie, przy
   normalnym obciążeniu PIHA (nie w oknie ciszy nocnej) — realistyczny worst case.
5. **Werdykt** (wyjście kalibracji, wejście do decyzji Oskara): włączyć jako
   domyślny fallback / zostawić za flagą `KB_QUERY_LOCAL_FALLBACK_ENABLED` (domyślnie
   off, włączany po dodatkowej obserwacji) / zrezygnować na rzecz jawnej degradacji
   503 (§2 Decyzja 2, pkt 3).

**Szacunek: 1–1.5 sesji** (zależnie od werdyktu kalibracji — degradacja 503 jest
prostsza niż domyślnie-włączony fallback z pełnym mem_limit tuningiem).

---

## 6. Krok 3 — linki do źródeł

Paperless: weryfikacja formatu URL na żywym hoście (§2 Decyzja 3) → stała w kodzie
z komentarzem skąd pochodzi (wzorzec z fazy 3 dla progów kalibrowanych). Gmail:
pola `subject`/`from`/`date`/`mail_ui_url: null` w response shape (§4). Zero nowego
schematu bazy — czyste odczyty z `envelope.entities`.

**Szacunek: 0.5 sesji** (część kroku 1, wydzielona tu tylko dla czytelności planu).

---

## 7. Krok 4 — frontend minimalny

Jedna strona (Jinja2 template + vanilla JS + CSS, serwowane z tego samego FastAPI,
§2 Decyzja 4):

- Pole zapytania + submit (Enter albo przycisk).
- Wyniki grupowane po `envelope_id` (dokument), w obrębie dokumentu chunki
  posortowane po `dist`.
- Kolorowanie progów (progi z fazy 3, `docs/kb/modules/05-faza3-plan.md` §1.2,
  zweryfikowane bramką): `dist < 0.45` zielony, `0.45–0.55` żółty, `> 0.55` —
  **nie renderować wyniku**, tylko komunikat "brak odpowiedzi w KB" (żółta/czerwona
  strefa nadal renderuje wynik z ostrzeżeniem wizualnym; czerwona = brak sensownego
  trafienia, więc nic konkretnego do pokazania poza samym komunikatem).
- Link źródła (paperless) / przycisk "kopiuj Message-ID" (gmail) — §6.
- Przełącznik kaskada/flat (debug) — parametr `mode` do `/search`, checkbox/select
  w UI, domyślnie `cascade`.

**Szacunek: 1 sesja.**

---

## 8. Krok 5 — ingress (npm@PIHA, OIDC, DNS)

Wg §2 Decyzja 5:

1. `authlib` w zależnościach kb-query; endpointy `/login`, `/auth/callback`, sesja
   przez cookie (podpisany, `SessionMiddleware` Starlette) — chroni `/search` i UI,
   `/healthz` zostaje bez auth (musi odpowiadać monitoringowi bez loginu).
2. Rejestracja OAuth2 app w Forgejo (Settings > Applications) — client_id/secret do
   `.env` kb-query (gitignored, jak wszędzie).
3. `extra_hosts: forgejo.kapala.org:192.168.31.5` w compose.
4. Deploy kontenera, LAN bind (`LAN_BIND_IP`).
5. Nowy vhost w `npm@PIHA` (ręcznie, UI) → `kb.kapala.org` → `192.168.31.5:<port>`,
   certyfikat = istniejący wildcard `*.kapala.org`.
6. DNS: potwierdzić pokrycie wildcardem Cloudflare (prawdopodobnie zero akcji) +
   Pi-hole Local DNS override `kb.kapala.org` → `192.168.31.5` (ręcznie, UI).
7. Weryfikacja end-to-end: z LAN i z poza LAN (przez Tailscale), login przez
   Forgejo, sesja trzyma.

**Szacunek: 1 sesja** (głównie integracja OIDC od zera w nowym frameworku — jedyny
krok bez bezpośredniego kodu-precedensu do skopiowania, tylko wzorca architektury).

---

## 9. Krok 6 — bramka jakościowa fazy 4

Wg §2 Decyzja 6:
1. `retrieval_eval.py --transport http --base-url http://piha:<port>` → identyczne
   `dist` vs `--transport direct` na tych samych 7+2 zapytaniach z `queries.yaml`.
2. Nowy test fallbacku (symulacja sol-down) → wyniki z PIHA-embedu, `dist` w
   granicach epsilon (do ustalenia empirycznie z kalibracji §5, prawdopodobnie
   rzędu 1e-3–1e-2) względem baseline z SOLARII, **kolejność top-k identyczna**.
3. **Kryterium ukończenia fazy**: oba testy PASS + UI ręcznie zweryfikowany na
   żywo (Definition of Done z CLAUDE.md wymaga też testu UI w przeglądarce dla
   zmian frontendowych, nie tylko pytest).

**Szacunek: 0.5–1 sesja** (zależnie od tego, ile iteracji wymaga dostrojenie
epsilon w teście fallbacku).

---

## 10. Krok 7 (bonus, opcjonalny) — bot telegramowy

Wg §2 Decyzja 7. **Nie wchodzi do kryterium ukończenia fazy 4** — osobna decyzja
Oskara po zobaczeniu działającego kb-query, czy warto. Zaimplementować dopiero po
§9 (wymaga stabilnego, przetestowanego `/search`).

**Szacunek: 0.5 sesji**, warunkowo.

---

## 11. Poza zakresem fazy 4

| Temat | Gdzie zakotwiczone | Kiedy |
|---|---|---|
| Synteza odpowiedzi (LLM nad wynikami retrievalu) + polityka eskalacji | kb-00, `05-faza3-plan.md` §8.1 inwariant 2 | faza 5 |
| Wiki (`kb-wiki`) jako trzeci poziom kaskady w wynikach wyszukiwania | `05-faza3-plan.md` §8.1 inwariant 5 | po automatyzacji kompilacji (faza 5+) |
| Batching wywołań Ollamy (embed) | `05-faza3-plan.md` §9 backlog | faza mailowa |
| Mail-UI (klikalny link dla trafień gmail, `mail_ui_url`) | kb-00 etap 6 (mail-indexer) | osobny moduł, poza kb-query |
| Multi-model retrieval UI (przełącznik modelu streszczeń, gdyby powstał drugi tor kompilacji) | `05-faza3-plan.md` §2 Decyzja 3 | zależne od decyzji o modelu fazy mailowej |
| Writeback / edycja danych z poziomu UI kb-query (to wyszukiwarka read-only) | — | nie planowane |
| Aktualizacja `hosts/solaria/capabilities.yaml` (model GPU) | finding recon fazy 3 §1.3 | drobny osobny task, nietknięty |

---

## 12. Plan implementacji (kolejność = zależności)

| # | Krok | Zależy od | Szacunek |
|---|---|---|---|
| 0 | `packages/kb-retrieval` — wydzielenie z `documents-ingest`, migracja importów, testy | — | 0.5 sesji |
| 1 | Szkielet `services/kb-query` (Dockerfile, `/healthz`, `/search` bez fallbacku, join do `envelope`) | 0 | 1 sesja |
| 2 | Linki do źródeł (paperless URL zweryfikowany, gmail metadata) | 1 | 0.5 sesji |
| 3 | Frontend minimalny (jedna strona, kolorowanie progów, toggle cascade/flat) | 1 | 1 sesja |
| 4 | Aktywny fallback embed: health-check + circuit breaker + inwariant modelu | 1 | 0.5 sesji (mechanizm) |
| 5 | Kalibracja lokalnego embedu na żywym PIHA → werdykt (włącz/flaga/degradacja) | 4 | 0.5–1 sesja + pomiar na żywo |
| 6 | Ingress: OIDC (`authlib`), npm@PIHA vhost, DNS (Cloudflare confirm + Pi-hole) | 1, 3 | 1 sesja |
| 7 | Bramka jakości: HTTP-equivalence test + fallback test (epsilon) | 2, 4, 5 | 0.5–1 sesja |
| 8 | Bonus: `/kb` w telegram-bot | 7 (opcjonalny, po ukończeniu fazy) | 0.5 sesji |

Kroki 2 i 3 mogą iść równolegle po kroku 1. Krok 6 (ingress) niezależny od kroków
4–5 (fallback) — może iść równolegle, o ile krok 3 (frontend) jest gotowy do
podpięcia za auth.

**Kryterium ukończenia fazy 4**: (a) `kb-query` odpowiada na `/search` przez
`kb.kapala.org` z działającym OIDC, (b) bramka §9 PASS (HTTP-equivalence +
fallback), (c) UI ręcznie zweryfikowany w przeglądarce (golden path + brak
wyniku + toggle cascade/flat), (d) werdykt kalibracji fallbacku udokumentowany
(nawet jeśli werdykt to "degradacja 503, nie lokalny embed" — to jest ważny,
udokumentowany wynik, nie porażka planu).

---

## 13. Szacunki zbiorcze

- **Czas sesyjny**: ~6–7.5 sesji roboczych (tabela §12, bez bonusu telegram) +
  0.5 sesji jeśli bonus wchodzi.
- **Nowa infrastruktura**: 1 nowy serwis (`kb-query`, PIHA), opcjonalnie 1 nowy
  kontener (`ollama-piha`, warunkowo po kalibracji), 1 nowy vhost npm (ręczny), 1
  nowa OAuth2 app w Forgejo, 0 nowych certów TLS, 0 nowych domen do rejestracji
  (wildcard już pokrywa).
- **Koszty zewnętrzne**: brak nowych kosztów API (kb-query nie woła Anthropic —
  to jest granica z fazą 5, synteza nie retrieval).
- **Ryzyko RAM na PIHA**: jedyny istotny nieznany parametr tego planu (§1.3) —
  wymaga pomiaru na żywym hoście przed krokiem 5, nie da się rozstrzygnąć z repo.

---

## 14. Podsumowanie dla Oskara

Silnik retrievalu (kaskada, bramka, progi) jest gotowy od fazy 3 — faza 4 to
**warstwa dostępu**: HTTP + UI + auth + fallback, żadnej nowej logiki wyszukiwania.
Największa realna niewiadoma to nie retrieval, tylko **RAM na PIHA** dla lokalnego
fallbacku embedu — plan świadomie nie przesądza "włączyć czy nie", tylko buduje
mechanizm i każe go zmierzyć na żywo przed zaufaniem mu jako domyślnej ścieżce
(ten sam odruch co kalibracja filtra śmieci w fazie 3). Druga realna nowość to
OIDC we własnym kodzie FastAPI — wzorzec (apka robi login sama, nie proxy) jest w
repo trzykrotnie potwierdzony, ale kb-query jest pierwszym Pythonowym/FastAPI
przypadkiem, więc to pierwsza taka integracja, nie kopiuj-wklej.

**7 decyzji w §2, wszystkie z rekomendacjami**; jedyna naprawdę otwarta (zmienia
przebieg planu w zależności od wyniku) to D2 — werdykt kalibracji lokalnego
fallbacku (krok 5) decyduje, czy faza kończy się z pełnym aktywnym fallbackiem czy
z udokumentowaną jawną degradacją. D1, D3–D7 to rekomendacje techniczne do
przyklepnięcia.

Nic nie zostało zaimplementowane, zdeployowane ani pobrane w ramach tego recon —
wynik to wyłącznie ten dokument.