111 lines
7.0 KiB
Markdown
111 lines
7.0 KiB
Markdown
# 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.
|