Update README

README.md

@@ -2,7 +2,7 @@
 
 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.
+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
 
@@ -17,8 +17,16 @@ Zatiaľ je implementované:
 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`,
+8. FastAPI backend s endpointmi:
-9. automatická Swagger dokumentácia API.
+   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
 
@@ -31,10 +39,14 @@ dp-zp-agent/
 │   ├── 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
 ```
@@ -79,6 +91,18 @@ Nakoniec sa vytvorí SQLite index:
 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:
@@ -99,7 +123,7 @@ Vyhľadávanie podľa znalostného grafu:
 python scripts/search_db.py "knowledge graph"
 ```
 
-## Spustenie API
+## Spustenie API lokálne
 
 FastAPI server sa spustí príkazom:
 
@@ -121,6 +145,24 @@ curl -X POST http://127.0.0.1:8000/search \
   -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.
@@ -131,26 +173,68 @@ 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.
+V Swagger UI je možné testovať endpointy `/health`, `/search` a `/sync` priamo z prehliadača.
 
-## Čo ešte treba dorobiť
+## Spustenie cez Docker
 
-### 1. Dockerizácia aplikácie
+Služba sa dá spustiť cez Docker Compose:
-
-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
+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:
 
@@ -166,19 +250,20 @@ app/
 
 Cieľ je, aby API, vyhľadávanie, databáza a synchronizácia neboli v jednom veľkom súbore.
 
-### 3. Synchronizácia so `zpwiki`
+### 2. Vylepšenie synchronizácie so `zpwiki`
 
-Treba pridať mechanizmus, ktorý bude vedieť aktualizovať dáta zo školského repozitára.
+Aktuálne endpoint `/sync` vie obnoviť celý index. Neskôr treba pridať efektívnejšiu synchronizáciu.
 
-Plánované časti:
+Treba dorobiť:
 
-1. skript pre `git pull`,
+1. zistenie aktuálneho commitu,
-2. zistenie aktuálneho commitu,
+2. uloženie posledného spracovaného commitu,
-3. detekcia zmenených Markdown súborov,
+3. detekciu zmenených Markdown súborov,
-4. reindexovanie zmenených dokumentov,
+4. reindexovanie iba zmenených dokumentov,
-5. uloženie stavu synchronizácie do databázy.
+5. uloženie stavu synchronizácie do databázy,
+6. logovanie výsledkov synchronizácie.
 
-### 4. Webhook endpoint pre Git
+### 3. Webhook endpoint pre Gitea
 
 Treba vytvoriť endpoint napríklad:
 
@@ -190,11 +275,12 @@ Tento endpoint má:
 
 1. prijať webhook z Gitea,
 2. overiť secret alebo podpis webhooku,
-3. spustiť synchronizáciu repozitára,
+3. spracovať push event,
-4. spustiť reindexovanie zmenených súborov,
+4. spustiť synchronizáciu repozitára,
-5. zapísať výsledok do logu alebo tabuľky synchronizácie.
+5. spustiť reindexovanie,
+6. vrátiť výsledok synchronizácie.
 
-### 5. OpenWebUI integrácia
+### 4. OpenWebUI integrácia
 
 Treba napojiť API na OpenWebUI.
 
@@ -207,7 +293,7 @@ Možné riešenia:
 
 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
+### 5. Embeddingy a vektorové vyhľadávanie
 
 Aktuálne vyhľadávanie je fulltextové a skórovacie. Ďalší krok je pridať embeddingy.
 
@@ -219,14 +305,14 @@ Treba dorobiť:
 4. vektorové vyhľadávanie,
 5. porovnanie fulltextového a vektorového vyhľadávania.
 
-Možné databázy:
+Možné databázy alebo nástroje:
 
 1. PostgreSQL plus pgvector,
 2. Qdrant,
 3. ChromaDB,
 4. FAISS ako jednoduchý lokálny prototyp.
 
-### 7. RAG odpovede s citáciami
+### 6. RAG odpovede s citáciami
 
 Treba doplniť generovanie odpovede pomocou jazykového modelu.
 
@@ -240,7 +326,7 @@ Postup:
 
 Cieľ je, aby agent nehalucinoval a vedel ukázať, z ktorých dokumentov odpovedal.
 
-### 8. Znalostný graf
+### 7. Znalostný graf
 
 Treba vytvoriť štruktúrovaný graf nad dátami zo `zpwiki`.
 
@@ -262,7 +348,7 @@ Základné vzťahy:
 5. práca je podobná inej práci,
 6. práca patrí do roka alebo obdobia.
 
-### 9. GraphRAG
+### 8. GraphRAG
 
 Treba prepojiť RAG a znalostný graf.
 
@@ -274,7 +360,7 @@ GraphRAG časť má umožniť:
 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
+### 9. Vyhodnotenie systému
 
 Treba pripraviť testovaciu sadu otázok a porovnať viacero prístupov.
 
@@ -303,7 +389,7 @@ Sledované vlastnosti:
 5. čas odpovede,
 6. čas reindexovania po zmene v Gite.
 
-### 11. Dokumentácia do diplomovej práce
+### 10. Dokumentácia do diplomovej práce
 
 Treba priebežne písať:
 
@@ -314,19 +400,20 @@ Treba priebežne písať:
 5. ako funguje `zpwiki`,
 6. návrh architektúry systému,
 7. návrh databázy a indexu,
-8. návrh webhook synchronizácie,
+8. návrh synchronizácie,
-9. návrh integrácie s OpenWebUI,
+9. návrh webhook integrácie,
-10. popis experimentov a vyhodnotenia.
+10. návrh integrácie s OpenWebUI,
+11. popis experimentov a vyhodnotenia.
 
 ## Najbližší praktický krok
 
-Najbližšie treba spraviť Docker nasadenie aktuálneho FastAPI prototypu.
+Najbližšie treba spraviť Gitea webhook endpoint.
 
 Poradie najbližších krokov:
 
-1. doplniť `README.md`,
+1. commitnúť aktuálne zmeny,
 2. pushnúť projekt na KEMT Git,
-3. vytvoriť `Dockerfile`,
+3. vytvoriť endpoint `POST /webhook/gitea`,
-4. vytvoriť `docker-compose.yml`,
+4. pridať overenie secretu alebo podpisu webhooku,
-5. spustiť API cez Docker,
+5. napojiť webhook na `/sync`,
-6. pripraviť základ pre webhook synchronizáciu.
+6. otestovať webhook lokálne alebo cez verejne dostupný tunel.