ZP Agent

Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom záverečných prác zpwiki.

Projekt načítava Markdown dokumenty, spracuje YAML metadata, rozdelí obsah na tokenové chunky a vytvorí SQLite index kombinujúci FTS5 fulltextové vyhľadávanie a embeddingy. Nad hybridným vyhľadávaním je 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.

Stabilná baseline retrieval vetva používa klasický hybridný RAG: FTS5/BM25 + embeddingy + RRF. Nad týmto baseline sa vo vetve GraphRAG dopĺňa knowledge graph uložený v Neo4j. Aktuálne je implementovaná grafová infraštruktúra, deterministický builder a vizualizácia grafu; graph retrieval a jeho spojenie s RAG vrstvou sú ďalší krok.

Implementované

• načítanie Markdown súborov a YAML front matter,
• normalizácia názvov, autorov, tagov, kategórií a published,
• tokenové chunkovanie pomocou tiktoken,
• konfigurovateľná maximálna veľkosť chunku, overlap a minimálna veľkosť chunku,
• zachovanie názvu dokumentu a hierarchie nadpisov v chunku,
• SQLite databáza a FTS5 fulltextový index,
• BM25 vyhľadávanie s podporou diakritiky a prefixových výrazov,
• vyhľadávacie stratégie all_terms, prefix_terms a any_term,
• embeddingy pre každý chunk pomocou modelu intfloat/multilingual-e5-small,
• uloženie embeddingov priamo v SQLite,
• vektorové vyhľadávanie pomocou cosine similarity,
• hybridné vyhľadávanie FTS5 + embeddings pomocou RRF,
• nižšia váha pre slabú any_term FTS stratégiu,
• lexikálne zvýhodnenie presných alebo veľmi silných zhôd,
• obmedzenie počtu výsledkov z jedného dokumentu pomocou max_per_document,
• filtrovanie publikovaných dokumentov,
• generovanie source_url pre dohľadateľnosť výsledkov,
• RAG vrstva s pripraveným kontextom, zdrojmi a pravidlami pre grounded odpoveď,
• rozšírenie RAG kontextu o začiatok rovnakej sekcie (section-lead expansion) bez globálneho zvýšenia max_per_document,
• pravidlá proti používaniu neoverených informácií a zamieňaniu rôznych typov údajov,
• no-answer správanie pri chýbajúcej alebo nedostatočne podloženej informácii,
• FastAPI endpointy /health, /rag, /search, /sync a /webhook/gitea,
• striktná validácia API vstupov,
• autorizácia vyhľadávania pomocou X-API-Key alebo Bearer tokenu,
• autorizácia /sync pomocou samostatného API kľúča,
• CORS konfigurácia pre OpenWebUI,
• bezpečnostné HTTP hlavičky,
• integrácia s OpenWebUI cez OpenAPI Tool Server,
• Gitea webhook s HMAC-SHA256 podpisom, limitom veľkosti payloadu a kontrolou udalosti a repozitára,
• zámok proti súbežnému reindexovaniu,
• 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 benchmarku,
• príprava rozšírených datasetov pre extended RAG, GraphRAG, robustness a performance experimenty.

Architektúra

zpwiki
  ↓
Markdown + YAML
  ↓
scan_zpwiki.py
  ↓
normalizované dokumenty
  ↓
build_chunks.py
  ↓
tokenové chunky
  ↓
build_sqlite_index.py
  ↓
SQLite
├── dokumenty
├── metadata
├── chunky
├── FTS5
└── embeddingy
  ↓
search_core.py / search_utils.py
  ↓
hybridné vyhľadávanie
├── FTS5 / BM25
├── embeddingové vyhľadávanie
└── RRF fusion + lexical anchor
  ↓
rag_utils.py
├── výber zdrojov
├── section-lead expansion
├── RAG kontext
└── grounding pravidlá
  ↓
FastAPI /rag
  ↓
OpenWebUI / ZP Agent
  ↓
jazykový model
  ↓
odpoveď + source_url

GraphRAG vývojová vetva:

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:

Gitea push
  ↓
POST /webhook/gitea
  ↓
HMAC + repository + event validácia
  ↓
voliteľný git pull --ff-only
  ↓
rebuild_index.py
  ↓
nový SQLite index
  ↓
atomická výmena databázy

Evaluačná vetva:

