# dp-zp-agent

Agent pre manažment záverečných prác nad repozitárom `zpwiki`.

Projekt rieši základnú službu pre indexovanie a vyhľadávanie v Markdown súboroch zo školského repozitára záverečných prác. Cieľom je vytvoriť samostatné API, ktoré vie načítať obsah `zpwiki`, spracovať metadata, rozdeliť dokumenty na chunky, vyhľadávať v nich a neskôr sa napojiť na OpenWebUI, RAG, znalostný graf a Gitea webhook.

## Aktuálny stav

Zatiaľ je implementované:

1. načítanie Markdown súborov z repozitára `zpwiki`,
2. extrakcia metadát z YAML front matter,
3. spracovanie položiek `taxonomy`, hlavne kategórie, tagy a autor,
4. rozdelenie dokumentov na menšie textové chunky,
5. vytvorenie SQLite indexu,
6. jednoduché fulltextové vyhľadávanie nad chunkmi,
7. rozlíšenie režimu vyhľadávania:
   1. `person` pre mená osôb, napríklad `jan ptak`,
   2. `topic` pre tematické dopyty, napríklad `rag agent` alebo `knowledge graph`,
8. FastAPI backend s endpointmi:
   1. `/health`,
   2. `/search`,
   3. `/sync`,
9. automatická Swagger dokumentácia API,
10. Dockerfile pre zostavenie API kontajnera,
11. `docker-compose.yml` pre spustenie služby,
12. mount repozitára `zpwiki` do kontajnera,
13. environment premenná `ZPWIKI_ROOT`,
14. reindexovanie dát cez endpoint `/sync`.

## Štruktúra projektu

```text
dp-zp-agent/
├── app/
│   ├── __init__.py
│   └── main.py
├── scripts/
│   ├── scan_zpwiki.py
│   ├── build_chunks.py
│   ├── build_sqlite_index.py
│   ├── rebuild_index.py
│   ├── search_chunks.py
│   └── search_db.py
├── data/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .dockerignore
├── .gitignore
└── README.md
```

## Príprava prostredia

Projekt očakáva, že vedľa neho existuje naklonovaný repozitár `zpwiki`.

Odporúčaná štruktúra:

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

Vytvorenie a aktivácia Python prostredia:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Vygenerovanie dát a indexu

Najprv sa načítajú dokumenty a metadata:

```bash
python scripts/scan_zpwiki.py
```

Potom sa dokumenty rozdelia na chunky:

```bash
python scripts/build_chunks.py
```

Nakoniec sa vytvorí SQLite index:

```bash
python scripts/build_sqlite_index.py
```

Alebo sa dá celý index obnoviť jedným príkazom:

```bash
python scripts/rebuild_index.py
```

S voliteľným `git pull` pred reindexovaním:

```bash
python scripts/rebuild_index.py --pull
```

## Testovanie vyhľadávania v termináli

Vyhľadávanie podľa osoby:

```bash
python scripts/search_db.py "jan ptak"
```

Vyhľadávanie podľa témy:

```bash
python scripts/search_db.py "rag agent"
```

Vyhľadávanie podľa znalostného grafu:

```bash
python scripts/search_db.py "knowledge graph"
```

## Spustenie API lokálne

FastAPI server sa spustí príkazom:

```bash
uvicorn app.main:app --reload
```

Health check:

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

Vyhľadávanie cez API:

```bash
curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query":"jan ptak","limit":5}'
```

Reindexovanie cez API:

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

Reindexovanie aj s `git pull`:

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

Poznámka: pri Docker verzii môže `pull_git:true` vyžadovať vyriešenie SSH prístupu ku Gitu. Zatiaľ je bezpečné používať hlavne `pull_git:false`.

## Swagger UI

FastAPI automaticky generuje Swagger dokumentáciu API.

Po spustení servera je dostupná na adrese:

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

V Swagger UI je možné testovať endpointy `/health`, `/search` a `/sync` priamo z prehliadača.

## Spustenie cez Docker

Služba sa dá spustiť cez Docker Compose:

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

Po spustení je API dostupné na:

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

Swagger UI:

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

Health check:

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

Vyhľadávanie:

```bash
curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query":"knowledge graph","limit":5}'
```

Reindexovanie:

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

V `docker-compose.yml` je repozitár `zpwiki` pripojený ako volume:

```yaml
volumes:
  - ./data:/app/data
  - ../zpwiki:/zpwiki
```

A cesta k nemu je nastavená cez environment premennú:

```yaml
environment:
  - ZPWIKI_ROOT=/zpwiki
```

## Čo ešte treba dorobiť

### 1. Upratanie kódu do modulov

Aktuálne je veľká časť logiky priamo v `app/main.py`. Neskôr treba kód rozdeliť napríklad takto:

```text
app/
├── main.py
├── search.py
├── database.py
├── schemas.py
├── sync.py
└── webhook.py
```

Cieľ je, aby API, vyhľadávanie, databáza a synchronizácia neboli v jednom veľkom súbore.

### 2. Vylepšenie synchronizácie so `zpwiki`

