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. Podľa zvoleného nástroja vyhľadá relevantné texty alebo grafové fakty.
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. Oba indexy sa obnovujú z rovnakého snapshotu a používajú spoločnú verziu dát.

Vyhľadávanie

RAG kombinuje fulltextové vyhľadávanie BM25 so sémantickým vyhľadávaním pomocou embeddingov. Výsledky spája metódou RRF. Je vhodný na otázky na obsah, zadanie, metódy, priebeh a výsledky práce.

GraphRAG využíva znalostný graf osôb, dokumentov, prác, projektov, tém, tagov a kategórií. Umožňuje vyhľadávať vzťahy, spoločné vlastnosti a kombinácie podmienok, napríklad tag spolu s typom a rokom práce.

Obsahový graf dopĺňa pojmy a vzťahy extrahované jazykovým modelom z profilov študentov. Každý poznatok zostáva spojený s pôvodným výňatkom, osobou, prácou a explicitne uvedeným dátumom. 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. 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. 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. Historické evaluácie sú uložené pri jednotlivých vetvách. Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.