commit 156925c689bc86a6b0326023f2ff2a7423d2ef5b Author: oskar Date: Tue Jul 21 15:42:02 2026 +0200 struktura: katalogi, konwencje, README Szkielet kb-wiki wg docs/kb/modules/05-faza3-plan.md §8.2 (homelab-codex-ws, read-only stąd): typy stron jako katalogi (podmioty/osoby/sprawy/umowy/tematy), _meta/conventions.md (frontmatter z blokiem sources, format przypisów [^envelope_id#chunk_id], zasady flagowania sprzeczności i wersji dokumentów, zasady lintu), README z ostrzeżeniem że treść jest LLM-kompilowana. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..9c78cb0 --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# kb-wiki + +Warstwa pamięci domowej bazy wiedzy (moduł 5, faza 3 — `homelab-codex-ws`, +`docs/kb/modules/05-faza3-plan.md` §8). Wzorzec: Karpathy llm-wiki +(gist `karpathy/442a6bf555914893e9891c11519de94f`). + +## Czym to jest + +Dwuwarstwowa architektura KB: + +- **Warstwa dowodowa** (`kb-postgres@PIHA`, poza tym repo): RAG/pgvector na + chunkach dokumentów — skala docelowa 225k+ kopert, zawsze lokalna, zawsze + źródło prawdy. +- **Warstwa pamięci** (to repo): strony-encje w Markdownie (firma, umowa, + sprawa, temat), kompilowane **z wyników retrievalu**, nie z surowców — + destylat, nie kopia. + +## ⚠️ Treść jest kompilowana przez LLM + +Każda strona w tym repo została napisana przez model językowy (Claude) na +podstawie wyników zapytań do kaskady retrievalu (streszczenia + chunki z +`kb-postgres`), **nie przez człowieka czytającego oryginalne dokumenty**. +Fakty liczbowe i identyfikujące mają przypisy `[^envelope_id#chunk_id]` +wskazujące źródłowy chunk — **weryfikuj przypis przy każdej decyzji, która +się na tej stronie opiera** (finansowej, prawnej, ubezpieczeniowej). Sprzeczne +źródła są flagowane jawnie w tekście, nie ukrywane, ale kompilacja może mimo +to pominąć niuans, którego model nie uznał za istotny. + +## Jak działa kompilacja + +1. Zapytanie po polsku trafia do kaskady retrievalu (`documents_ingest.retrieval`, + pakiet z `homelab-codex-ws/jobs/documents-ingest`): embed (bge-m3, Ollama) + → top-N `document_summary` (model `claude-haiku-4-5`) → top-k + `document_chunk` w obrębie tych kopert, zawsze `WHERE excluded_reason IS NULL`. +2. Sesja CC/API dostaje zwrócone chunki + streszczenia, pisze/aktualizuje + stronę Markdown: fakty wyłącznie ze źródeł, przypis inline przy każdym + fakcie liczbowym/identyfikującym, blok `sources` we frontmatterze agregujący + wszystkie użyte koperty. +3. Commit do `master` z opisem `compile: ← ` — historia + commitów tego repo **jest** audytowalną historią kompilacji (inwariant 6 + szkicu operatora), stąd commitowanie bezpośrednio na `master`, bez task + branchy (inny reżim niż `homelab-codex-ws`, patrz uzasadnienie niżej). + +Format stron, konwencje linkowania i zasady lintu: `_meta/conventions.md`. + +## Dlaczego osobne repo, nie katalog w homelab-codex-ws + +Decyzja D7 planu fazy 3: inna klasa wrażliwości (ten wiki jest destylatem danych +osobistych — zdrowie, finanse, umowy — `homelab-codex-ws` to kod infry) i inny +cykl commitów (kompilator commituje często i maszynowo; w repo infry zaśmiecałoby +to historię i gryzłoby się z dyscypliną worktree tamtego repo). Git history tutaj += darmowy audit trail kompilacji, czystszy gdy w historii są wyłącznie strony wiki. + +## Status + +Proof-of-concept fazy 3: struktura + `_meta/conventions.md` + 3–5 stron-encji +skompilowanych ręcznie sesją CC z wyników retrievalu. Pełna kompilacja korpusu +(225k+ kopert, przyrostowo) i integracja stron wiki z retrievalem jako +trzeci poziom kaskady — poza zakresem tej fazy, patrz plan §8.2 i §9. diff --git a/_meta/conventions.md b/_meta/conventions.md new file mode 100644 index 0000000..dc56111 --- /dev/null +++ b/_meta/conventions.md @@ -0,0 +1,150 @@ +--- +title: Konwencje kb-wiki +type: meta +status: active +tags: [] +sources: [] +compiled_by: claude-sonnet-5 +compiled_at: 2026-07-21 +updated_at: 2026-07-21 +--- + +# Konwencje kb-wiki + +Ten dokument definiuje format stron tej wiki. Rozwinięcie decyzji architektonicznych +z `homelab-codex-ws`, `docs/kb/modules/05-faza3-plan.md` §8 (szkic operatora, NIE +zmieniamy stamtąd decyzji — tylko doprecyzowujemy wykonanie). To repo jest read-write +tylko dla kompilatora (CC/API); baza źródłowa (`kb-postgres@PIHA`) jest zawsze +read-only z tej strony. + +## Struktura katalogów + +Typy stron = katalogi; płasko wewnątrz każdego, graf robią linki `[[...]]`, nie +hierarchia plików. + +| Katalog | Zawartość | +|---|---| +| `podmioty/` | Firmy i instytucje: ubezpieczyciele, banki, urzędy — encje trwałe, nie procesy | +| `osoby/` | Tożsamości/aliasy osób fizycznych | +| `sprawy/` | Procesy w czasie: sezony, remonty, procesy decyzyjne, porównania ofert | +| `umowy/` | Konkretne, zawarte kontrakty/polisy — jeden dokument prawny lub jego wersje | +| `tematy/` | Przekrojowe kategorie łączące wiele podmiotów/spraw (np. „ubezpieczenia auto”) | +| `_meta/` | Ten plik, raporty lintu | + +Wybór katalogu dla nowej strony: jeśli encja to firma/instytucja → `podmioty/`; +jeśli to coś co się dzieje/działo w czasie (sezon, spór, zakup) → `sprawy/`; jeśli to +konkretna umowa prawna → `umowy/`; jeśli łączy wiele podmiotów pod wspólnym parasolem +tematycznym → `tematy/`. + +## Frontmatter + +```yaml +--- +title: +type: podmiot # podmiot | osoba | sprawa | umowa | temat | meta +status: active # active | archived +tags: [ubezpieczenie] # słownik wspólny z jobs/documents-ingest/tags-vocab.yaml + # (homelab-codex-ws) — nie wymyślamy nowego słownika dla wiki +sources: + - envelope_id: paperless:119 + chunks: [4211, 4213] # document_chunk.id (klucz PK), NIE chunk_index + - envelope_id: "CABtrY-...@mail.gmail.com" + chunks: [] # koperta bez chunków (np. sam manifest) +compiled_by: claude-sonnet-5 # model/sesja, która skompilowała/ostatnio zmieniła stronę +compiled_at: 2026-07-20 # data pierwszej kompilacji +updated_at: 2026-07-20 # data ostatniej zmiany +--- +``` + +`sources` agreguje **wszystkie** koperty, z których cokolwiek na stronie pochodzi — +niezależnie od tego, ile razy dana koperta jest cytowana w treści. To jest poziom +audytu „skąd strona czerpie w ogóle”; poziom „ten konkretny fakt” robią przypisy +inline (niżej). + +## Przypisy inline i cytowanie faktów + +Każdy fakt liczbowy lub identyfikujący (kwota, data, numer polisy/umowy, adres, +próg punktowy) dostaje przypis w miejscu użycia: + +```markdown +składka 1 234 zł/rok [^paperless:119#4212] +``` + +Format: `[^#]`. Jeden fakt może mieć więcej niż +jeden przypis, jeśli potwierdzają go niezależnie różne chunki/koperty — wtedy oba +się wypisuje: `[^paperless:14#965][^paperless:22#2081]`. + +Fakty opisowe/narracyjne (np. „PZU oferuje kilka wariantów ubezpieczenia") niosące +niską specyficzność mogą dzielić jeden przypis na koniec akapitu zamiast przypisu +po każdym zdaniu — przypis jest obowiązkowy per sekcja, nie per zdanie, ale musi +dawać się prześledzić do konkretnego chunka. + +**Zakaz dopowiadania**: jeśli fakt nie występuje w żadnym pobranym chunku/streszczeniu, +strona pisze wprost „brak danych w KB" zamiast go zgadywać z wiedzy ogólnej modelu. + +## Sprzeczności między źródłami + +Gdy dwa dokumenty (typowo: dwie wersje tego samego OWU z różnymi datami +obowiązywania, albo dwie oferty konkurencyjne) podają różne wartości dla tego +samego faktu, strona **nie wybiera cicho jednej wersji**. Sprzeczność jest +flagowana jawnie w tekście, z obiema wartościami i obu przypisami, np.: + +```markdown +Udział własny w AC: 300 zł wg OWU obowiązującego od 21.03.2026 [^paperless:14#871], +ale 500 zł wg wcześniejszej wersji OWU [^paperless:17#XXXX] — **rozbieżność między +wersjami, nie literówka**; przy sporze o odszkodowanie decyduje wersja obowiązująca +w dniu zdarzenia. +``` + +## Wersjonowanie dokumentów źródłowych + +Ubezpieczenia i regulaminy w korpusie mają wielokrotne wersje z różnymi datami +„obowiązuje od". Strona encji **nie kompiluje jednej płaskiej prawdy** — jeśli +źródła mają rozbieżne daty obowiązywania, strona wymienia wersje osobno (np. +podsekcja per data) zamiast nadpisywać starszą nowszą bez adnotacji. To był +konkretny finding z pilota dedupa (`docs/kb/eval/retrieval-pilot-2026-07-16.md`, +`docs/kb/modules/05-faza3-plan.md` §3.2) — dokumenty bywają też **duplikatami +binarnymi** (`excluded_reason='duplicate'` w bazie), co jest czymś innym niż +kolejna wersja: duplikat pomijamy w kompilacji (baza już to wyklucza z retrievalu), +wersję z inną datą obowiązywania — nie. + +## Linkowanie między stronami + +`[[nazwa-pliku-bez-rozszerzenia]]` — link do innej strony wiki po nazwie pliku +(bez katalogu, nazwy plików są unikalne w całym repo). Linkujemy tam, gdzie treść +się faktycznie styka (wspólny podmiot, wspólna sprawa, przywoływany dokument) — +nie tworzymy linków na wyrost do stron, które jeszcze nie istnieją, chyba że +świadomie oznaczamy brakujące pojęcie (patrz niżej), bo taki link psuje inwariant +lintu „brak stron-sierot i wiszących linków" dopóki strona docelowa nie powstanie. + +## Brakujące pojęcia (przyszłe strony) + +Jeśli podczas kompilacji natrafiamy na encję wartą osobnej strony, ale poza +zakresem bieżącej kompilacji (np. inny ubezpieczyciel wspomniany punktowo, inna +sprawa), **nie tworzymy linku `[[...]]`** do niej (byłby wiszący). Zamiast tego +kandydatka trafia do listy „brakujące pojęcia" w najbliższym raporcie lintu +(`_meta/lint-reports/`), żeby nie zgubić się w wątku. + +## Zasady lintu + +Okresowy lint (ręczny w tej fazie, `_meta/lint-reports/YYYY-MM-DD.md`) sprawdza: + +1. **Strony-sieroty** — strona bez żadnego linku przychodzącego z innej strony + (poza `INDEX.md`, który z definicji linkuje do wszystkiego). +2. **Wiszące linki** — `[[cel]]` bez odpowiadającego pliku `cel.md` w repo. +3. **Brakujące pojęcia** — encje wspomniane w treści (nie w linku) a nieopisane + osobną stroną; kandydaci na przyszłe strony, nie błąd. +4. **Spot-check** — dla losowej próbki przypisów `[^envelope_id#chunk_id]` + weryfikacja, że treść chunka w bazie faktycznie potwierdza przywołany fakt. +5. **Sprzeczności międzystronicowe** — ten sam fakt o tej samej encji opisany + różnie na dwóch stronach (nie mylić z rozbieżnością międzywersyjną w obrębie + jednej strony, która jest już jawnie flagowana w treści per wyżej). + +## Integracja z retrievalem (poza zakresem tej fazy) + +Docelowo strony wiki wchodzą do `kb-postgres` jako koperty `source='wiki'` +(`id='wiki:/'`), embedowane tym samym pipeline'em co chunki +dokumentów — kaskada retrievalu rozszerza się wtedy o trzeci poziom: wiki → +streszczenie → chunk. Nie jest to realizowane w tej fazie (proof-of-concept +ręcznej kompilacji 3–5 stron) — patrz `docs/kb/modules/05-faza3-plan.md` §8.2 +w `homelab-codex-ws` po szczegóły. diff --git a/_meta/lint-reports/.gitkeep b/_meta/lint-reports/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/osoby/.gitkeep b/osoby/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tematy/.gitkeep b/tematy/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/umowy/.gitkeep b/umowy/.gitkeep new file mode 100644 index 0000000..e69de29