ZP Agent

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

Účel

Projekt vzniká v rámci práce Agent pre manažment záverečných prác. Spracúva profily študentov, zadania a priebežné poznámky zo ZP Wiki. Poskytuje dohľadateľné odpovede o prácach, projektoch, rokoch a vzťahoch prostredníctvom klasického RAG a grafového vyhľadávania v Neo4j.

Implementované funkcie

• Import Markdownov a YAML metadát, štruktúrne tokenové chunkovanie.
• SQLite FTS5/BM25, viacjazyčné embeddingy E5 a hybridné radenie RRF.
• Segmentácia finálnych embeddingových vstupov a cache nezmenených vektorov.
• Deterministický znalostný graf a parametrizované vyhľadávanie v Neo4j.
• Kontrola faktov, väzieb, citácií, počtov a úplnosti pred doručením odpovede.
• Rozlíšenie zadania, plánov, priebežného stavu a výsledkov práce.
• Spoločná synchronizácia SQLite a Neo4j z Gitu, webhook a persistentná fronta.
• FastAPI, Docker Compose, kontroly dostupnosti a modelové assets pre offline štart.
• Claude Skills a MCP konektor s OAuth/PKCE pre RAG, GraphRAG a stav služieb.
• Retrieval evaluácia, zdrojové audity a automatické regresné testy.

Architektúra

zpwiki (Git) -> Markdown/YAML -> spoločný snapshot
                                      |-- SQLite: FTS5 + embeddingy
                                      `-- Neo4j: entity + vzťahy

Claude + Skills -> HTTPS/OAuth -> MCP -> FastAPI /answer
                                             |
                                +------------+------------+
                                |                         |
                           RAG / SQLite            GraphRAG / Neo4j
                                |                         |
                                +------------+------------+
                                             |
                              model -> kontroly -> renderer
                                             |
                                  odpoveď + zdrojové odkazy

/rag a /graphrag vracajú podklady. /answer vykonáva kontrolovanú prípravu odpovede; pri nedostatočných dôkazoch informáciu nedopĺňa odhadom.

Štruktúra

Priečinok	Obsah
app/	FastAPI, vstupné modely a autorizácia.
tools/rag/	Import, chunky, SQLite a hybridné vyhľadávanie.
tools/graphrag/	Dátový model, Neo4j, grafové dotazy a evaluácia.
tools/answers/, tools/answer_evaluation/	Generovanie, dôkazy, kontroly a metriky.
tools/retrieval/, tools/sync/, tools/runtime/	Kontrakty, synchronizácia a prevádzka.
packages/claude/	Skills, MCP, OAuth, klient a inštalovateľné ZIPy.
deployment/, scripts/	Docker, závislosti, štart a overovacie skripty.
test/, tools/*/tests/	Jednotkové a integračné regresie.

Spustenie

Vyžaduje Docker s Compose v2 a Buildx, lokálny klon wiki v ../zpwiki a súbor .env s konfiguráciou kľúčov, Neo4j, Git prístupu a modelového API. Prvý build potrebuje sieť na získanie závislostí a modelových súborov. Pre webový Claude treba navyše dostupnú HTTPS adresu MCP a OAuth nastavenia.

./scripts/start_project.sh
./scripts/compose.sh --profile claude up -d --build
curl http://127.0.0.1:8000/health

Konfiguráciu služieb určuje Docker Compose. Klientské pokyny sú v RAG Skill a GraphRAG Skill. Balíky sa zostavia cez python scripts/build_claude_packages.py. Lokálne overenie poskytuje scripts/verify_project.py po príprave jeho závislostí.

Stav a ďalší vývoj

Obe vetvy a kontrolovaná cesta odpovedí sú funkčné a overené aj cez Claude. Prototyp používa dočasný HTTPS tunel; trvalé nasadenie zostáva ďalšou etapou. Plánované sú tolerantné rozpoznávanie mien, hlavný agent, Git nástroje, CRZP, plné texty prác a spoločné porovnanie RAG/GraphRAG a modelov. Historické merania sú v evaluačných priečinkoch; nepredstavujú univerzálnu záruku presnosti aktuálneho agenta. Tajomstvá, databázy a modelové váhy nepatria na Git.