README

README.md

@@ -10,10 +10,11 @@ vytvorená RAG vrstva, ktorá pripravuje kontext, zdroje a pravidlá pre
 odpoveď jazykového modelu. API je integrované so školským OpenWebUI ako
 OpenAPI Tool Server.
 
-Súčasná hlavná retrieval vetva používa klasický hybridný RAG:
+Stabilná baseline retrieval vetva používa klasický hybridný RAG:
-FTS5/BM25 + embeddingy + RRF. GraphRAG zatiaľ nie je implementovaný;
+FTS5/BM25 + embeddingy + RRF. Nad týmto baseline sa vo vetve GraphRAG
-je preň pripravený samostatný evaluačný dataset a bude sa dopĺňať ako
+dopĺňa knowledge graph uložený v Neo4j. Aktuálne je implementovaná
-ďalšia experimentálna vetva.
+grafová infraštruktúra, deterministický builder a vizualizácia grafu;
+graph retrieval a jeho spojenie s RAG vrstvou sú ďalší krok.
 
 ## Implementované
 
@@ -60,6 +61,14 @@ je preň pripravený samostatný evaluačný dataset a bude sa dopĺňať ako
 - atomická výmena databázy po úspešnom reindexovaní,
 - persistentná Hugging Face cache v Docker volume,
 - warm-up embeddingového modelu,
+- Neo4j databáza spúšťaná ako samostatná Docker služba,
+- deterministická tvorba knowledge graphu z `documents.json` a
+  `chunks.json`,
+- grafové entity `Person`, `Document`, `Work`, `Topic`, `Category` a
+  `Author`,
+- grafové vzťahy pre dokumenty, práce, témy, kategórie a autorstvo,
+- uniqueness constraints a opakovateľný rebuild GraphRAG grafu,
+- Neo4j Browser na vizualizáciu a kontrolu vytvoreného grafu,
 - retrieval evaluácia pre FTS, embeddings a hybridný retrieval,
 - answer-level RAG evaluácia cez OpenWebUI model a RAG tool,
 - oddelené answer-level overrides bez úpravy frozen retrieval
@@ -113,6 +122,34 @@ jazykový model
 odpoveď + source_url
 ```
 
+GraphRAG vývojová vetva:
+
+```text
+documents.json + chunks.json
+  ↓
+graphrag.py
+  ↓
+build_graphrag.py
+  ↓
+Neo4j
+├── Person
+├── Document
+├── Work
+├── Topic
+├── Category
+└── Author
+  ↓
+grafové vzťahy + vizualizácia
+  ↓
+graph retrieval
+  ↓
+spojenie s klasickým RAG
+```
+
+V aktuálnom stave je implementované vytvorenie a uloženie knowledge
+graphu. Samotný graph retrieval a jeho zapojenie do `/rag` sa ešte
+dopĺňajú.
+
 Synchronizačná vetva:
 
 ```text
@@ -167,6 +204,10 @@ zp-agent/
 │   ├── build_chunks.py
 │   ├── build_sqlite_index.py
 │   ├── embedding_utils.py
+│   ├── graph_db.py
+│   ├── graphrag.py
+│   ├── build_graphrag.py
+│   ├── neo4j_smoke.py
 │   ├── rag_utils.py
 │   ├── rebuild_index.py
 │   ├── search_db.py
@@ -277,6 +318,33 @@ vyhľadávacou vrstvou.
 - normalizuje vektory,
 - poskytuje utility pre vektorové vyhľadávanie.
 
+`graph_db.py`
+
+- načítava konfiguráciu Neo4j,
+- vytvára Neo4j driver,
+- poskytuje kontrolu spojenia s grafovou databázou.
+
+`graphrag.py`
+
+- pripravuje dátový model knowledge graphu,
+- normalizuje grafové identifikátory,
+- extrahuje osoby, práce, roky, témy, kategórie a súvisiace metadata,
+- pripravuje uzly a vzťahy pre zápis do Neo4j.
+
+`build_graphrag.py`
+
+- načíta `documents.json` a `chunks.json`,
+- vytvorí GraphRAG payload,
+- vytvorí Neo4j uniqueness constraints,
+- zapíše uzly a vzťahy,
+- podporuje opakovateľný rebuild spravovanej časti grafu,
+- vypíše základné počty uzlov, vzťahov a kvalitu extrakcie názvov prác.
+
+`neo4j_smoke.py`
+
+Jednoduchý smoke test pripojenia k Neo4j používaný pri kontrole Docker
+prostredia.
+
 `search_core.py`
 
 Nízkoúrovňové jadro vyhľadávania:
