Aktualizovat sk1/README.md

sk1/README.md

@@ -34,4 +34,171 @@ CREATE TABLE IF NOT EXISTS history (
     text TEXT NOT NULL,
     prediction TEXT NOT NULL,
     timestamp TIMESTAMP NOT NULL
-);```
+);
+```
+Popis polí:
+
+`id`: automatický primárny kľúč (číselný identifikátor)
+`text`: vstupný text, ktorý užívateľ zadal
+`prediction`: výstup modelu (napr. "Neutrálny text")
+`timestamp`: dátum a čas, kedy bol text spracovaný
+
+---
+
+## 3. Štruktúra projektu
+
+Projekt má nasledovnú štruktúru:
+
+```
+skuska/
+├── Dockerfile               # multistage Dockerfile (frontend + backend)
+├── prepare-app-cloud.sh           # skript na nasadenie aplikácie do GCP
+├── remove-app-cloud.sh            # skript na odstránenie služby
+├── history.json             # synchronizovaný záznam histórie (čítaný frontend)
+├── frontend/                # React frontend projekt (vite)
+│   └── ...                  # komponenty, assets, App.jsx atď.
+├── backend/                 # Flask backend
+│   ├── app.py               # hlavný backend súbor (Flask API)
+│   └── requirements.txt     # python balíčky (model sa sťahuje dynamicky z Hugging Face)
+```
+
+---
+
+## 4. Opis odovzdaných súborov a konfigurácie:
+
+### `backend/app.py`: hlavný backend aplikácie vo Flasku. 
+Obsahuje:
+
+- endpoint `/api/predict` na AI predikciu
+
+- `/api/history`, `/api/history/db` a `/api/history/reset` - slúžia na prácu s históriou. /api/history číta zo súboru history.json, ktorý je automaticky synchronizovaný s databázou. /api/history/db číta priamo z PostgreSQL databázy a zobrazí zoznam záznamov zoradených podľa času. /api/history/reset vymaže všetky záznamy z tabuľky history v databáze a zároveň prepíše history.json na prázdny zoznam.
+
+- prepojenie na PostgreSQL (cez psycopg2 a DATABASE_URL)
+
+- uloženie a synchronizáciu histórie
+
+- automatické stiahnutie modelu z Hugging Face pri štarte aplikácie
+
+### `frontend/`: React projekt vytvorený cez Vite. 
+- Obsahuje komponenty pre UI, API volania, zobrazovanie výsledkov a histórie.
+
+### `backend/`: obsahuje `app.py`, `requirements.txt`
+
+### Dockerfile: kombinácia frontend + backend do jedineho obrazu
+
+Výrez Dockerfile:
+
+```dockerfile
+FROM node:18 AS frontend
+WORKDIR /frontend
+COPY frontend/ .
+RUN npm install && npm run build
+
+FROM python:3.10-slim
+WORKDIR /app
+COPY backend/ .
+RUN apt-get update && apt-get install -y gcc libpq-dev && pip install -r requirements.txt
+COPY --from=frontend /frontend/dist /app/static
+CMD ["python", "app.py"]
+```
+### `prepare-app-cloud.sh`: 
+Bash skript, ktorý:
+- definuje všetky dôležité premenne (názov projektu, región, názov obrazu a databázy)
+- zostaví Docker image pomocou gcloud builds submit
+- nasadí image do Google Cloud Run cez gcloud run deploy
+- nastaví environmentálnu premennú DATABASE_URL
+- prepojí službu so zvolenou databázou cez --add-cloudsql-instances
+- vyžaduje spustený gcloud CLI a prihláseného používateľa
+
+### `remove-app-cloud.sh`: 
+Bash skript, ktorý:
+- pomocou gcloud run services delete zmaže existujúcu službu z Google Cloud Run
+- využíva parameter --quiet na potlačenie výzvy na potvrdenie
+- vyžaduje rovnaké prostredie ako skript prepare-app.sh
+
+### `history.json`: 
+- vygenerovaný automaticky zo stavu databázy (synchronizuje sa pri každom uložení nového záznamu pomocou funkcie `sync_history_file()`)
+
+### Pripojenie k databáze:
+
+Premenná:
+
+```
+DATABASE_URL=postgresql://user:password@/mydb?host=/cloudsql/hatespeechsite:europe-central2:hate-db
+```
+
+---
+## 5. Návod na použitie aplikácie v prehliadači:
+
+1. Otvorte v prehliadači URL:
+```
+https://hate-detektor-19732600168.europe-central2.run.app/
+```
+2. Zadajte text do formulára
+3. Kliknite na "Skontrolovať"
+4. Zobrazí sa výsledok klasifikácie
+5. Pod formulárom sa nachádza sekcia histórie
+
+Pozamka: môžete resetovat' historiu priamo cez terminál príkazom:
+```
+curl -X POST https://hate-detektor-19732600168.europe-central2.run.app/api/history/reset | jq
+```
+
+---
+## 6. Podmienky pre spustenie skriptov:
+
+### `prepare-app-cloud.sh`:
+
+vyžaduje:
+
+- GCP projekt s povolenými službami: Artifact Registry, Cloud Build, Cloud Run, Cloud SQL
+- `gcloud` CLI s aktívnym prihlásením a nastaveným projektom
+
+vykonáva:
+
+- build Docker image
+- push do Artifact Registry
+- deploy do Cloud Run + pripojenie k Cloud SQL + nastavenie DATABASE_URL
+- používa premenné prostredia pre názvy služby a databázy
+- skript je opakovateľný a nevyžaduje manuálnu interakciu
+
+### `remove-app-cloud.sh`:
+
+- odstráni službu z Cloud Run
+- spustenie je okamžité bez potreby interakcie
+- tichý režim (bez potvrdenia) pomocou parametra --quiet
+
+
+---
+
+## 7. Externé zdroje:
+
+Trénovaný model:
+
+- Použitý model: `slovak-t5-small`, finetunovaný osobne 
+- Model bol trénovaný na slovenskom datasete pozostávajúcom z anotovaných viet so zameraním na identifikáciu nenávistného prejavu
+- Tréning prebehol s využitím metódy PEFT (Parameter-Efficient Fine-Tuning) konkrétne cez technológiu LoRA (Low-Rank Adaptation), čo umožnilo efektívne doladiť model s minimálnym počtom trénovateľných parametrov
+- Model dosiahol presnosť 71 % pri testovaní na slovenskom dátovom korpuse
+
+### Model: `tetianamohorian/hate_speech_model` z HuggingFace (transformers model BERT)
+
+- Knižnice a frameworky:
+
+  - `transformers`, `torch` pre modelovanie
+  - `Flask`, `psycopg2`, `pytz` pre backend 
+  - `React`, `Vite`, `fetch` pre frontend
+
+---
+## 8. Zhrnutie a vykonané kroky:
+
+✅ Vytvorený frontend v Reacte s použitím Vite
+✅ Vytvorený backend vo Flasku s REST API
+✅ Nasadený AI model trénovaný na slovenskom datasete (slovak-t5-small, LoRA, 71 % presnosť)
+✅ Prepojenie aplikácie s databázou Cloud SQL (PostgreSQL)
+✅ Vytvorená databázová tabuľka history s políčkami: id, text, prediction, timestamp
+✅ Implementovaná synchronizácia databázy s `history.json`
+✅ Nasadenie aplikácie pomocou Dockeru a Google Cloud Run
+✅ Vytvorené shellové skripty na deploy (prepare-app-cloud.sh) a odstránenie (remove-app-cloud.sh)
+✅ Zabezpečený verejný prístup cez HTTPS
+✅ Otestované API: `/api/predict`, `/api/history`, `/api/history/reset`, `/api/history/db`
+