dp-zp-agent/README.md

ZP Agent

Backend, ktorý odpovedá na otázky o záverečných prácach z repozitára zpwiki (ZP Wiki, KEMT FEI TUKE). Vzniká v rámci práce Agent pre manažment záverečných prác.

Spracúva profily študentov, zadania a záznamy zo stretnutí a odpovedá na otázky o prácach, projektoch, vedúcich, témach, výsledkoch, rokoch a vzťahoch medzi študentmi. Každá odpoveď je overená a má odkazy na zdroj.

Ako funguje

1. Synchronizácia – načíta Markdown a YAML metadáta z lokálnej kópie Git repozitára (ručne, webhookom z Gitea alebo automaticky každých 24 hodín).
2. Indexovanie – rozdelí texty na úseky a z rovnakého snapshotu vytvorí textový, vektorový a grafový index. Nová verzia sa aktivuje až keď sú hotové všetky; pri chybe zostáva predchádzajúca.
3. Porozumenie otázke – otázka sa preloží na typovaný plán (osoby, roly, práce, roky, obdobia, podmienky). Jednoznačné otázky plánujú pravidlá; nové formulácie priradí LLM k pevnému katalógu typov otázok. Model nikdy nepíše databázový dotaz.
4. Vyhľadanie podkladov – podľa plánu sa hľadajú textové úseky alebo grafové fakty.
5. Zostavenie odpovede – zoznamy, počty a metadáta skladá priamo kód; opisy a porovnania formuluje LLM výhradne z dodaných dôkazov.
6. Kontrola pred odoslaním – backend overí osoby, práce, čísla a citácie a samostatné LLM volanie overí, že tvrdenia sú podložené. Neoverenú odpoveď nevydá; namiesto toho oznámi, že odpoveď nie je dostupná.

Pravidlá domény: autor profilovej stránky študenta je jeho vedúci (konvencia KEMT), rok práce nie je dátum stretnutia a zadanie ani plán sa nevydávajú za výsledok.

Vyhľadávanie

RAG – kombinuje fulltext BM25 a sémantické vyhľadávanie (embeddingy), výsledky spája metódou RRF. Osobu, typ práce a rok filtruje záväzne. Slovenské tvary slov zjednocuje lematizácia (Stanza) a poradie kandidátov spresňuje cross-encoder reranker. Hodí sa na otázky o obsahu, zadaní, metódach, priebehu a výsledkoch práce.

GraphRAG – pevné Cypher šablóny nad grafom v Neo4j (osoby, práce, témy, činnosti, dôkazy). Odpovedá na vzťahy: kto robil danú tému, podobní študenti, súvisiace témy, vedúci a ich študenti, roky a počty. Prepojenia dokladá výňatkami z oboch prác.

Obsahový graf – LLM z profilov extrahuje činnosti, pojmy a výsledky. Každý poznatok má doslovný výňatok, aktéra, konkrétnu prácu, fázu a dátum. Neisté poznatky sa ako fakty nepoužijú. Rovnaké pojmy v rôznych tvaroch sa automaticky zjednotia. Extrakciu spúšťa python -m tools.knowledge.build (vyžaduje nakonfigurované LLM API).

Použité technológie

• Python, FastAPI, Pydantic – API, validácia vstupov a typované plány a odpovede.
• SQLite + FTS5 – dokumenty, metadáta, fulltextový index, vektory a cache.
• Sentence Transformers, multilingual-e5-small – viacjazyčné embeddingy.
• Cross-encoder mmarco-mMiniLMv2 – preusporiadanie (reranking) nájdených podkladov.
• Stanza – lematizácia slovenčiny.
• Neo4j a Cypher – metadátový a obsahový graf.
• OpenAI-kompatibilné LLM API – plánovanie nejasných otázok, formulácia a overenie odpovedí.
• DSPy (offline) – optimalizácia inštrukcií a príkladov katalógu typov otázok.
• Tiktoken – meranie a delenie textových úsekov.
• MCP (FastMCP) a Claude Skills – nástroje /rag a /graphrag v Claude.
• OAuth s PKCE, Cloudflare Tunnel – zabezpečený verejný prístup k MCP serveru.
• Docker Compose – nasadenie API, Neo4j, MCP servera a tunela.
• Git a Gitea webhooky – získavanie zmien zo ZP Wiki.
• Pytest – testy funkcionality a regresie.

Architektúra

Claude (Skills /rag, /graphrag)
        │  MCP + OAuth (Cloudflare Tunnel)
        ▼
claude-mcp (FastMCP) ──HTTP──► zp-agent-api (FastAPI)
                                 ├─ SQLite: texty, FTS5, vektory, cache
                                 ├─ Neo4j: metadátový a obsahový graf
                                 ├─ LLM API: plán, formulácia, overenie
                                 └─ Git kópia zpwiki ◄── Gitea webhook / 24 h

Spustenie

bash scripts/start.sh                       # build, Neo4j, príprava indexov, API
bash scripts/compose.sh up -d claude-mcp    # voliteľne MCP server pre Claude
.venv/bin/python -m pytest -q               # testy

Konfigurácia (API kľúče, LLM poskytovateľ, OAuth) sa nastavuje v .env. Prepínače RETRIEVAL_LEMMATIZER, RETRIEVAL_RERANKER a ANSWER_QUESTION_CATALOG v deployment/docker-compose.yml zapínajú lematizáciu, reranker a katalóg otázok.

Priečinky

• app/ – HTTP API (endpointy /answer, /graphrag, /health, synchronizácia) a zabezpečenie.
• tools/rag/ – textové a vektorové vyhľadávanie.
• tools/graphrag/ – metadátový graf a grafové dotazy.
• tools/knowledge/ – obsahový graf: extrakcia poznatkov a ich vyhľadávanie.
• tools/answers/ – plán otázky, zostavenie a kontrola odpovede.
• tools/retrieval/ – spoločné vyhľadávacie pravidlá, mená, lematizácia, reranker.
• tools/sync/ – synchronizácia s Git repozitárom a obnova indexov.
• tools/git_runner/ – Gitea runner, ktorý dopĺňa fork jp170na/zpwiki z KEMT/zpwiki.
• tools/runtime/ – príprava modelov a indexov pri štarte.
• tools/claude/, packages/claude/ – zostavenie a hotové Claude Skills (dist/rag, dist/graphrag).
• deployment/ – Dockerfile, Docker Compose a závislosti.
• scripts/ – spúšťacie skripty.
• test/, tools/*/tests/ – testy funkcionality jednotlivých služieb (plánovanie, vyhľadávanie, kontrola odpovedí, API, synchronizácia, balíky Claude).
• data/ – lokálne dáta za behu (indexy, cache); nie sú v Gite.