From 49c8159e2afdf74755a7f4dd64e69ae094b36b11 Mon Sep 17 00:00:00 2001 From: jp170na Date: Wed, 4 Nov 2026 14:41:59 +0100 Subject: [PATCH] =?UTF-8?q?Stru=C4=8Dn=C3=BD=20opis=20projektu?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 106 ++++++++++++++++++------------------------------------ 1 file changed, 34 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index e29523d..07c2f7b 100644 --- a/README.md +++ b/README.md @@ -3,86 +3,48 @@ Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom záverečných prác `zpwiki`. -## Účel - Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**. -Spracúva profily študentov, zadania a priebežné poznámky zo ZP Wiki. -Poskytuje dohľadateľné odpovede o prácach, projektoch, rokoch a vzťahoch -prostredníctvom klasického RAG a grafového vyhľadávania v Neo4j. +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. -## Implementované funkcie +## Ako funguje -- Import Markdownov a YAML metadát, štruktúrne tokenové chunkovanie. -- SQLite FTS5/BM25, viacjazyčné embeddingy E5 a hybridné radenie RRF. -- Segmentácia finálnych embeddingových vstupov a cache nezmenených vektorov. -- Deterministický znalostný graf a parametrizované vyhľadávanie v Neo4j. -- Kontrola faktov, väzieb, citácií, počtov a úplnosti pred doručením odpovede. -- Rozlíšenie zadania, plánov, priebežného stavu a výsledkov práce. -- Spoločná synchronizácia SQLite a Neo4j z Gitu, webhook a persistentná fronta. -- FastAPI, Docker Compose, kontroly dostupnosti a modelové assets pre offline štart. -- Claude Skills a MCP konektor s OAuth/PKCE pre RAG, GraphRAG a stav služieb. -- Retrieval evaluácia, zdrojové audity a automatické regresné testy. +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. Podľa zvoleného nástroja vyhľadá relevantné texty alebo grafové fakty. +4. Jazykový model vyberie dôkazy alebo navrhne štruktúrované tvrdenia. +5. Backend skontroluje hodnoty, väzby, citácie a pokrytie požadovaných údajov. +6. Z overených podkladov zostaví odpoveď; chýbajúce informácie výslovne označí. -## Architektúra +Aktualizáciu možno spustiť manuálne alebo webhookom z Gitea. Oba indexy +sa obnovujú z rovnakého snapshotu a používajú spoločnú verziu dát. -```text -zpwiki (Git) -> Markdown/YAML -> spoločný snapshot - |-- SQLite: FTS5 + embeddingy - `-- Neo4j: entity + vzťahy +## Vyhľadávanie -Claude + Skills -> HTTPS/OAuth -> MCP -> FastAPI /answer - | - +------------+------------+ - | | - RAG / SQLite GraphRAG / Neo4j - | | - +------------+------------+ - | - model -> kontroly -> renderer - | - odpoveď + zdrojové odkazy -``` +**RAG** kombinuje fulltextové vyhľadávanie BM25 so sémantickým vyhľadávaním +pomocou embeddingov. Výsledky spája metódou RRF. Je vhodný na otázky +na obsah, zadanie, metódy, priebeh a výsledky práce. -`/rag` a `/graphrag` vracajú podklady. `/answer` vykonáva kontrolovanú -prípravu odpovede; pri nedostatočných dôkazoch informáciu nedopĺňa odhadom. +**GraphRAG** využíva znalostný graf osôb, dokumentov, prác, projektov, +tém, tagov a kategórií. Umožňuje vyhľadávať vzťahy, spoločné vlastnosti +a kombinácie podmienok, napríklad tag spolu s typom a rokom práce. -## Štruktúra +## Použité technológie -| Priečinok | Obsah | -| --- | --- | -| `app/` | FastAPI, vstupné modely a autorizácia. | -| `tools/rag/` | Import, chunky, SQLite a hybridné vyhľadávanie. | -| `tools/graphrag/` | Dátový model, Neo4j, grafové dotazy a evaluácia. | -| `tools/answers/`, `tools/answer_evaluation/` | Generovanie, dôkazy, kontroly a metriky. | -| `tools/retrieval/`, `tools/sync/`, `tools/runtime/` | Kontrakty, synchronizácia a prevádzka. | -| `packages/claude/` | Skills, MCP, OAuth, klient a inštalovateľné ZIPy. | -| `deployment/`, `scripts/` | Docker, závislosti, štart a overovacie skripty. | -| `test/`, `tools/*/tests/` | Jednotkové a integračné regresie. | +- **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í. -## Spustenie +## Súčasný stav -Vyžaduje Docker s Compose v2 a Buildx, lokálny klon wiki v `../zpwiki` -a súbor `.env` s konfiguráciou kľúčov, Neo4j, Git prístupu a modelového API. -Prvý build potrebuje sieť na získanie závislostí a modelových súborov. -Pre webový Claude treba navyše dostupnú HTTPS adresu MCP a OAuth nastavenia. - -```bash -./scripts/start_project.sh -./scripts/compose.sh --profile claude up -d --build -curl http://127.0.0.1:8000/health -``` - -Konfiguráciu služieb určuje [Docker Compose](deployment/docker-compose.yml). -Klientské pokyny sú v [RAG Skill](packages/claude/rag/SKILL.md) a -[GraphRAG Skill](packages/claude/graphrag/SKILL.md). -Balíky sa zostavia cez `python scripts/build_claude_packages.py`. -Lokálne overenie poskytuje `scripts/verify_project.py` po príprave jeho závislostí. - -## Stav a ďalší vývoj - -Obe vetvy a kontrolovaná cesta odpovedí sú funkčné a overené aj cez Claude. -Prototyp používa dočasný HTTPS tunel; trvalé nasadenie zostáva ďalšou etapou. -Plánované sú tolerantné rozpoznávanie mien, hlavný agent, Git nástroje, -CRZP, plné texty prác a spoločné porovnanie RAG/GraphRAG a modelov. -Historické merania sú v evaluačných priečinkoch; nepredstavujú univerzálnu -záruku presnosti aktuálneho agenta. Tajomstvá, databázy a modelové váhy nepatria na Git. +RAG, GraphRAG, kontrolovaná cesta odpovedí a pripojenie cez Claude sú funkčné. +Systém obsahuje embeddingovú cache, kontroly dostupnosti a persistentnú +synchronizačnú frontu. Historické evaluácie sú uložené pri jednotlivých vetvách. +Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.