homelab-codex-ws/docs/sessions/2026-07-27-kb-f4-fallback.md

Sesja 2026-07-27 — KB faza 4: fallback embed SOLARIA→PIHA (krok 3, ostatni element rdzenia)

Dopisek redakcyjny (2026-07-30, dedup — docs/kb/modules/05-fallback-dedup-raport.md): implementacja kodu z tej sesji (app/fallback.py, branch task/kb-f4-fallback, 3d4ee38) została porzucona — do mastera weszła równoległa, szersza implementacja tego samego kroku planu (e7625cd, app/embed_router.py, 2026-07-29) i to ona biega na PIHA. Ten log wciągnięto do repo, bo dokumentuje fakty operacyjne niezależne od porzuconego kodu: znalezisko i wyłączenie osieroconego natywnego ollama.service na PIHA (§3, z backlogiem odinstalowania ≈2026-08-10), kalibrację live ollama-piha z werdyktem GO (§4 — konfiguracja kontenera identyczna na masterze, pomiar przenosi się) oraz metodologię i baseline bramki §9 (§5, Δ~3e-4). Wyniki bramki i testu sol-down dotyczyły kodu z brancha — na wdrożonym masterze wymagają powtórki (raport dedup, follow-up (b)). Sekcje o deployu (§6) i "Do zrobienia przez operatora" pkt 1–2 opisują stan sprzed merge'a e7625cd — historyczne. Z delty brancha uratowano ponadto: retrieval_eval.py --transport http (plan §2 D6/§9) i luki testowe T1/T2 przeniesione do test_embed_router.py.

Zakres: docs/kb/modules/05-faza4-plan.md §2 decyzja 2 / §5 — aktywny fallback embedu, ostatni brakujący element rdzenia fazy 4 (frontend i ingress LIVE od 2026-07-22/23, docs/sessions/2026-07-23-kb-f4-ingress.md). Zero zmian w schemacie DB, zero zmian w kb_retrieval's retrieval logice — wyłącznie warstwa embed + health.

Praca wykonana w task worktree (task/kb-f4-fallback, .claude/skills/worktree-aware). Zgodnie z ustaleniem na starcie sesji (patrz "Ustalenia proceduralne" niżej): kod napisany i przetestowany lokalnie w worktree, produkcyjne kroki (kalibracja, deploy, live-test) wykonane po jawnej zgodzie operatora, z osobnym potwierdzeniem przed każdym kolejnym krokiem dotykającym PIHA/SOLARIĘ.

Ustalenia proceduralne

Zadanie wprost wymagało kroków produkcyjnych (kalibracja RAM/latencji na żywym PIHA, symulacja sol-down dotykająca SOLARII, deploy, push) — sprzeczne z ogólną dyscypliną worktree-aware ("nigdy nie uruchamiaj deployów/healthchecków przeciw produkcji z worktree"). Zamiast rozstrzygać to samodzielnie, zapytano operatora:

1. Recon read-only (bez zmian stanu) — zgoda bez pytania.
2. Właściwe kroki produkcyjne (kalibracja, deploy, live-test, push) — operator potwierdził jawnie ("Yes, proceed with all of it") po zobaczeniu pełnego zakresu.

1. Kod (warstwa embed + health, zero zmian retrievalu/DB)

