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. Pri opisoch a porovnaniach model navrhne prirodzené tvrdenia s konkrétnymi dôkazmi.
5. Backend skontroluje väzby, čísla a citácie; podporu preverí oddelené LLM volanie, rizikové tvrdenia aj druhý posudok.
6. Pri zlyhaní syntézy zostane pôvodná doložená odpoveď. Názvy, počty a presné zoznamy zostavuje priamo.

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.