README

2026-06-03 21:20:25 +02:00 · 2026-06-03 21:20:25 +02:00 · 6078c734c8
commit 6078c734c8
parent 1895ebd8d9
1 changed files with 332 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,332 @@
+# 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
+
+```text
+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:
+
+```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
+```
+
+## 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
+
+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}'
+```
+
+## 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` 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:
+
+```bash
+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:
+
+```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.
+
+### 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 Git
+
+Treba vytvoriť endpoint napríklad:
+
+```text
+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.
+
+Poradie najbližších krokov:
+
+1. doplniť `README.md`,
+2. pushnúť projekt na KEMT Git,
+3. vytvoriť `Dockerfile`,
+4. vytvoriť `docker-compose.yml`,
+5. spustiť API cez Docker,
+6. pripraviť základ pre webhook synchronizáciu.