• packages/kb_retrieval/embed.py: embed_chunk dostał opcjonalny timeout_s (domyślnie None, zero zmiany zachowania istniejących wołań) — potrzebny do twardego 3 s timeoutu na nodze SOLARIA bez zmiany zachowania nogi PIHA.
• services/kb-query/app/fallback.py (nowy): SolCircuitBreaker (cache 30 s, zegar wstrzykiwalny do testów) + resolve_sol_status (probe /api/tags, 500 ms) + embed_with_fallback (SOLARIA z twardym 3 s timeoutem → jednorazowe przełączenie na PIHA w tym samym requeście przy timeout/błędzie → PIHA bez dodatkowego timeoutu). Dokładnie maszyna stanów z planu §2 decyzja 2.
• app/search.py: run_search liczy embedding raz przez embed_with_fallback, potem woła flat_retrieve/cascade_retrieve/hybrid_retrieve (niskopoziomowe funkcje kb_retrieval, biorą gotowy wektor) zamiast flat_query/cascade_query/ hybrid_query (które embedują same) — dzięki temu decyzja fallbacku żyje wyłącznie w warstwie HTTP kb-query, zero zmiany w kb_retrieval. sol_status w odpowiedzi to teraz realny wynik, nie zahardkodowane "up".
• app/main.py: /healthz i /search dzielą jeden SolCircuitBreaker (app.state.sol_breaker) — oba endpointy zawsze zgadzają się co do aktualnego stanu. Nowy env OLLAMA_PIHA_URL (domyślnie http://localhost:11434 — celowo "inertny" placeholder, fail-closed, dopóki operator nie ustawi realnego adresu).
• Inwariant modelu: nie dodano drugiego, per-request sprawdzenia w DB — EMBED_MODEL to jedna stała wątkowana przez obie nogi embed_with_fallback, więc startowy check (app/startup.py, niezmieniony) pokrywa obie ścieżki z konstrukcji. Dodanie drugiego DB-checka chroniłoby przed scenariuszem, który nie może wystąpić (CLAUDE.md: nie dodawaj walidacji dla scenariuszy, które nie mogą się zdarzyć) — zamiast tego nowy test (test_both_legs_use_identical_embed_model) strukturalnie dowodzi, że obie nogi w tym samym requeście dostają identyczny embed_model.
• jobs/documents-ingest/eval/retrieval_eval.py: dodano --transport {direct,http} + --base-url (plan §2 decyzja 6 / §9) — dotąd nieistniejące (tylko ręczny smoke-test, docs/sessions/2026-07-23-kb-f4-ingress.md follow-up). Tryb http woła trzy GET /search (flat/cascade/hybrid) na żywym kb-query zamiast embedować+odpytywać lokalnie; envelope.source do kryterium 4 bierze się z pola source w odpowiedzi JSON, nie z osobnego zapytania do DB. Nie da się swipe'ować N przez HTTP (kb-query serwuje jeden N per request) — tryb http raportuje tylko przy --gate-n.

2. Nowy serwis services/ollama-piha

Klon wzorca services/ollama (owner_node: piha zamiast solaria, bez rezerwacji GPU — PIHA to arm64 bez akceleracji), OLLAMA_KEEP_ALIVE=0 (model ładowany tylko na czas requestu). mem_limit: 2560m (tentatywny wg planu, potwierdzony pomiarem — patrz §3). Wpisany do hosts/piha/services.yaml (depends_on.local kb-query → [kb-postgres, ollama-piha], fallback nie jest twardą zależnością na starcie).

3. Znalezisko: osierocony natywny ollama.service na PIHA

Podczas pierwszej próby deployu ollama-piha (bind 127.0.0.1:11434) — konflikt portu. Okazało się, że PIHA ma natywny (nie-Docker) systemd ollama.service (v0.6.1, enabled, działający od 2026-06-22, PATH env wskazujący na użytkownika /home/pi/...), o którym nic nie wiadomo w repo — plan §1.2 wprost zakładał "PIHA: brak Ollamy", co okazało się nieaktualne/błędne. To realna sprzeczność planu z rzeczywistością → STOP, pytanie do operatora zamiast cichej decyzji.

Weryfikacja przed jakąkolwiek akcją: journalctl -u ollama --since "7 days ago" — tylko własne, właśnie wykonane zapytania probe (/api/version, /api/tags), total blobs: 0 od startu (nigdy nic nie pobrano). Operator potwierdził: martwy balast, sudo systemctl disable --now ollama.service (disable, nie uninstall — odwracalne). Port 11434 zwolniony, ollama-piha wystartował normalnie.

Backlog: PIHA host-level shadow — natywny ollama.service wyłączony 2026-07-27; odinstalować binarkę/unit po ~2 tygodniach jeśli nic się nie posypie.

4. Kalibracja (plan §5, gate) — werdykt: GO

Zmierzone na żywym PIHA pod normalnym obciążeniem (kb-postgres, paperless, Immich, HA, Forgejo działające, nie okno nocnej ciszy), 3 kolejne wywołania /api/embeddings po ollama pull bge-m3:

Wywołanie	Latencja
1 (pierwsze, zimny start)	5.25 s
2	4.41 s
3	4.16 s

Brak przyspieszenia między wywołaniami — zgodnie z projektem (OLLAMA_KEEP_ALIVE=0 zwalnia model po każdym requeście, ollama ps pokazuje zero rezydentnych modeli między wywołaniami).

RAM: baseline idle ~66 MiB, szczyt podczas burst ~983 MiB (docker stats, próbkowane co 0.3 s w trakcie 3 wywołań) — komfortowo w granicach ceilingu 2560m. free -h systemowe: available nie spadło poniżej ~1.3 GiB w trakcie, osiadło na ~4.2 GiB po (dla porównania: przed startem eksperymentu available = 3.7 GiB).

Werdykt: oba kryteria planu spełnione (latencja pojedyncze sekundy, nie dziesiątki; RAM ze sporym zapasem) → włączony jako domyślny fallback, bez flagi KB_QUERY_LOCAL_FALLBACK_ENABLED.

5. Bramka jakościowa (plan §9)

Wszystko uruchomione z ~/kb/venv na PIHA (istniejący venv z poprzednich sesji, aiohttp/asyncpg/yaml już obecne) przeciw żywej bazie + żywemu kb-query.

HTTP-equivalence (--transport http vs --transport direct, SOLARIA up, ten sam --gate-n 10): oba PASS, 0 rozbieżności w dist na wszystkich zapytaniach (flat_top1_dist, hybrid_top1_dist, cascade[10].top1_dist) — identyczne bit w bit, jak wymagał plan (nie ±epsilon, bo to ten sam kod, HTTP to tylko opakowanie).

Live sol-down fallback test: symulacja przez OLLAMA_URL=http://solaria:1 (zły port, zgodnie z rekomendacją planu — zero dotknięcia SOLARII/innych konsumentów Ollamy) w .env kb-query, restart kontenera. /healthz → sol_status: "down". /search → 200, wyniki z PIHA, ~4.3 s (zgodnie z kalibracją). Pełna bramka retrieval_eval.py --transport http z SOLARIA-down: PASS — identyczny wzorzec hit@3 co na SOLARII, dist w granicach epsilon:

Zapytanie	dist (SOLARIA)	dist (PIHA fallback)	Δ
1	0.341780	0.341509	0.000271
2	0.324808	0.324858	0.00005
3	0.428898	0.429184	0.000286
4	0.448199	0.447903	0.000296
5	0.386901	0.386816	0.000085
N (negative control)	0.598301	0.598017	0.000283
N2 (negative control borderline)	0.529772	0.529530	0.000242

Maksymalna rozbieżność: ~3e-4 — rząd wielkości mniejszy niż oczekiwany przez plan (1e-3–1e-2), kolejność top-k identyczna, wynik bramki (gate.passed) identyczny. Kb-query przywrócony do normalnej konfiguracji po teście (.env z prawdziwym OLLAMA_URL, restart), /healthz z powrotem sol_status: "up".

6. Deploy

Kod nie był jeszcze zmergowany do master (dyscyplina worktree: agent nigdy nie mergeuje/pushuje master) — deploy przez standardowy deploy-node.sh niedostępny bez mastera. Zamiast tego: rsync zmienionych plików (packages/kb-retrieval, services/kb-query, services/ollama-piha, hosts/piha/runtime/ollama-piha, hosts/piha/services.yaml, jobs/documents-ingest/eval/retrieval_eval.py + README) do żywego checkoutu ~/homelab-codex-ws na PIHA (bez zmiany brancha — working tree pozostaje na master z niescommitowanym diffem 1:1 identycznym z tą gałęzią), potem standardowy docker compose ... up -d --build z tego miejsca. Efekt: realny, działający deploy, ale repo na PIHA ma dziś dirty working tree — wymaga domknięcia (patrz "Do zrobienia przez operatora" niżej).

Zweryfikowane: kb-query (healthy), ollama-piha (healthy, bge-m3 w wolumenie), curl https://kb.kapala.org/healthz → 200 {"sol_status":"up"}, curl https://kb.kapala.org/search?q=test → 200.

Stan na koniec sesji

Element	Status
packages/kb-retrieval — embed_chunk(timeout_s=...)	✅ kod + testy
services/kb-query/app/fallback.py — maszyna stanów	✅ kod + testy (38/38 kb-query, 25/25 kb-retrieval)
services/ollama-piha — nowy serwis GitOps	✅ zdefiniowany, ✅ LIVE na PIHA
Natywny ollama.service na PIHA (osierocony)	✅ wyłączony (nie odinstalowany)
Kalibracja RAM/latencja	✅ zmierzone — werdykt GO
retrieval_eval.py --transport http	✅ zaimplementowane, ✅ PASS na żywo
Live sol-down fallback test	✅ PASS, Δ~3e-4
Deploy kb-query + ollama-piha na PIHA	✅ LIVE, working tree PIHA dirty (patrz niżej)
Merge do master	⛔ nie wykonany (dyscyplina worktree — operator)

Do zrobienia przez operatora

1. Merge task/kb-f4-fallback → master (scripts/dev/agent.sh merge albo ręcznie) — branch popchnięty do origin/task/kb-f4-fallback (patrz commit poniżej).
2. Na PIHA: cd ~/homelab-codex-ws && git status będzie dirty (diff identyczny z tym commitem, bo już wdrożony ad-hoc przez rsync w tej sesji) — po mergu do mastera, git checkout -- . (working tree już ma dokładnie tę treść) albo zwyczajnie git pull po mergu powinien wylądować "already up to date"/no-op, bo pliki na dysku już są zgodne z tym co przyjdzie z mastera. Zweryfikować git diff jest puste po pull, nie zakładać.
3. Backlog: natywny ollama.service na PIHA wyłączony systemctl disable --now 2026-07-27 (§3 wyżej) — jeśli nic się nie posypie przez ~2 tygodnie, odinstalować binarkę/unit całkiem.
4. OIDC dla kb-query nadal odłożone (decyzja z 2026-07-23) — nie w zakresie tej sesji.