# GraphRAG evaluácia

Aktuálna verzia je **v7**, tag `graphrag-v7-frozen`.
[Správa v7](results/final_v7_2026-10-26/REPORT.md): graf DEV 1 046/1 046,
nový query-group TEST 80/80, model DEV 46/46, finálne odpovede TEST 80/80
(prvý pokus 77/80). Všetkých 591 testov prešlo. Stará regresia má 319/320;
jeden nepodložený modelový názov sa nedoručil. TEST sa neprekrýva so žiadnou odhalenou query skupinou;
korpus, ľudia a šablóny sú známe. Dve kategórie majú len 2 a 7 nových skupín.

CLI vyžaduje explicitné `--questions`, `--audit`, `--freeze-manifest`
(pri TESTe) a nový výstupný adresár. Použite `graphrag_questions_v7.json`,
`results/v7_preparation/source_audit.json`, `frozen_v7.json`.
Generátor `benchmark_v7` vytvára otázky jednorazovo z raw zdrojov, bez
predikcií. Odstránil sa odhad začiatku štúdia z adresára, nie nedokumentované
otázky z merania. [Príkazy a postup](../../../docs/graphrag_v7_2026-10-26_worklog.md).

## Historická v6

Historická verzia je **v6**, tag `graphrag-v6-frozen`.
[Finálna správa v6](results/final_v6_2026-10-25/REPORT.md) oddeľuje grafový
DEV 722/722, regresiu 320/320 a generované odpovede modelu.
Generovanie má strict **316/320 (98,75 %)**; všetkých **565 testov** prešlo.
Benchmark v6 ponecháva všetkých 1 042 otázok, ich ID a rozdelenie. Opravuje
15 očakávaní po priamom čítaní zdrojov; generický odkaz „rešerš“ nie je názov
akademického projektu. Všetky staršie dáta a výsledky ostávajú zachované.
Modelový DEV má 42 známych otázok; finálna regresia obsahuje všetkých 320.

Použite `--questions tools/graphrag/evaluation/graphrag_questions_v6.json`,
`--audit tools/graphrag/evaluation/results/v6_preparation/source_audit.json`
a `--freeze-manifest tools/graphrag/evaluation/frozen_v6.json`.
[Postup, kontroly a zdrojová vzorka](../../../docs/graphrag_v6_2026-10-25_worklog.md).
Kontrola vzorky je AI kontrola; ľudské posúdenie je pripravené v CSV, neprebehlo.
Ročník adresára sa pri chýbajúcom explicitnom začiatku štúdia používa ako
náhradná konvencia, nie ako nezávislý administratívny doklad.

## Historická v5.1

Historická verzia je **v5.1**, tag `graphrag-v5.1-frozen`.
[Finálna správa](results/final_v5_1_2026-10-25/REPORT.md) a
[strojový súhrn](results/final_v5_1_2026-10-25/summary.json) oddeľujú
vyhľadávanie, zdrojovú kontrolu všetkých vrátených typovaných faktov a generovanie.

- Graf DEV: **722/722**.
- Graf historická regresia: **320/320**, vrátane kontroly nadbytočných faktov.
- Generovanie: 39 vopred deklarovaných DEV a finálna regresia všetkých 320
  historických otázok. Finálny výsledok: **317/320 (99,06 %)**, bez chýb JSON
  a bez opravného požiadavku. Všetky tri zlyhania zostávajú započítané.
- Kompletné automatizované testy: **525 passed, 4 skipped**.

Všetky otázky sú už známe. V5.1 je regresia, nie nový nezávislý TEST; finálna
regresia generovania obsahuje aj 39 DEV otázok. Pôvodné gold ani výsledky sa
nemenili. Prvá iterácia v5 (319/320) zostáva uložená a má overený zdrojový patch.

Reprodukcia v5.1 vyžaduje zodpovedajúci release checkout, raw wiki, JSON vstupy
aj graf podľa manifestu. Používajte vždy nový výstupný adresár:

```bash
python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split test \
  --audit tools/graphrag/evaluation/results/v5_1_preparation/source_audit.json \
  --freeze-manifest tools/graphrag/evaluation/frozen_v5_1.json \
  --output-dir /tmp/graphrag-v5-1-reproduction
```

Nové zmrazenie po vývoji používa kompletný DEV a `--purpose historical_regression`.
Odtlačky zahŕňajú spoločné moduly aj efektívnu publikačnú politiku. Každý reálny
DEV výsledok musí prejsť nezávislou kontrolou všetkých vrátených typovaných faktov.
Pri ďalšom nezávislom experimente treba nové, vopred zdrojovo overené otázky.

## Historický protokol v4

Nasledujúce merania a príkazy opisujú pôvodnú v4. Na reprodukciu použite jej
pôvodný checkout/graf; aktuálny kód nezodpovedá odtlačkom frozen_v4.

Historická zmrazená verzia je **v4**. [Finálna správa](results/final_v4_2026-10-25/REPORT.md) obsahuje protokol, výsledky a obmedzenia.

| Meranie grafového vyhľadávania | Správne | Úspešnosť |
|---|---:|---:|
| DEV/regresia v4 | 722/722 | 100,00 % |
| Širší TEST v4 | 320/320 | 100,00 % |

Cieľ ≥92 % grafového vyhľadávania bol splnený v prvom finálnom behu. TEST má desať kategórií, 288 kladných a 32 záporných otázok, bez runtime chýb. Osoby aj korpus sú známe; nové sú otázky a kombinácie faktov. Logické skupiny ani normalizované otázky sa medzi DEV a TEST neprekrývajú. Výsledok neznamená všeobecnú 100 % správnosť na ľubovoľnom vstupe.

