From 173e8191918dfbf11698de1f9957c8f84c66efef Mon Sep 17 00:00:00 2001 From: Tetiana Mohorian Date: Wed, 4 Jun 2025 10:44:32 +0000 Subject: [PATCH] Aktualizovat telegram_bot/README.md --- telegram_bot/README.md | 113 ++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/telegram_bot/README.md b/telegram_bot/README.md index 9a5a63d..0d62647 100644 --- a/telegram_bot/README.md +++ b/telegram_bot/README.md @@ -1,123 +1,122 @@ +# Hate Speech Bot – Documentation -# Hate Speech Bot – Dokumentácia +## 🧠 Application Overview -## 🧠 Opis aplikácie +The Hate Speech Bot is a complete system for the automated detection of hate speech within **Telegram**. It functions as a monitoring and analysis tool that enables: -Hate Speech Bot je kompletný systém na automatickú detekciu nenávistnej reči v prostredí **Telegramu**. Aplikácia slúži ako monitorovací a analytický nástroj, ktorý umožňuje: +- Automatic **interception and analysis of user messages** in group chats +- When hate speech is detected, it records information about the **user and the message into a database** +- Displays violators through a **real-time web interface** -- Automaticky **zachytiť a analyzovať správy** používateľov v skupinových chatoch. -- V prípade detekcie nenávistného prejavu zaznamená informáciu o **používateľovi a správe do databázy**. -- Vizualizuje porušovateľov cez **webové rozhranie** v reálnom čase. - -### Komponenty systému: -1. **Telegram Bot**: Interceptuje správy v skupine a pomocou trénovaného LLM modelu klasifikuje, či ide o nenávistnú reč. -2. **MySQL databáza**: Ukladá údaje o používateľoch, správach a čase incidentu. -3. **Webová aplikácia (Flask)**: Zobrazuje tabuľku s porušeniami, automaticky aktualizovanú každých 5 sekúnd. +### System Components: +1. **Telegram Bot**: Intercepts messages and uses a fine-tuned LLM model to classify whether the message contains hate speech. +2. **MySQL Database**: Stores user information, messages, and incident timestamps. +3. **Web Application (Flask)**: Displays a real-time table of violations, updated every 5 seconds. --- -## 🧱 Zoznam použitých Docker kontajnerov +## 🧱 List of Used Docker Containers -| Kontajner | Popis | -|--------------------------------------|-------| -| `tetianamohorian/hate-speech-bot` | Obsahuje Telegram bota, klasifikačný model (napr. fine-tuned BERT), a Flask frontend. | -| `mysql:8` | Relačný databázový systém pre ukladanie záznamov o porušovateľoch. | +| Container | Description | +|-------------------------------------|-------------| +| `tetianamohorian/hate-speech-bot` | Contains the Telegram bot, classification model (e.g. fine-tuned BERT), and Flask frontend | +| `mysql:8` | Relational database for storing violator records | --- -## ☸️ Zoznam Kubernetes objektov +## ☸️ List of Kubernetes Objects -| Objekt | Popis | -|----------------------------|-------| -| `Namespace: botspace` | Izolovaný priestor pre všetky objekty súvisiace s aplikáciou. | -| `Deployment: bot-deployment` | Nasadzuje kontajner s botom. | -| `Deployment: flask-web` | Nasadzuje Flask webserver. | -| `StatefulSet: mysql` | Zabezpečuje perzistentný a konzistentný chod MySQL databázy. | -| `PersistentVolume` | Uchováva fyzické dáta databázy mimo podu. | -| `PersistentVolumeClaim` | Žiadosť o diskový priestor pre databázu. | -| `Service: mysql` | Vnútorná služba pre prístup k databáze. | -| `Service: flask-service` | Port-forward pre sprístupnenie webu. | -| `ConfigMap: init-sql` | Obsahuje SQL skripty na prvotnú inicializáciu schémy. | -| `Secret: bot-secret` | Bezpečné uloženie citlivých údajov ako je Telegram token. | +| Object | Description | +|---------------------------|-------------| +| `Namespace: botspace` | Isolated space for all app-related objects | +| `Deployment: bot-deployment` | Deploys the container with the bot | +| `Deployment: flask-web` | Deploys the Flask web server | +| `StatefulSet: mysql` | Ensures persistent and consistent MySQL operation | +| `PersistentVolume` | Stores database data outside the pod | +| `PersistentVolumeClaim` | Requests disk space for the database | +| `Service: mysql` | Internal service for accessing the database | +| `Service: flask-service` | Port-forward service for accessing the web | +| `ConfigMap: init-sql` | Contains initial SQL schema scripts | +| `Secret: bot-secret` | Secure storage of sensitive data like the Telegram token | --- -## 🌐 Virtuálne siete a úložiská +## 🌐 Virtual Networks and Storage -- Všetky pody komunikujú cez internú sieť v `botspace`, čím sa znižuje riziko únikov údajov. -- `PersistentVolume` pripojený k MySQL zaručuje zachovanie dát aj po reštarte podu. +- All pods communicate over an internal network in `botspace`, minimizing data leakage risks +- `PersistentVolume` attached to MySQL ensures data preservation even after pod restarts --- -## ⚙️ Konfigurácia kontajnerov +## ⚙️ Container Configuration -- **Flask Web**: Beží na porte `5000`, ktorý je dostupný cez `flask-service`. Obnovuje sa každých 5 sekúnd pomocou JavaScriptu (AJAX `fetch`). -- **Telegram Bot**: Spustený v samostatnom threade, číta správy, klasifikuje ich pomocou PyTorch modelu (alebo HuggingFace Transformers), a zapisuje výsledok do databázy. -- **MySQL**: Inicializovaná pomocou `initContainer`, ktorý spustí skript uložený v `ConfigMap`. +- **Flask Web**: Runs on port `5000`, accessible via `flask-service`. Automatically updates via JavaScript (AJAX `fetch`) every 5 seconds +- **Telegram Bot**: Runs in a separate thread, classifies messages using a PyTorch model or HuggingFace Transformers, and logs results into the database +- **MySQL**: Initialized with an `initContainer` that runs a script from the `ConfigMap` --- -## 🚀 Návod na použitie +## 🚀 Usage Guide -### 1. Príprava aplikácie: +### 1. Prepare the Application: ```bash ./prepare-app.sh ``` -- Zostaví Docker image s aplikáciou. -- Pushne ho do Docker Hub repozitára. +- Builds the Docker image +- Pushes it to Docker Hub --- -### 2. Spustenie aplikácie: +### 2. Start the Application: ```bash ./start-app.sh ``` -- Vytvorí Kubernetes objekty. -- Spustí port-forwarding pre Flask web na `localhost:8888`. +- Creates Kubernetes objects +- Starts port-forwarding for Flask web on `localhost:8888` --- -### 3. Pozastavenie (port-forward): +### 3. Stop Port-Forwarding: ```bash pkill -f "kubectl port-forward" ``` -- Zastaví dočasný prístup cez port-forward. +- Terminates temporary access via port-forward --- -### 4. Odstránenie aplikácie: +### 4. Remove the Application: ```bash ./stop-app.sh ``` -- Zmaže celý `botspace`, vrátane databázy a všetkých služieb. +- Deletes the entire `botspace`, including database and services --- -## 🌍 Prístup k webovej aplikácii +## 🌍 Accessing the Web Interface -Po úspešnom spustení aplikácie otvorte webový prehliadač: +After launching the app, open a browser: ``` http://localhost:8888 ``` -- Zobrazí sa tabuľka s informáciami o porušovateľoch. -- Dáta sa aktualizujú automaticky každých 5 sekúnd bez potreby obnoviť stránku. +- A table of violators will be displayed +- Data updates automatically every 5 seconds --- -## 📦 Použité technológie +## 📦 Technologies Used -- **Python, Flask, PyTorch / Transformers** – analýza a klasifikácia textov -- **Docker, Docker Hub** – kontajnerizácia -- **Kubernetes** – orchestrácia, škálovanie a sieťová izolácia -- **MySQL** – relačné databázové úložisko -- **JavaScript (AJAX)** – aktualizácia frontendu v reálnom čase +- **Python, Flask, PyTorch / Transformers** – text analysis and classification +- **Docker, Docker Hub** – containerization +- **Kubernetes** – orchestration, scaling, and network isolation +- **MySQL** – relational data storage +- **JavaScript (AJAX)** – real-time frontend updates \ No newline at end of file