dp-zp-agent/README.md
jp170na 55d29ae167 odpovede, stránkovanie
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 01:16:15 +01:00

111 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.