# 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). **CRZP** – Centrálny register záverečných prác (všetky slovenské vysoké školy) je súčasťou `/rag` aj `/graphrag`, nie samostatný nástroj. Každá otázka sa súbežne pýta ZP Wiki aj CRZP (`tools/answers/combined.py`); CRZP pridá práce osoby na TUKE (vedúci, oponent, abstrakt), práce na rovnakú tému alebo podobné práce z iných škôl a odpovedá sám na otázky o iných školách, oponentoch, katedrách a obhájených prácach (zverejnená práca v CRZP = obhájená). Číta sa len verejné HTML (metadáta a abstrakty, nie plné texty), s obmedzením počtu požiadaviek a lokálnou cache (`data/crzp`). Použité práce sa ukladajú do Neo4j a prepájajú s osobami a témami ZP Wiki (`PROBABLY_SAME`, `SAME_TOPIC`). ## Odpoveď - Jedna odpoveď: zoznam ľudí je jeden očíslovaný zoznam (najprv ZP Wiki, potom CRZP, s označením zdroja), zdroje sú v jednom riadku na konci. - Dlhý zoznam ukáže 6 položiek a opýta sa „Chceš vidieť ďalšie?“; odpoveď „áno“ ukáže ďalšie. - Doplňujúce otázky cez podpísaný token: „a z akých škôl sú?“, „a čo robil prvý z nich?“, výber práce („2“, „tak 1“, „bakalársku“), výber menovca a „a o čom je?“. - Súvisiace témy: téma, kto ju robil v ZP Wiki a koľko prác je v CRZP (vážené podľa toho, ako špecifický je pojem); podobné práce: najšpecifickejšie spoločné pojmy v základnom tvare. - Čas každej odpovede (kroky, počet a typ volaní modelu, bez textu otázky) sa zapisuje do `data/logs/answer_timings.jsonl`. ## Testovanie - `pytest` – testy funkcionality a regresie. - `python -m tools.evaluation.gold_set run --label X` – 111 ručne napísaných otázok s očakávaniami odvodenými zo ZP Wiki (spúšťať samostatne). - `python -m tools.evaluation.corpus build|run --label X` – ~460 generovaných otázok na každý profil (vedúci, posledné stretnutie, začiatok štúdia, práce, úlohy, technológie), témy, doplňujúce otázky, súvisiace a podobné práce, CRZP a odmietnutia; kontroluje aj, či odpoveď neobsahuje servisné poznámky. Výsledky platia len pre danú sadu. ## 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. ## 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.