Aktualizácia README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -1,95 +1,104 @@
 # ZP Agent
 
-Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom
-záverečných prác `zpwiki`.
+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**.
 
-Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**.
-Spracúva profily študentov, zadania a poznámky zo ZP Wiki a poskytuje
-odpovede o prácach, projektoch, rokoch a súvisiacich vzťahoch so zdrojovými odkazmi.
+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. Načíta Markdown dokumenty a YAML metadáta z lokálnej kópie Git repozitára.
-2. Rozdelí obsah na tokenové úseky a vytvorí textový, vektorový a grafový index.
-3. Spoločný Pydantic plán zachová osoby, roly, práce, časové podmienky a požadované údaje.
-   Jednoznačné otázky plánuje priamo; nové formulácie pomáha overene interpretovať LLM.
-   Podľa plánu vyhľadá textové podklady alebo grafové fakty; neznáme podmienky nevynechá.
-4. Pri opisoch a porovnaniach model navrhne prirodzené tvrdenia s konkrétnymi dôkazmi.
-5. Backend skontroluje väzby, čísla a citácie; podporu preverí oddelené LLM volanie, rizikové tvrdenia aj druhý posudok.
-6. Pri zlyhaní syntézy zostane pôvodná doložená odpoveď. Názvy, počty a presné zoznamy zostavuje priamo.
+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á.
 
-Aktualizáciu možno spustiť manuálne alebo webhookom z Gitea. Docker nasadenie
-ju plánuje aj každých 24 hodín (`WIKI_SYNC_INTERVAL_SECONDS=86400`).
-`SYNC_UPSTREAM_FORK=1` bezpečne dopĺňa fork `jp170na/zpwiki` z `KEMT/zpwiki`;
-do originálu nezapisuje. Vyžaduje bežiaci backend a SSH prístup do forku.
-Textový index, metadátový graf a už zapnutá obsahová extrakcia sa pripravujú
-z rovnakého snapshotu a aktivujú spoločne. Pri chybe zostáva predchádzajúca verzia.
+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 fulltextové vyhľadávanie BM25 so sémantickým vyhľadávaním
-pomocou embeddingov. Samostatné výsledky spája metódou RRF; osobu, typ a rok filtruje záväzne.
-Je vhodný na otázky na obsah, zadanie, metódy, priebeh a výsledky práce.
+**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** využíva metadátové dotazy a ohraničené prechody cez osoby, práce,
-činnosti, témy a dôkazy v Neo4j. Prepojenia vysvetľuje zdrojovými výňatkami oboch prác.
-Cypher šablóny sú pevné; jazykový model nevykonáva ľubovoľné databázové príkazy.
+**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 dopĺňa pojmy a vzťahy extrahované jazykovým modelom z profilov
-študentov. Každý poznatok uchováva doslovný výňatok, aktéra, konkrétnu prácu,
-fázu a oddelený dátum záznamu, vykonania či plánovaný termín. Podporuje otázky na pokrok, čas výsledkov,
-podobné témy a študentov venujúcich sa určitej činnosti. Zadanie ani plán
-sa nevydávajú za dokončený výsledok; chýbajúce údaje sa neodhadujú.
-Pri výsledkoch sa rozlišuje dátum záznamu od skutočného dňa vykonania práce.
-Model spracúva najviac osem jednotiek naraz a rozhoduje o každej z nich;
-neisté poznatky sa nepoužijú ako fakty. Vzťahy vyžadujú doslovný dôkaz aj
-samostatné modelové overenie. Chýbajúce rozhodnutie zablokuje publikovanie.
-Repozitárové odkazy sa overujú cez verejné API; neoveriteľné odkazy sa nezobrazujú.
-
-Extrakciu spúšťa `python -m tools.knowledge.build` s nakonfigurovaným LLM API.
-Vyžaduje pripravené spoločné indexy a Neo4j. Nezmenené vstupy využívajú cache;
-po prvom vytvorení sa obsahový index obnovuje aj pri synchronizácii.
-Claude Skills sú klientom rovnakého backendu, jeho logika nezávisí od rozhrania.
-`ANSWER_STRUCTURED_OUTPUT=json_schema` zapína schému u podporujúceho poskytovateľa.
-Predvolene sa používa prompt a lokálna typová aj významová kontrola plánu.
-Voliteľný Compose profil `claude-tunnel` pripája Cloudflare priamo k službe MCP
-v Docker sieti. Dočasná verejná URL vyžaduje zodpovedajúce OAuth nastavenie
-`ZP_MCP_PUBLIC_URL`; po vytvorení nového tunela sa môže zmeniť.
+**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 a Pydantic** – API, validácia vstupov a typované odpovede.
-- **SQLite a FTS5** – dokumenty, metadáta, fulltextový index a uložené vektory.
-- **Sentence Transformers a multilingual-e5-small** – viacjazyčné embeddingy.
-- **Tiktoken** – meranie veľkosti a delenie textových úsekov.
-- **Neo4j a Cypher** – uloženie a vyhľadávanie grafových vzťahov.
-- **MCP a Claude Skills** – sprístupnenie RAG a GraphRAG používateľovi v Claude.
-- **OAuth s PKCE** – autentizácia webového MCP konektora.
-- **Docker Compose** – spoločné nasadenie API, Neo4j a MCP servera.
-- **Git a Gitea webhooky** – získavanie zmien a spúšťanie synchronizácie.
-- **Pytest a evaluačné skripty** – regresie, kontrola vyhľadávania a odpovedí.
+- **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.
 
-## Súčasný stav
+## Architektúra
 
-RAG, GraphRAG, kontrolovaná cesta odpovedí a pripojenie cez Claude sú funkčné.
-Systém obsahuje embeddingovú cache, kontroly dostupnosti a persistentnú
-synchronizačnú frontu. `/health` samostatne uvádza vyhľadávanie, obsahové
-poznatky a generovanie. Dostupnosť modelu eviduje po jeho použití alebo po
-explicitnom autentifikovanom `POST /health/generation`; samotná kontrola
-`GET /health` model nevolá. Historické evaluácie sú oddelené od prevádzkového kódu.
-Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.
+```
+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
+```
 
-## Organizácia projektu
+## Spustenie
 
-- `app/` – HTTP API a zabezpečenie.
-- `tools/rag/`, `tools/graphrag/`, `tools/knowledge/` – vyhľadávanie a indexovanie.
-- `tools/answers/` – príprava podkladov, kontroly a zostavenie odpovede.
-- `tools/retrieval/`, `tools/sync/`, `tools/runtime/` – spoločné pravidlá a prevádzka.
-- Offline evaluátory, diagnostika a testovacia sada sú lokálne v `local/evaluation/` (mimo Gitu).
-- `packages/claude/`, `deployment/`, `scripts/` – klienti, nasadenie a spúšťanie.
+```bash
+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
+```
 
-Prevádzkový image neobsahuje testy ani historické experimenty. Spúšťa sa cez
-`bash scripts/start.sh`; voliteľné služby ovláda `bash scripts/compose.sh`.
-Regresie spúšťa `.venv/bin/python -m pytest -q test tools/rag/tests tools/graphrag/tests`.
-Otázky, merania, historické výsledky a interná dokumentácia sú lokálne v `local/` mimo Gitu.
-Offline evaluátory vyžadujú príslušné lokálne dátové súbory; agent ich na beh nepotrebuje.
+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.