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

Načíta Markdown dokumenty a YAML metadáta z lokálnej kópie Git repozitára.
Rozdelí obsah na tokenové úseky a vytvorí textový, vektorový a grafový index.
Podľa zvoleného nástroja vyhľadá relevantné texty alebo grafové fakty.
Jazykový model vyberie dôkazy alebo navrhne štruktúrované tvrdenia.
Backend skontroluje hodnoty, väzby, citácie a pokrytie požadovaných údajov.
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. 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 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. 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é manifesty ani výsledky sa neprepisujú na odtlačky aktuálnej implementácie; ich úspešnosť nie je novým meraním po reorganizácii.

5.9 KiB Raw Blame History Unescape Escape