ZP Agent

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.

Implementované funkcie

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.

Architektúra

zpwiki (Git) -> Markdown/YAML -> spoločný snapshot
                                      |-- SQLite: FTS5 + embeddingy
                                      `-- Neo4j: entity + vzťahy

Claude + Skills -> HTTPS/OAuth -> MCP -> FastAPI /answer
                                             |
                                +------------+------------+
                                |                         |
                           RAG / SQLite            GraphRAG / Neo4j
                                |                         |
                                +------------+------------+
                                             |
                              model -> kontroly -> renderer
                                             |
                                  odpoveď + zdrojové odkazy

/rag a /graphrag vracajú podklady. /answer vykonáva kontrolovanú prípravu odpovede; pri nedostatočných dôkazoch informáciu nedopĺňa odhadom.

Štruktúra

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.

Spustenie

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.

./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. Klientské pokyny sú v RAG Skill a GraphRAG Skill. 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.

4.2 KiB Raw Blame History