# 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 FTS5 index. 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,
- filtrovanie publikovaných dokumentov,
- FastAPI endpointy `/health`, `/search`, `/sync` a `/webhook/gitea`,
- autorizácia `/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 nad reálnymi dátami.

## Štruktúra

```text
zp-agent/
├── app/
│   └── main.py
├── scripts/
│   ├── common.py
│   ├── scan_zpwiki.py
│   ├── build_chunks.py
│   ├── build_sqlite_index.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>
EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki
WEBHOOK_PULL_GIT=false
```

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 --no-cache
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 a obnoví SQLite FTS5 index:

```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
```

## Vyhľadávanie

Test z terminálu:

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

Vyhľadávanie cez API:

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

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
```

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

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

Aktuálna implementácia prešla všetkými 65 testami vrátane live testov.

## Ďalší krok

Najbližšia etapa je integrácia s OpenWebUI a vytvorenie agentového rozhrania. Následne sa doplnia embeddingy, hybridné vyhľadávanie a RAG odpovede s citáciami.