89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|
|
|
|
```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.
|