From 0a29548db6ea50dbb8bde89bf9b896a27f839c54 Mon Sep 17 00:00:00 2001 From: jp170na Date: Sat, 14 Nov 2026 03:29:53 +0100 Subject: [PATCH] =?UTF-8?q?Aktualiz=C3=A1cia=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- README.md | 159 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 84 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index b69c214..cd0cc9c 100644 --- a/README.md +++ b/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.