# 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.