Generovanie odpovedí dosiahlo **281/300 (93,67 %)** na novom externom TESTe; 20 DEV otázok malo 19/20. Všetkých 19 zlyhaní vrátane 7 neplatných JSON odpovedí ostáva započítaných. Doplnkový audit všetkých vrátených grafových kontextových faktov má **319/320 (99,69 %)**; strict 320/320 neznamená pravdivosť každej nadbytočnej hodnoty. Najslabšia LLM kategória je názov + tag (21/30).

Samostatne sa hodnotí generovanie odpovedí cez školské OpenWebUI API po dodaní skutočného grafového kontextu. [Protokol generovania](../../answer_evaluation/README.md) oddeľuje 20 DEV a 300 nových LLM TEST výstupov. Natívny výber nástrojov hlavným agentom je ďalší blok projektu.

## Reprodukcia zmrazeného grafu

Použi zodpovedajúci kód, rovnakú pôvodnú wiki, JSON vstupy a obsah Neo4j podľa manifestu. Súkromné kľúče ostávajú v `.env`.

```bash
set -a
source .env
set +a
python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split test \
  --audit tools/graphrag/evaluation/results/v4_preparation/source_audit.json \
  --freeze-manifest tools/graphrag/evaluation/frozen_v4.json \
  --output-dir /tmp/graphrag-v4-reproduction
```

Existujúce finálne výstupy a manifesty sa neprepisujú. Opakované spustenie rovnakého TESTu je reprodukcia, nie nové nezávislé overenie. Ak sa podľa odhalených TEST chýb ladí ďalšia verzia, tieto otázky sú od tej chvíle DEV.

## Zdrojový benchmark a história

- `graphrag_questions.json`: pôvodných 500 otázok. V2 opravila 137 nesúladov (128 tagových predpokladov a 9 neúplných množín kategórií). Zmeny sú v `results/v2_preparation/legacy_corrections.json`.
- V2: 509 DEV a 80 profilovo oddelených TEST otázok; finálny TEST 67/80 (83,75 %). Po odhalení sa stal regresiou.
- V3: 589 DEV a 13 **nových** doplnkových otázok vytvorených z pôvodných dokumentov posledných dvoch neodhalených profilov. Nešlo o výber trinástich z pôvodných 500. Meranie prebehlo interným skriptom nad Neo4j bez OpenWebUI či LLM. DEV 589/589, malý TEST 13/13; obmedzené pokrytie neumožňovalo tvrdiť všeobecnú 100 % presnosť.
- V4: 722 DEV (602 historických + 120 nových), 320 nových TEST skupín nad všetkými známymi profilmi. `source_oracle.py` číta raw Markdown oddelene od buildera. `benchmark_v4.py` nepoužíva výsledky vyhľadávania pri tvorbe očakávaní ani výbere otázok. Kontrola surových zdrojov doplnila 45 zmien/rozšírení historických väzieb názvov; záznamy a mapovanie ID sú v `results/v4_preparation/`.

V1–v3 ostávajú v pôvodných adresároch s manifestmi a tagmi `graphrag-v1-frozen`, `graphrag-v2-frozen`, `graphrag-v3-frozen`. Na reprodukciu treba ich pôvodný kód a graf. Percentá rôznych verzií nie sú kontrolovaným porovnaním identických otázok. Klasický RAG a jeho referenčné experimenty ostávajú samostatné.

## Strict a zmrazenie

Správne hodnoty patria tej istej osobe/práci a majú prepojené typované dôkazy. Overuje sa význam roku, názov a typ práce, relácie, kategória a autor toho istého dokumentu, zdrojové alternatívy a URL, presné množiny a počet, explicitné no-answer a neorezaný výsledok. Rozpoznaná hodnota z otázky sama nie je dôkazom. Schema3 overuje strojové vzory ciest, nie iba textový zoznam očakávaných trás.

Freeze vyžaduje kompletný DEV, nulové runtime chyby, platný zdrojový audit a odtlačky kódu, otázok, pôvodných súborov, JSON vstupov, grafu a parametrov. V4 explicitne deklaruje prekryv 72 profilov a nulový prekryv logických skupín. Starší režim profilovo oddeleného holdoutu zostáva zachovaný.

Oracle aj evaluator sú pravidlové. Priama kontrola pôvodných riadkov a stratifikovaná kontrola anotácií nie sú náhradou nezávislej ľudskej anotácie celého datasetu.

## Vývoj ďalšej verzie

Generátory historických v1–v4 neregeneruj na pôvodných miestach. Nové dáta, manifesty a merania potrebujú nové cesty/verziu. `benchmark_v4 --extra-exposed` vie vyradiť ďalšie odhalené skupiny, ale množstvo nových zdrojových prípadov je konečné a kvóty sa nesmú meniť podľa úspechu vyhľadávania.

```bash
python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split dev --audit tools/graphrag/evaluation/results/v4_preparation/source_audit.json \
  --output-dir /tmp/graphrag-next
python -m tools.graphrag.evaluation.freeze_graphrag \
  --dev-results /tmp/graphrag-next/graphrag_dev.json \
  --audit tools/graphrag/evaluation/results/v4_preparation/source_audit.json \
  --output /tmp/graphrag-next/frozen.json
```

Záverečná kompletná automatizovaná sada: **448 passed, 4 skipped** (vrátane nových testov generovania). Neo4j integračné testy používajú izolovaný scope a rollback. Výsledky obsahujú úplné JSON/CSV a odtlačky pre reprodukciu.