# GraphRAG evaluácia

Aktuálny výsledok v1 a obmedzenia: [finálna správa](results/final_2026-10-24/REPORT.md).
Primárne skóre: DEV **209/286 (73,08 %)**, TEST **152/214 (71,03 %)**, bez runtime chýb.

Benchmark má 500 otázok (286 DEV, 214 TEST), schema v2. Statický audit pred finálnym TESTom odhalil 137 nesúladov očakávaní so zdrojmi. Všetky zostávajú zahrnuté v primárnom skóre. Doplnková podmnožina bez zistených nesúladov má DEV 209/209 a TEST 152/154; podrobnosti a dve zostávajúce zlyhania sú v správe.

## Reprodukcia zmrazenej evaluácie

Použi rovnaké `data/documents.json`, `data/chunks.json` a rovnaký obsah Neo4j. Odtlačky sú v `frozen_v1.json`; Git revízia wiki je vo výsledkovom JSON. Načítaj vlastné lokálne tajomstvá bez ich výpisu:

```bash
set -a
source .env
set +a

python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split test \
  --audit tools/graphrag/evaluation/results/final_2026-10-24/source_audit.json \
  --freeze-manifest tools/graphrag/evaluation/frozen_v1.json \
  --output-dir /tmp/graphrag-v1-reproduction
```

TEST/all bez manifestu sa odmietne. Overuje sa kód, benchmark, vstupné JSON súbory, obsah grafu, audit aj parametre. Zmenený obsah, neúplný holdout alebo iné parametre beh zablokujú. Výsledky neregeneruj do adresára archivovaného finálneho behu.

## Nová vývojová verzia

Ďalší vývoj musí mať vlastné výsledky a nový manifest. Už vyhodnotený TEST nepoužívaj na dolaďovanie deklarované ako nový nezávislý experiment.

```bash
python -m tools.graphrag.evaluation.audit_benchmark \
  --output /tmp/graphrag-next/source_audit.json

python -m tools.graphrag.evaluation.evaluate_graphrag \
  --split dev \
  --audit /tmp/graphrag-next/source_audit.json \
  --output-dir /tmp/graphrag-next

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

Zmrazenie vyžaduje kompletný DEV bez runtime chýb a súlad s aktuálnymi odtlačkami. Nevyžaduje predstieraných 100 % na chybne anotovanom datasete. Obsahový manifest platí aj pre zmeny, ktoré ešte nemajú commit; Git tag označuje publikovaný checkpoint.

## Metriky a dôkazy

Strict kontroluje očakávané hodnoty, typované entity, relácie, vlastnosti, zdrojové dokumenty a URL, presnú množinu pri definovaných prípadoch, správny počet pri agregácii a neorezaný výsledok. Samotné entity rozpoznané z otázky nie sú odpoveďou. `expected_paths` sú opisné anotácie a nehodnotia sa doslovným porovnaním reťazcov.

Výstup obsahuje JSON aj CSV, metriky podľa kategórie a obtiažnosti, priemer/medián/p95 latencie, čas behu, verziu Pythonu, Git revízie a obsahové odtlačky. Latencia je iba čas vyhľadávania v grafe.

## Testy

```bash
pytest -q

# Po načítaní Neo4j konfigurácie z .env:
RUN_NEO4J_TESTS=1 pytest -q tools/graphrag/tests/test_graph_search_neo4j.py
```

Neo4j testy používajú unikátny oddelený scope a rollback transakcie. Existujúce wiki dáta nemenia.