evaluation/json_files/*.json
  ↓
retrieval evaluator / RAG answer evaluator
  ↓
runner
  ↓
metriky
  ↓
evaluation/results/

evaluation/results/ nie je v nižšie uvedenom stromčeku, pretože obsahuje generované výstupy experimentov.

Štruktúra projektu

Nižšie je funkčná štruktúra projektu. Testovacie súbory, generované výsledky, cache, __pycache__, Git interné súbory a podobné pomocné artefakty sú zámerne vynechané.

zp-agent/
├── app/
│   ├── main.py
│   ├── routes.py
│   └── security.py
│
├── scripts/
│   ├── common.py
│   ├── scan_zpwiki.py
│   ├── 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
│   ├── search_core.py
│   └── search_utils.py
│
├── evaluation/
│   ├── evaluate_retrieval.py
│   ├── retrieval_runner.py
│   ├── metrics.py
│   ├── evaluate_rag_answers.py
│   ├── rag_runner.py
│   ├── rag_metrics.py
│   └── json_files/
│       ├── questions.json
│       ├── questions_before_ambiguity_cleanup.json
│       ├── questions_before_validation.json
│       ├── rag_answer_overrides.json
│       ├── questions_extended_2000.json
│       ├── graphrag_questions.json
│       ├── robustness_questions.json
│       └── performance_queries.json
│
├── data/
│   ├── documents.json
│   ├── chunks.json
│   └── zp_index.sqlite
│
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── requirements-dev.txt
└── README.md

app/

app/main.py

• vytvára FastAPI aplikáciu,
• nastavuje lifespan aplikácie,
• validuje bezpečnostnú konfiguráciu pri štarte,
• vykonáva warm-up embeddingovej vrstvy,
• nastavuje CORS a bezpečnostné hlavičky,
• pripája API routery,
• ponecháva OpenAPI schému dostupnú pre OpenWebUI.

Interaktívne Swagger/Redoc rozhranie môže byť v produkčnej konfigurácii vypnuté. Pre integráciu OpenWebUI je dôležitý endpoint:

/openapi.json

app/routes.py

• definuje /health,
• definuje verejne publikovaný RAG nástroj /rag,
• obsahuje interné/zabezpečené /search a /sync,
• obsluhuje /webhook/gitea,
• vykonáva validáciu requestov a sanitizáciu chýb,
• používa reindexovací zámok,
• kontroluje webhook payload pred spracovaním.

app/security.py

• spracúva SEARCH_API_KEY,
• spracúva SYNC_API_KEY,
• spracúva WEBHOOK_SECRET,
• vyžaduje dostatočne dlhé a navzájom odlišné tajomstvá,
• používa bezpečné porovnávanie autentifikačných hodnôt,
• validuje očakávaný Gitea repozitár a súvisiacu konfiguráciu.

scripts/

common.py

Spoločné utility a konfiguračné funkcie používané indexovacou a vyhľadávacou vrstvou.

scan_zpwiki.py

• prechádza repozitár zpwiki,
• načítava Markdown a YAML front matter,
• normalizuje dokumentové metadata,
• pripravuje dokumenty na ďalšie spracovanie.

build_chunks.py

• rozdeľuje dokumenty na tokenové chunky,
• používa tiktoken,
• zachováva nadpisy, kódové bloky a tabuľky,
• podporuje tokenový overlap,
• eviduje token count a hash obsahu chunku.

build_sqlite_index.py

• vytvára SQLite databázu,
• ukladá dokumenty, chunky a metadata,
• vytvára FTS5 index,
• ukladá embeddingy do SQLite,
• pripravuje databázu pre hybridný retrieval.

embedding_utils.py

• načítava embeddingový model,
• vytvára embeddingy pre dokumenty a query,
• 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:

• normalizácia query,
• FTS5 vyhľadávanie,
• embeddingové vyhľadávanie,
• scoring,
• RRF fusion,
• lexical anchor,
• metadata,
• diverzifikácia výsledkov.

search_utils.py

Vyššia orchestration vrstva nad search_core.py a kompatibilné vyhľadávacie utility používané ostatnými časťami projektu.

search_db.py

CLI rozhranie na ručné vyhľadávanie nad lokálnym SQLite indexom.

rag_utils.py

• zostavuje RAG kontext,
• pripravuje zdrojové metadata,
• pridáva source_url,
• aplikuje grounding pravidlá,
• podporuje no-answer správanie,
• rozširuje primárny chunk o začiatok rovnakej sekcie,
• zachováva väzbu medzi primárnym chunkom a section-lead chunkom.

rebuild_index.py

Orchestruje kompletný rebuild:

scan
→ chunking
→ SQLite/FTS
→ embeddings
→ validácia
→ atomická výmena DB

evaluation/

evaluate_retrieval.py

CLI vstup pre retrieval benchmark. Umožňuje spúšťať DEV, TEST alebo celý dataset a používa strict dataset validáciu.

retrieval_runner.py

Spúšťa jednotlivé retrieval stratégie nad evaluačnými otázkami.

metrics.py

Počíta retrieval metriky, napríklad:

Hit@1
Hit@3
Hit@5
MRR
Recall@5

evaluate_rag_answers.py

CLI vstup pre answer-level RAG evaluáciu. Hodnotí celý tok:

otázka
→ OpenWebUI model
→ ZP Agent tool
→ /rag
→ finálna odpoveď

Podporuje answer-level overrides, aby nebolo potrebné meniť frozen retrieval benchmark pri otázkach, ktoré sú pre generatívnu evaluáciu nejednoznačné.

rag_runner.py

Spúšťa jednotlivé answer-level prípady a komunikuje s OpenWebUI/API.

rag_metrics.py

Počíta answer-level metriky, napríklad:

• prítomnosť očakávaných faktov,
• správnosť source_url,
• should_answer,
• použitie toolu,
• strict pass,
• latency a tokenové údaje.

evaluation/json_files/

questions.json

Hlavný frozen benchmark pre klasický retrieval a RAG. Po zmrazení benchmarku sa nemá meniť len preto, aby sa zlepšil výsledok answer-level evaluácie.

rag_answer_overrides.json

Obsahuje iba answer-level úpravy formulácie alebo očakávaní pri nejednoznačných otázkach. Retrieval benchmark tým ostáva nezmenený.

questions_before_ambiguity_cleanup.json

Historická záloha datasetu pred úpravami nejednoznačností.

questions_before_validation.json

Historická záloha datasetu pred validačnými úpravami.

questions_extended_2000.json

Rozšírený benchmark s presne 2000 otázkami. Je pripravený pre neskoršie rozsiahlejšie experimenty nad klasickým retrievalom a RAG.

Obsahuje kombináciu:

• faktických otázok,
• parafráz,
• otázok bez diakritiky,
• preklepov,
• krátkych query,
• no-answer prípadov,
• negatívnej verifikácie,
• multi-document otázok,
• porovnávania,
• citation-oriented prípadov.

Tento dataset je zatiaľ pripravený, ale nemá sa používať na priebežné ladenie frozen benchmarku.

graphrag_questions.json

Samostatný benchmark pripravený pre vývoj GraphRAG vetvy.

Obsahuje 500 otázok zameraných na:

• multi-hop vzťahy,
• spoločné témy,
• spoločné roky,
• person → title → year,
• person → topic → title,
• person → category → author,
• agregácie,
• konjunktívnu disambiguáciu,
• multi-document reasoning.

Dataset obsahuje aj GraphRAG metadata ako:

graph.task
graph.hop_count
graph.start_entities
graph.expected_entities
graph.expected_relations
graph.expected_paths

Dataset sa používa pre vývoj a neskoršie porovnanie GraphRAG vetvy. 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

Samostatný dataset s 200 otázkami pre testovanie robustnosti.

Pokrýva napríklad:

• chýbajúcu diakritiku,
• preklepy,
• nekonzistentnú kapitalizáciu a interpunkciu,
• nerelevantný šum,
• prompt injection,
• konfliktné tvrdenia používateľa,
• tlak na halucinovanie,
• no-answer grounding,
• ambiguity/disambiguation,
• integritu citácií,
• kombinovaný vstupný šum.

Každá položka obsahuje aj robustness metadata s typom útoku, perturbáciou, očakávaným správaním a závažnosťou.

performance_queries.json

Samostatný workload s 200 query pre budúce performance a stress experimenty.

Profily zahŕňajú:

• baseline single-document query,
• krátke query,
• noisy query,
• multi-document query,
• no-answer query,
• query s väčším retrieval limitom,
• context-heavy query,
• opakované hot query.

Súbor samotný performance nemeria. Je to vstup pre budúci samostatný performance runner, ktorý bude volať /rag a merať napríklad:

mean latency
median
P50
P95
P99
requests/second
error rate
timeout rate
cold vs warm latency

Stress režim bude nad rovnakým workloadom zvyšovať paralelizmus a sledovať správanie systému pri rastúcej záťaži.

Konfigurácia

V koreňovom priečinku vytvor .env:

WEBHOOK_SECRET=<náhodná hodnota s minimálne 32 znakmi>
SYNC_API_KEY=<iná náhodná hodnota s minimálne 32 znakmi>
SEARCH_API_KEY=<ďalšia náhodná hodnota s minimálne 32 znakmi>
EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki
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:

openssl rand -hex 32

Súbor .env sa nesmie commitovať.

Chunkovanie je možné konfigurovať pomocou premenných prostredia:

CHUNK_MAX_TOKENS=450
CHUNK_OVERLAP_TOKENS=70
CHUNK_MIN_TOKENS=80
CHUNK_TOKEN_ENCODING=cl100k_base

Spustenie cez Docker

docker compose up -d --build

Kontrola služby:

curl http://127.0.0.1:8000/health

OpenAPI schéma:

http://127.0.0.1:8000/openapi.json

Logy:

docker compose logs -f zp-agent-api

Zastavenie:

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ť:

docker compose ps

Neo4j Browser je lokálne dostupný na:

http://127.0.0.1:7474/browser/

Kontrola spojenia z API kontajnera:

docker compose exec zp-agent-api \
  python -m scripts.neo4j_smoke

Reindexovanie

Celý proces načíta dokumenty, vytvorí chunky, obnoví FTS5 index a vytvorí embedding pre každý chunk:

docker compose run --rm zp-agent-api python scripts/rebuild_index.py

Vzniknú súbory:

data/documents.json
data/chunks.json
data/zp_index.sqlite

Databáza obsahuje dokumenty, chunky, FTS5 index, metadata a embeddingy.

Pri automatickom reindexovaní sa používa zámok proti súbežnému spusteniu a atomická výmena databázy po úspešnom vytvorení nového indexu.

Hybridné vyhľadávanie

Vyhľadávanie kombinuje:

dotaz
├── FTS5 / BM25
└── embeddingové vyhľadávanie
        ↓
   RRF fusion
        ↓
   lexical anchor
        ↓
   výsledky

FTS5 používa stratégie:

all_terms
prefix_terms
any_term

Presné lexikálne výsledky majú prednosť pred slabšími sémantickými zhodami. Pri slabšej any_term stratégii sa znižuje jej váha a väčší význam môže dostať embeddingové vyhľadávanie.

Test z terminálu:

docker compose run --rm zp-agent-api \
  python scripts/search_db.py "rag agent" --limit 5

Pred volaním API načítaj premenné z .env:

set -a
source .env
set +a

Vyhľadávanie cez zabezpečené API:

curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SEARCH_API_KEY" \
  -d '{
    "query": "strojový preklad",
    "limit": 3,
    "published_only": false,
    "max_per_document": 1
  }'

API používa hybridný engine:

hybrid_fts5_embeddings

max_per_document=1 zabezpečí, že sa pri požiadavke na viac výsledkov preferujú rôzne dokumenty namiesto viacerých chunkov z rovnakého dokumentu.

RAG

Nad hybridným retrievalom je implementovaná RAG vrstva v scripts/rag_utils.py.

Endpoint /rag vyhľadá relevantné dokumenty a pripraví:

• textový kontext pre jazykový model,
• metadata použitých zdrojov,
• názov a autora dokumentu,
• source_url,
• interné retrieval informácie,
• pravidlá pre grounded odpoveď.

RAG pravidlá požadujú, aby model odpovedal iba podľa poskytnutých zdrojov. Zároveň rozlišujú údaje, ktoré sa môžu ľahko zameniť, napríklad autora dokumentu, osobu, o ktorej dokument pojednáva, rok začiatku štúdia a rok záverečnej práce.

Ak sa relevantná informácia nenachádza priamo v primárnom chunke, RAG vrstva môže k rovnakému zdroju doplniť začiatok rovnakej sekcie. Táto section-lead expanzia umožňuje zachovať retrieval max_per_document=1, ale zároveň doplniť názov témy, rok alebo inú informáciu umiestnenú na začiatku sekcie.

Pri nedostatočnej podpore má model odmietnuť informáciu domýšľať.

Príklad:

curl -X POST http://127.0.0.1:8000/rag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SEARCH_API_KEY" \
  -d '{
    "query": "V akom roku robil Ján Holp diplomovú prácu?",
    "limit": 5,
    "published_only": false,
    "max_per_document": 1
  }'

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:

Person
Document
Work
Topic
Category
Author

Hlavné vzťahy zahŕňajú napríklad:

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:

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.

OpenWebUI používa OpenAPI schému ZP Agent API a Bearer autentifikáciu pre vyhľadávací/RAG nástroj.

Tok požiadavky:

používateľ
  ↓
OpenWebUI
  ↓
jazykový model
  ↓
ZP Agent /rag
  ↓
hybrid retrieval
  ↓
RAG kontext + zdroje
  ↓
jazykový model
  ↓
odpoveď

Výsledná odpoveď má byť grounded v ZP Wiki a má používať relevantný source_url.

Retrieval evaluácia

Frozen retrieval benchmark sa spúšťa napríklad:

python evaluation/evaluate_retrieval.py \
  --split dev \
  --strict-dataset

Podporované režimy:

dev
test
all

Vyhodnocujú sa samostatne:

FTS
vector
hybrid

a metriky:

Hit@1
Hit@3
Hit@5
MRR
Recall@5

TEST split sa nemá používať na priebežné ladenie retrieval konfigurácie.

RAG answer evaluácia

Answer-level evaluácia používa:

python evaluation/evaluate_rag_answers.py --split dev

Evaluuje kompletný model/tool/RAG tok a od retrieval benchmarku je oddelená.

Ak je pôvodná otázka vhodná pre retrieval, ale nejednoznačná pre generatívnu odpoveď, jej answer-level formulácia sa upraví iba cez:

evaluation/json_files/rag_answer_overrides.json

Pôvodný frozen questions.json tým ostáva nezmenený.

Manuálna synchronizácia

Manuálne reindexovanie cez zabezpečený endpoint:

curl -X POST http://127.0.0.1:8000/sync \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SYNC_API_KEY" \
  -d '{"pull_git": false}'

Gitea webhook

Endpoint:

POST /webhook/gitea

Webhook overuje:

• HMAC-SHA256 podpis,
• typ Gitea udalosti,
• očakávaný repozitár,
• maximálnu veľkosť payloadu,
• stav reindexovacieho zámku.

Očakávaný repozitár:

EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki

Ak je povolené:

WEBHOOK_PULL_GIT=true

pred reindexovaním sa vykoná:

git pull --ff-only

Bezpečnosť

Vyhľadávanie podporuje API key:

X-API-Key: <SEARCH_API_KEY>

aj Bearer autentifikáciu:

Authorization: Bearer <SEARCH_API_KEY>

Endpoint /sync používa samostatný SYNC_API_KEY a webhook samostatný WEBHOOK_SECRET.

Tajomstvá sa ukladajú do .env, ktorý nesmie byť súčasťou Git repozitára.

Bezpečnostná vrstva zároveň kontroluje minimálnu dĺžku tajomstiev, odlišnosť jednotlivých secretov a používa bezpečné porovnávanie hodnôt.

Testy

Inštalácia testovacích závislostí:

pip install -r requirements-dev.txt

Bežné automatizované testy:

pytest -q

Kontrola syntaxe najdôležitejších upravovaných modulov:

python -m py_compile \
  scripts/rag_utils.py \
  evaluation/evaluate_rag_answers.py \
  evaluation/rag_runner.py \
  evaluation/rag_metrics.py

Pred checkpointom je vhodné použiť aj:

git diff --check
git status

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.

Experimentálne datasety

Pre ďalšie experimenty sú pripravené:

questions_extended_2000.json
graphrag_questions.json
robustness_questions.json
performance_queries.json

graphrag_questions.json je aktuálne určený pre vývoj GraphRAG vetvy. Ostatné datasety zostávajú oddelené od priebežného ladenia frozen klasického baseline.

Najbližší postup

Klasický RAG baseline je zmrazený a GraphRAG infraštruktúra s Neo4j je funkčná. Ďalší vývoj pokračuje nad samostatnou GraphRAG vetvou.

1. Dokončenie kvality knowledge graphu

• doplniť bezpečné fallback pravidlá pre explicitné názvy prác,
• ponechať null tam, kde zdroj názov skutočne neuvádza,
• doplniť regresné testy pre graph builder.

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:

grafové entity
→ grafové cesty
→ relevantné dokumenty
→ zdrojové chunky

3. Spojenie s klasickým RAG

Grafový retrieval sa následne spojí s existujúcim FTS5 + embedding retrievalom. Klasický baseline zostane zachovaný ako samostatný referenčný bod.

query
  ↓
├── classic retrieval
└── graph retrieval
       ↓
   context fusion
       ↓
      RAG

4. GraphRAG evaluácia

GraphRAG sa bude priebežne ladiť na DEV dátach a vyhodnocovať aj na samostatnom graphrag_questions.json datasete. Až po stabilizovaní celého systému budú nasledovať širšie embeddingové, robustness a performance experimenty.