dp-zp-agent/README.md

# ZP Agent

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

Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**.
Spracúva profily študentov, zadania a poznámky zo ZP Wiki a poskytuje
odpovede o prácach, projektoch, rokoch a súvisiacich vzťahoch so zdrojovými odkazmi.

## Ako funguje

1. Načíta Markdown dokumenty a YAML metadáta z lokálnej kópie Git repozitára.
2. Rozdelí obsah na tokenové úseky a vytvorí textový, vektorový a grafový index.
3. Spoločný Pydantic plán zachová osoby, roly, práce, časové podmienky a požadované údaje.
   Jednoznačné otázky plánuje priamo; nové formulácie pomáha overene interpretovať LLM.
   Podľa plánu vyhľadá textové podklady alebo grafové fakty; neznáme podmienky nevynechá.
4. Jazykový model vyberie dôkazy alebo navrhne štruktúrované tvrdenia.
5. Backend skontroluje hodnoty, väzby, citácie a pokrytie požadovaných údajov.
6. Z overených podkladov zostaví odpoveď; chýbajúce informácie výslovne označí.

Aktualizáciu možno spustiť manuálne alebo webhookom z Gitea. Docker nasadenie
ju plánuje aj každých 24 hodín (`WIKI_SYNC_INTERVAL_SECONDS=86400`).
`SYNC_UPSTREAM_FORK=1` bezpečne dopĺňa fork `jp170na/zpwiki` z `KEMT/zpwiki`;
do originálu nezapisuje. Vyžaduje bežiaci backend a SSH prístup do forku.
Textový index, metadátový graf a už zapnutá obsahová extrakcia sa pripravujú
z rovnakého snapshotu a aktivujú spoločne. Pri chybe zostáva predchádzajúca verzia.

## Vyhľadávanie

**RAG** kombinuje fulltextové vyhľadávanie BM25 so sémantickým vyhľadávaním
pomocou embeddingov. Samostatné výsledky spája metódou RRF; osobu, typ a rok filtruje záväzne.
Je vhodný na otázky na obsah, zadanie, metódy, priebeh a výsledky práce.

**GraphRAG** využíva metadátové dotazy a ohraničené prechody cez osoby, práce,
činnosti, témy a dôkazy v Neo4j. Prepojenia vysvetľuje zdrojovými výňatkami oboch prác.
Cypher šablóny sú pevné; jazykový model nevykonáva ľubovoľné databázové príkazy.

Obsahový graf dopĺňa pojmy a vzťahy extrahované jazykovým modelom z profilov
študentov. Každý poznatok uchováva doslovný výňatok, aktéra, konkrétnu prácu,
fázu a oddelený dátum záznamu, vykonania či plánovaný termín. Podporuje otázky na pokrok, čas výsledkov,
podobné témy a študentov venujúcich sa určitej činnosti. Zadanie ani plán
sa nevydávajú za dokončený výsledok; chýbajúce údaje sa neodhadujú.
Pri výsledkoch sa rozlišuje dátum záznamu od skutočného dňa vykonania práce.
Model spracúva najviac osem jednotiek naraz a rozhoduje o každej z nich;
neisté poznatky sa nepoužijú ako fakty. Vzťahy vyžadujú doslovný dôkaz aj
samostatné modelové overenie. Chýbajúce rozhodnutie zablokuje publikovanie.
Repozitárové odkazy sa overujú cez verejné API; neoveriteľné odkazy sa nezobrazujú.

Extrakciu spúšťa `python -m tools.knowledge.build` s nakonfigurovaným LLM API.
Vyžaduje pripravené spoločné indexy a Neo4j. Nezmenené vstupy využívajú cache;
po prvom vytvorení sa obsahový index obnovuje aj pri synchronizácii.
Claude Skills sú klientom rovnakého backendu, jeho logika nezávisí od rozhrania.
`ANSWER_STRUCTURED_OUTPUT=json_schema` zapína schému u podporujúceho poskytovateľa.
Predvolene sa používa prompt a lokálna typová aj významová kontrola plánu.
Voliteľný Compose profil `claude-tunnel` pripája Cloudflare priamo k službe MCP
v Docker sieti. Dočasná verejná URL vyžaduje zodpovedajúce OAuth nastavenie
`ZP_MCP_PUBLIC_URL`; po vytvorení nového tunela sa môže zmeniť.

## Použité technológie

- **Python, FastAPI a Pydantic** – API, validácia vstupov a typované odpovede.
- **SQLite a FTS5** – dokumenty, metadáta, fulltextový index a uložené vektory.
- **Sentence Transformers a multilingual-e5-small** – viacjazyčné embeddingy.
- **Tiktoken** – meranie veľkosti a delenie textových úsekov.
- **Neo4j a Cypher** – uloženie a vyhľadávanie grafových vzťahov.
- **MCP a Claude Skills** – sprístupnenie RAG a GraphRAG používateľovi v Claude.
- **OAuth s PKCE** – autentizácia webového MCP konektora.
- **Docker Compose** – spoločné nasadenie API, Neo4j a MCP servera.
- **Git a Gitea webhooky** – získavanie zmien a spúšťanie synchronizácie.
- **Pytest a evaluačné skripty** – regresie, kontrola vyhľadávania a odpovedí.

## Súčasný stav

RAG, GraphRAG, kontrolovaná cesta odpovedí a pripojenie cez Claude sú funkčné.
Systém obsahuje embeddingovú cache, kontroly dostupnosti a persistentnú
synchronizačnú frontu. `/health` samostatne uvádza vyhľadávanie, obsahové
poznatky a generovanie. Dostupnosť modelu eviduje po jeho použití alebo po
explicitnom autentifikovanom `POST /health/generation`; samotná kontrola
`GET /health` model nevolá. Historické evaluácie sú oddelené od prevádzkového kódu.
Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.

## Organizácia projektu

- `app/` – HTTP API a zabezpečenie.
- `tools/rag/`, `tools/graphrag/`, `tools/knowledge/` – vyhľadávanie a indexovanie.
- `tools/answers/` – príprava podkladov, kontroly a zostavenie odpovede.
- `tools/retrieval/`, `tools/sync/`, `tools/runtime/` – spoločné pravidlá a prevádzka.
- `tools/evaluation/` a `tools/*/evaluation/` – offline evaluátory a diagnostika.
- `experiments/rag/`, `experiments/graphrag/` – vybrané historické vstupy a výsledky.
- `experiments/archive/` – komprimované vývojové pokusy; mapovanie a SHA-256 sú v `catalog.json`.
- `packages/claude/`, `deployment/`, `scripts/` – klienti, nasadenie a spúšťanie.

Prevádzkový image neobsahuje testy ani historické experimenty. Spúšťa sa cez
`bash scripts/start.sh`; voliteľné služby ovláda `bash scripts/compose.sh`.
Regresie spúšťa `.venv/bin/python -m pytest -q test tools/rag/tests tools/graphrag/tests`.
Integritu experimentov overí `python -m tools.evaluation.archive verify`.
Archív možno obnoviť bez prepisovania súborov pomocou
`python -m tools.evaluation.archive restore --destination /tmp/zp-experiments`.
Pôvodný kód experimentov určuje `source_commit` v katalógu a historické Git tagy.
Staré výsledky sa neprepisujú; ich úspešnosť nie je novým meraním po reorganizácii.