# GraphRAG evaluácia

Aktuálna opravená verzia je **v3**. [Finálna správa](results/final_v3_2026-10-25/REPORT.md) uvádza výsledky aj ich obmedzenia.

- DEV/regresia: **589/589**.
- Posledný doplnkový TEST: **13/13**, iba dva úplne nové profily a obmedzené kategórie.
- Širší nezávislý TEST v2 pred finálnymi opravami: **67/80**. Je archivovaný a jeho otázky sa po odhalení chýb stali DEV.
- Celá testovacia sada: **430 passed, 4 skipped**.

Tieto čísla neznamenajú 100 % všeobecnú správnosť kódu. Vyhľadávanie sa hodnotí bez generovania odpovede LLM.

## Reprodukcia aktuálnej zmrazenej verzie

Použi zodpovedajúci kód, rovnaké pôvodné wiki súbory, vstupné JSON 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/v3_preparation/source_audit.json \
  --freeze-manifest tools/graphrag/evaluation/frozen_v3.json \
  --output-dir /tmp/graphrag-v3-reproduction
```

V1 a v2 sú zachované v pôvodných adresároch s manifestmi a Git tagmi `graphrag-v1-frozen` a `graphrag-v2-frozen`. Na ich reprodukciu treba zodpovedajúcu verziu kódu a grafu; aktuálny upravený kód úmyselne neprejde kontrolou starého manifestu. Originálny klasický RAG ostáva samostatným referenčným experimentom.

## Referenčné údaje a ďalší vývoj

`graphrag_questions.json` je pôvodných 500 otázok. V2 opravila 137 nesúladov: 128 nepravdivých predpokladov o tagoch a 9 množín kategórií. Pravidlá a každá zmena majú zdrojový záznam v `results/v2_preparation/legacy_corrections.json`.

`source_oracle.py` číta pôvodný Markdown nezávisle od grafového buildera. `benchmark_v2.py` vytvára opravenú regresiu a pôvodný profilovo oddelený v2 holdout. `benchmark_v3.py` presúva všetky vystavené v2 prípady do DEV, opravuje projekt/práca anotácie a rezervuje posledné nepoužité profily. Nový vývoj musí mať novú verziu, nové výstupy a primerane nezávislý holdout. Archivované datasety neregeneruj na mieste.

```bash
# Príklad vývoja na existujúcom datasete do nového adresára:
python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split dev --audit tools/graphrag/evaluation/results/v3_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/v3_preparation/source_audit.json \
  --output /tmp/graphrag-next/frozen.json
```

Samotné ďalšie spustenie toho istého TESTu je reprodukcia, nie nové nezávislé vyhodnotenie. Existujúce freeze manifesty a finálne výstupy sa neprepisujú.

## Čo hodnotí strict

Správne hodnoty musia patriť tej istej osobe/práci a mať prepojené typované dôkazy. Overuje sa význam roku, názov a typ práce, relácie, zdrojové alternatívy a URL, presné množiny a počet, explicitné no-answer/ambiguous a neorezaný výsledok. Rozpoznaná hodnota z otázky sama nie je dôkazom. Schema3 používa strojovo overované väzby a vzory ciest; textové `expected_paths` pôvodnej schema2 sú historické anotácie.

## Testy

```bash
pytest -q
# Po načítaní .env:
RUN_NEO4J_TESTS=1 pytest -q
```

Neo4j integračné testy používajú izolovaný scope a rollback. Výsledky obsahujú JSON aj CSV, kategórie, obtiažnosti, priemer/medián/p95, Git revízie, Python a obsahové odtlačky.