Agent pre manažment záverečných prác
Go to file
2026-11-16 20:45:10 +01:00
app revizia_odpovedi 2026-11-16 20:45:10 +01:00
deployment upravy vyhladavania 2026-11-15 16:27:08 +01:00
packages/claude odpovede, stránkovanie 2026-11-16 01:16:15 +01:00
runtime_assets Stabilné spustenie projektu 2026-10-26 15:12:31 +01:00
scripts Stabilizácia odpovedí 2026-11-13 16:00:48 +01:00
test revizia_odpovedi 2026-11-16 20:45:10 +01:00
tools revizia_odpovedi 2026-11-16 20:45:10 +01:00
.dockerignore Upratanie projektu 2026-11-14 03:16:54 +01:00
.gitignore Upratanie projektu 2026-11-14 03:16:54 +01:00
conftest.py revizia_odpovedi 2026-11-16 20:45:10 +01:00
pytest.ini Stabilizácia odpovedí 2026-11-13 16:00:48 +01:00
README.md odpovede, stránkovanie 2026-11-16 01:16:15 +01:00

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.