@@ -420,7 +488,7 @@ ladenie frozen benchmarku.
 
 `graphrag_questions.json`
 
-Samostatný benchmark pripravený pre budúcu GraphRAG vetvu.
+Samostatný benchmark pripravený pre vývoj GraphRAG vetvy.
 
 Obsahuje 500 otázok zameraných na:
 
@@ -445,8 +513,9 @@ graph.expected_relations
 graph.expected_paths
 ```
 
-Dôležité: existencia tohto datasetu neznamená, že je GraphRAG už
+Dataset sa používa pre vývoj a neskoršie porovnanie GraphRAG vetvy.
-implementovaný. Dataset je pripravený na neskorší vývoj a porovnanie.
+Knowledge graph a jeho Neo4j vrstva sú už implementované; samotný
+graph retrieval a answer-level GraphRAG tok sa ešte dopĺňajú.
 
 `robustness_questions.json`
 
@@ -517,6 +586,12 @@ WEBHOOK_PULL_GIT=false
 # Voliteľné
 EMBEDDING_MODEL=intfloat/multilingual-e5-small
 EMBEDDING_BATCH_SIZE=32
+
+# GraphRAG / Neo4j
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=<silné lokálne heslo>
+NEO4J_DATABASE=neo4j
 ```
 
 Tajomstvá je možné vygenerovať príkazom:
@@ -569,6 +644,26 @@ docker compose down
 Hugging Face cache je uložená v persistentnom Docker volume, takže sa
 embeddingový model pri bežnom reštarte kontajnera nemusí znova sťahovať.
 
+Neo4j je spustené ako samostatná služba v rovnakom Docker Compose
+prostredí. Stav služieb je možné skontrolovať:
+
+```bash
+docker compose ps
+```
+
+Neo4j Browser je lokálne dostupný na:
+
+```text
+http://127.0.0.1:7474/browser/
+```
+
+Kontrola spojenia z API kontajnera:
+
+```bash
+docker compose exec zp-agent-api \
+  python -m scripts.neo4j_smoke
+```
+
 ## Reindexovanie
 
 Celý proces načíta dokumenty, vytvorí chunky, obnoví FTS5 index a
@@ -699,6 +794,51 @@ curl -X POST http://127.0.0.1:8000/rag \
   }'
 ```
 
+## GraphRAG
+
+GraphRAG vetva rozširuje existujúci klasický RAG o knowledge graph.
+Graf sa vytvára deterministicky z už pripravených dokumentov a chunkov
+a ukladá sa do Neo4j.
+
+Aktuálne používané hlavné typy uzlov:
+
+```text
+Person
+Document
+Work
+Topic
+Category
+Author
+```
+
+Hlavné vzťahy zahŕňajú napríklad:
+
+```text
+Person   -[:HAS_DOCUMENT]-> Document
+Person   -[:HAS_WORK]-> Work
+Work     -[:EVIDENCED_BY]-> Document
+Document -[:HAS_TOPIC]-> Topic
+Document -[:IN_CATEGORY]-> Category
+Author   -[:AUTHORED]-> Document
+Document -[:DESCRIBES]-> Topic
+```
+
+Knowledge graph sa vytvorí príkazom:
+
+```bash
+docker compose exec zp-agent-api \
+  python -m scripts.build_graphrag
+```
+
+Builder vytvára constraints, zapisuje uzly a vzťahy a pri štandardnom
+spustení obnoví iba časť grafu spravovanú ZP Agentom. Opakované
+spustenie preto nevytvára duplicitné uzly.
+
+Graf je možné vizuálne kontrolovať v Neo4j Browseri. GraphRAG zatiaľ
+nezasahuje do stabilného klasického `/rag` toku. Nasledujúca etapa
+doplní graph retrieval a následne spojenie grafového a klasického
+retrievalu.
+
 ## OpenWebUI
 
 ZP Agent je pripojený do OpenWebUI ako OpenAPI Tool Server.
@@ -891,10 +1031,9 @@ Pevný počet `pytest` výsledkov nie je v README uvádzaný, pretože sa
 s vývojom mení. Aktuálny stav sa má vždy potvrdiť novým spustením testov
 na konkrétnom commite.
 
-## Pripravené, ale zatiaľ neaktívne experimenty
+## Experimentálne datasety
 
-Nasledujúce datasety sú pripravené, ale nemajú sa teraz používať na
+Pre ďalšie experimenty sú pripravené:
-priebežné ladenie aktuálneho frozen benchmarku:
 
 ```text
 questions_extended_2000.json
