dp-zp-agent/README.md

dp-zp-agent

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

Projekt zatiaľ rieši základnú časť systému pre vyhľadávanie v Markdown súboroch zo školského repozitára záverečných prác. Cieľom je vytvoriť samostatnú službu, ktorá vie indexovať obsah zpwiki, vyhľadávať v ňom a neskôr sa napojí na OpenWebUI, RAG, znalostný graf a webhook synchronizáciu.

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 /health a /search,
9. automatická Swagger dokumentácia API.

Štruktúra projektu

dp-zp-agent/
├── app/
│   ├── __init__.py
│   └── main.py
├── scripts/
│   ├── scan_zpwiki.py
│   ├── build_chunks.py
│   ├── build_sqlite_index.py
│   ├── search_chunks.py
│   └── search_db.py
├── data/
├── requirements.txt
├── .gitignore
└── README.md

Príprava prostredia

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

Odporúčaná štruktúra:

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

Vytvorenie a aktivácia Python prostredia:

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:

python scripts/scan_zpwiki.py

Potom sa dokumenty rozdelia na chunky:

python scripts/build_chunks.py

Nakoniec sa vytvorí SQLite index:

python scripts/build_sqlite_index.py

Testovanie vyhľadávania v termináli

Vyhľadávanie podľa osoby:

python scripts/search_db.py "jan ptak"

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

python scripts/search_db.py "rag agent"

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

python scripts/search_db.py "knowledge graph"

Spustenie API

FastAPI server sa spustí príkazom:

uvicorn app.main:app --reload

Health check:

curl http://127.0.0.1:8000/health

Vyhľadávanie cez API:

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

Swagger UI

FastAPI automaticky generuje Swagger dokumentáciu API.

Po spustení servera je dostupná na adrese:

http://127.0.0.1:8000/docs

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

Čo ešte treba dorobiť

1. Dockerizácia aplikácie

Treba vytvoriť:

1. Dockerfile,
2. docker-compose.yml,
3. jednoduchý návod na spustenie cez Docker,
4. volume alebo mount pre dáta a SQLite databázu.

Cieľ je, aby sa služba dala spustiť jedným príkazom:

docker compose up --build

2. 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:

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.

3. Synchronizácia so zpwiki

Treba pridať mechanizmus, ktorý bude vedieť aktualizovať dáta zo školského repozitára.

Plánované časti:

1. skript pre git pull,
2. zistenie aktuálneho commitu,
3. detekcia zmenených Markdown súborov,
4. reindexovanie zmenených dokumentov,
5. uloženie stavu synchronizácie do databázy.

4. Webhook endpoint pre Gitea

Treba vytvoriť endpoint napríklad:

POST /webhook/gitea

Tento endpoint má:

1. prijať webhook z Gitea,
2. overiť secret alebo podpis webhooku,
3. spustiť synchronizáciu repozitára,
4. spustiť reindexovanie zmenených súborov,
5. zapísať výsledok do logu alebo tabuľky synchronizácie.

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

6. 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:

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

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

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

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

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

11. 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 webhook synchronizácie,
9. návrh integrácie s OpenWebUI,
10. popis experimentov a vyhodnotenia.

Najbližší praktický krok

Najbližšie treba spraviť Docker nasadenie aktuálneho FastAPI prototypu.