Aktuálne endpoint `/sync` vie obnoviť celý index. Neskôr treba pridať efektívnejšiu synchronizáciu.

Treba dorobiť:

1. zistenie aktuálneho commitu,
2. uloženie posledného spracovaného commitu,
3. detekciu zmenených Markdown súborov,
4. reindexovanie iba zmenených dokumentov,
5. uloženie stavu synchronizácie do databázy,
6. logovanie výsledkov synchronizácie.

### 3. Webhook endpoint pre Gitea

Treba vytvoriť endpoint napríklad:

```text
POST /webhook/gitea
```

Tento endpoint má:

1. prijať webhook z Gitea,
2. overiť secret alebo podpis webhooku,
3. spracovať push event,
4. spustiť synchronizáciu repozitára,
5. spustiť reindexovanie,
6. vrátiť výsledok synchronizácie.

### 4. OpenWebUI integrácia

Treba napojiť API na OpenWebUI.

Možné riešenia:

1. OpenAPI tool server,
2. OpenWebUI tool,
3. OpenWebUI pipeline,
4. vlastný agent, ktorý bude volať endpoint `/search`.

Cieľ je, aby používateľ mohol v OpenWebUI položiť otázku a agent použil vyhľadávanie nad `zpwiki`.

### 5. Embeddingy a vektorové vyhľadávanie

Aktuálne vyhľadávanie je fulltextové a skórovacie. Ďalší krok je pridať embeddingy.

Treba dorobiť:

1. výber embedding modelu,
2. generovanie embeddingov pre chunky,
3. uloženie embeddingov,
4. vektorové vyhľadávanie,
5. porovnanie fulltextového a vektorového vyhľadávania.

Možné databázy alebo nástroje:

1. PostgreSQL plus pgvector,
2. Qdrant,
3. ChromaDB,
4. FAISS ako jednoduchý lokálny prototyp.

### 6. RAG odpovede s citáciami

Treba doplniť generovanie odpovede pomocou jazykového modelu.

Postup:

1. používateľ položí otázku,
2. systém nájde relevantné chunky,
3. chunkom priradí zdrojové URL,
4. jazykový model vytvorí odpoveď iba z nájdeného kontextu,
5. odpoveď obsahuje odkazy na zdrojové stránky.

Cieľ je, aby agent nehalucinoval a vedel ukázať, z ktorých dokumentov odpovedal.

### 7. Znalostný graf

Treba vytvoriť štruktúrovaný graf nad dátami zo `zpwiki`.

Základné entity:

1. `Student`,
2. `Thesis`,
3. `Tag`,
4. `Category`,
5. `Author`,
6. `Year`.

Základné vzťahy:

1. študent má prácu,
2. práca má tag,
3. práca patrí do kategórie,
4. autor vedie alebo spravuje prácu,
5. práca je podobná inej práci,
6. práca patrí do roka alebo obdobia.

### 8. GraphRAG

Treba prepojiť RAG a znalostný graf.

GraphRAG časť má umožniť:

1. vyhľadávanie podľa vzťahov,
2. vysvetlenie, prečo sa našli konkrétne práce,
3. odporúčanie podobných tém,
4. analýzu tém podľa tagov, rokov a kategórií,
5. kombináciu textového, vektorového a grafového vyhľadávania.

### 9. Vyhodnotenie systému

Treba pripraviť testovaciu sadu otázok a porovnať viacero prístupov.

Porovnať treba minimálne:

1. jednoduché fulltextové vyhľadávanie,
2. vektorové vyhľadávanie,
3. RAG,
4. GraphRAG.

Príklady testovacích otázok:

1. `Nájdi práce o RAG.`
2. `Nájdi práce podobné téme Agent pre manažment záverečných prác.`
3. `Ktoré práce používajú znalostný graf?`
4. `Kto riešil chatbot alebo agenta?`
5. `Aké témy patria do kategórie dp2027?`
6. `Zhrň práce súvisiace s NLP.`

Sledované vlastnosti:

1. relevantnosť výsledkov,
2. správnosť odpovede,
3. správnosť citácií,
4. počet halucinácií,
5. čas odpovede,
6. čas reindexovania po zmene v Gite.

### 10. Dokumentácia do diplomovej práce

Treba priebežne písať:

1. čo je RAG,
2. čo je generatívny model,
3. čo je znalostný graf,
4. čo je GraphRAG,
5. ako funguje `zpwiki`,
6. návrh architektúry systému,
7. návrh databázy a indexu,
8. návrh synchronizácie,
9. návrh webhook integrácie,
10. návrh integrácie s OpenWebUI,
11. popis experimentov a vyhodnotenia.

## Najbližší praktický krok

Najbližšie treba spraviť Gitea webhook endpoint.

Poradie najbližších krokov:

1. commitnúť aktuálne zmeny,
2. pushnúť projekt na KEMT Git,
3. vytvoriť endpoint `POST /webhook/gitea`,
4. pridať overenie secretu alebo podpisu webhooku,
5. napojiť webhook na `/sync`,
6. otestovať webhook lokálne alebo cez verejne dostupný tunel.