dp-zp-agent/README.md

# ZP Agent

Backend pre indexovanie a vyhľadávanie v repozitári záverečných prác `zpwiki`.

Projekt načítava Markdown dokumenty, spracuje YAML metadata, rozdelí obsah na tokenové chunky a vytvorí SQLite index kombinujúci FTS5 fulltextové vyhľadávanie a embeddingy. Vyhľadávanie je dostupné cez FastAPI a systém podporuje manuálnu aj webhookovú synchronizáciu.

## Implementované

- načítanie Markdown súborov a YAML front matter,
- normalizácia názvov, autorov, tagov, kategórií a `published`,
- tokenové chunkovanie pomocou `tiktoken`,
- zachovanie názvu dokumentu a hierarchie nadpisov v chunku,
- SQLite databáza a FTS5 fulltextový index,
- BM25 vyhľadávanie s podporou diakritiky a prefixových výrazov,
- embeddingy pre každý chunk pomocou modelu `intfloat/multilingual-e5-small`,
- uloženie embeddingov priamo v SQLite,
- vektorové vyhľadávanie pomocou cosine similarity,
- hybridné vyhľadávanie FTS5 + embeddings pomocou RRF,
- nižšia váha pre slabú `any_term` FTS stratégiu,
- zachovanie presných `all_terms` a `prefix_terms` výsledkov bez vektorového šumu,
- filtrovanie publikovaných dokumentov,
- FastAPI endpointy `/health`, `/search`, `/sync` a `/webhook/gitea`,
- autorizácia `/search` a `/sync` pomocou API kľúča,
- Gitea webhook s HMAC-SHA256 podpisom a kontrolou udalosti a repozitára,
- zámok proti súbežnému reindexovaniu,
- atomická výmena databázy po úspešnom reindexovaní,
- automatizované a integračné testy.

## Štruktúra

```text
zp-agent/
├── app/
│   └── main.py
├── scripts/
│   ├── common.py
│   ├── scan_zpwiki.py
│   ├── build_chunks.py
│   ├── build_sqlite_index.py
│   ├── embedding_utils.py
│   ├── rebuild_index.py
│   ├── search_db.py
│   └── search_utils.py
├── test/
├── data/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── requirements-dev.txt
└── README.md
```

Projekt očakáva repozitáre v tejto štruktúre:

```text
~/DP/
├── zpwiki/
└── zp-agent/
```

## Konfigurácia

V koreňovom priečinku vytvor `.env`:

```dotenv
WEBHOOK_SECRET=<náhodná hodnota s minimálne 32 znakmi>
SYNC_API_KEY=<iná náhodná hodnota s minimálne 32 znakmi>
SEARCH_API_KEY=<ďalšia náhodná hodnota s minimálne 32 znakmi>
EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki
WEBHOOK_PULL_GIT=false

# Voliteľné
EMBEDDING_MODEL=intfloat/multilingual-e5-small
EMBEDDING_BATCH_SIZE=32
```

Tajomstvá je možné vygenerovať príkazom:

```bash
openssl rand -hex 32
```

Súbor `.env` sa nesmie commitovať.

## Spustenie cez Docker

```bash
docker compose build
docker compose up -d
```

Kontrola služby:

```bash
curl http://127.0.0.1:8000/health
```

Swagger UI:

```text
http://127.0.0.1:8000/docs
```

Zastavenie:

```bash
docker compose down
```

## Reindexovanie

Celý proces načíta dokumenty, vytvorí chunky, obnoví FTS5 index a vytvorí embedding pre každý chunk:

```bash
docker compose run --rm zp-agent-api python scripts/rebuild_index.py
```

Vzniknú súbory:

```text
data/documents.json
data/chunks.json
data/zp_index.sqlite
```

Databáza obsahuje dokumenty, chunky, FTS5 index, metadata a embeddingy.

## Vyhľadávanie

Vyhľadávanie kombinuje:

```text
dotaz
├── FTS5 / BM25
└── embeddingové vyhľadávanie
        ↓
   RRF fusion
        ↓
   výsledky
```

Test z terminálu:

```bash
docker compose run --rm zp-agent-api \
  python scripts/search_db.py "rag agent" --limit 5
```

Pred volaním API načítaj premenné z `.env`:

```bash
set -a
source .env
set +a
```

Vyhľadávanie cez zabezpečené API:

```bash
curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SEARCH_API_KEY" \
  -d '{
    "query": "rag agent",
    "limit": 5,
    "published_only": false,
    "max_per_document": 3
  }'
```

API vracia hybridný engine:

```text
hybrid_fts5_embeddings
```

Manuálne reindexovanie cez zabezpečený endpoint:

```bash
curl -X POST http://127.0.0.1:8000/sync \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SYNC_API_KEY" \
  -d '{"pull_git": false}'
```

## Testy

Inštalácia testovacích závislostí:

```bash
pip install -r requirements-dev.txt
```

Bežné automatizované testy:

```bash
pytest -q test
```

Aktuálna testovacia sada:

```text
65 passed, 2 skipped
```

Testy vrátane kontroly reálne vygenerovaných dát a databázy:

```bash
RUN_LIVE_TESTS=1 pytest -q test
```

## Ďalší krok

Najbližšia etapa je integrácia s OpenWebUI a vytvorenie agentového rozhrania. Následne sa doplnia RAG odpovede so zdrojmi a citáciami.