@@ -903,104 +1042,53 @@ robustness_questions.json
 performance_queries.json
 ```
 
-Odporúčané poradie ich neskoršieho použitia:
+`graphrag_questions.json` je aktuálne určený pre vývoj GraphRAG vetvy.
-
+Ostatné datasety zostávajú oddelené od priebežného ladenia frozen
-```text
+klasického baseline.
-stabilný klasický RAG
-  ↓
-extended benchmark
-  ↓
-robustness benchmark
-  ↓
-GraphRAG implementácia
-  ↓
-GraphRAG benchmark
-  ↓
-performance benchmark
-  ↓
-stress test
-  ↓
-finálne experimenty
-```
 
 ## Najbližší postup
 
-Najbližšia vývojová etapa je zámerne menšia a má uzavrieť existujúci
+Klasický RAG baseline je zmrazený a GraphRAG infraštruktúra s Neo4j je
-klasický RAG pred otvorením ďalších experimentov.
+funkčná. Ďalší vývoj pokračuje nad samostatnou GraphRAG vetvou.
 
-### 1. Uzavretie retrieval/regresie
+### 1. Dokončenie kvality knowledge graphu
 
-Najprv sa má potvrdiť, že aktuálne zmeny neovplyvnili frozen retrieval
+- doplniť bezpečné fallback pravidlá pre explicitné názvy prác,
-baseline.
+- ponechať `null` tam, kde zdroj názov skutočne neuvádza,
+- doplniť regresné testy pre graph builder.
 
-Postup:
+### 2. Graph retrieval
+
+Vytvoriť vyhľadávaciu vrstvu nad Neo4j, ktorá z otázky identifikuje
+relevantné osoby, témy, kategórie, práce a roky a vráti:
 
 ```text
-py_compile
+grafové entity
-↓
+→ grafové cesty
-pytest
+→ relevantné dokumenty
-↓
+→ zdrojové chunky
-frozen retrieval DEV strict
-↓
-porovnanie s uloženým baseline
-↓
-git diff --check
-↓
-retrieval lock
 ```
 
-Do retrieval scoringu sa potom nemá zasahovať bez nového
+### 3. Spojenie s klasickým RAG
-experimentálneho dôvodu.
 
-### 2. Regresia section-lead RAG kontextu
+Grafový retrieval sa následne spojí s existujúcim FTS5 + embedding
-
+retrievalom. Klasický baseline zostane zachovaný ako samostatný
-Treba potvrdiť, že section-lead expanzia:
+referenčný bod.
-
-- opravuje prípady, kde primárny chunk chýba o názov/tému/rok,
-- nepridáva duplicitný chunk,
-- zostáva v rovnakom dokumente a sekcii,
-- nemení retrieval `max_per_document=1`,
-- nevytvára zbytočne veľký kontext.
-
-### 3. `retry + backoff + resume` pre answer evaluator
-
-Pred spustením veľkého DEV answer benchmarku sa má evaluator doplniť
-tak, aby dlhý beh nebol znehodnotený jedným timeoutom alebo dočasnou
-chybou API.
-
-Plánované správanie:
 
 ```text
-request
+query
   ↓
-úspech ───────────────→ uložiť výsledok
+├── classic retrieval
-  │
+└── graph retrieval
-  └─ timeout / 429 / 5xx
        ↓
-       retry
+   context fusion
        ↓
- exponential backoff
+      RAG
-           ↓
-       retry limit
 ```
 
-Resume mechanizmus má:
+### 4. GraphRAG evaluácia
 
-- priebežne ukladať `.partial.json`,
+GraphRAG sa bude priebežne ladiť na DEV dátach a vyhodnocovať aj na
-- pri novom spustení načítať existujúci partial výsledok,
+samostatnom `graphrag_questions.json` datasete. Až po stabilizovaní
-- overiť kompatibilitu modelu/datasetu/splitu,
+celého systému budú nasledovať širšie embeddingové, robustness a
-- preskočiť už úspešne dokončené otázky,
+performance experimenty.
-- pokračovať od ďalšej otázky,
-- neprepisovať hotové výsledky bez explicitnej voľby,
-- po úspešnom dokončení vytvoriť finálny JSON/CSV výstup.
-
-Zároveň je vhodné:
-
-- rozlišovať retryable a permanentné chyby,
-- logovať číslo pokusu a dôvod retry,
-- mať konfigurovateľný maximálny počet pokusov,
-- mať konfigurovateľný počiatočný backoff,
-- používať mierny delay medzi otázkami,
-- validovať typy answer-level datasetových polí,
-- nenačítavať osobný OpenWebUI API kľúč z fallback súboru, ak má byť
-  podľa bezpečnostnej politiky dostupný iba cez environment.