diff --git a/README.md b/README.md index 9456eb5..843c706 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,144 @@ # README.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Tento súbor slúži ako dokumentácia. -## Project Overview +## Prehľad projektu -AI Fact Checker - a full-stack web application that verifies claims using Natural Language Inference (NLI) models. The system searches the web via SerpAPI, analyzes snippets against claims, and returns verdicts (True/False/Ambiguous) with evidence. +AI Fact Checker - full-stack webová aplikácia, ktorá overuje tvrdenia používateľov pomocou modelov NLI (Natural Language Inference). Systém prehľadáva web prostredníctvom služby SerpAPI, analyzuje úryvky z vyhľadávania z dôveryhodných zdrojov v porovnaní s tvrdeniami a vracia verdikty (Pravda/Nepravda/Nejednoznačné) spolu s nájdenými dôkazmi. -## Tech Stack +## Technologický Stack **Backend (Python/Flask):** -- Flask REST API with CORS -- ML: HuggingFace Transformers (RoBERTa, mDeBERTa-v3) -- Translation: deep_translator (Google Translate) -- Database: SQLite with caching layer -- Search: SerpAPI for Google search results +- Flask REST API s CORS kompatibilitou +- Strojové učenie: HuggingFace Transformers (RoBERTa, mDeBERTa-v3) +- Preklad: deep_translator (Google Translate) +- Databáza: SQLite s cache vrstvou +- Vyhľadávanie: SerpAPI pre extrakciu výsledkov z Google **Frontend (React/Vite):** -- React 19 with Vite 7 -- React Router for navigation -- Axios for HTTP requests -- CSS custom properties for theming +- React 19 s Vite 7 +- React Router pre navigáciu medzi stránkami +- Axios pre HTTP požiadavky +- Vlastné CSS pre vizuálne témy a dizajn -## Architecture +## Architektúra ``` factchecker/ ├── backend/ -│ ├── app.py # Flask API, NLI logic, model switching -│ ├── database.py # SQLite cache, verified facts, stats -│ ├── .env # SERPAPI_API_KEY (required) -│ └── venv/ # Python virtual environment +│ ├── app.py # Flask API, NLI logika, prepínanie modelov +│ ├── database.py # SQLite cache, overené fakty, štatistiky +│ ├── .env # SERPAPI_API_KEY (povinné) +│ └── venv/ # Virtuálne prostredie Pythonu ├── frontend/ │ ├── src/ -│ │ ├── App.jsx # Router setup -│ │ ├── main.jsx # React entry point +│ │ ├── App.jsx # Nastavenie routera +│ │ ├── main.jsx # Vstupný bod pre React │ │ ├── components/ │ │ │ └── Layout.jsx │ │ └── pages/ -│ │ ├── Home.jsx # Main fact-check UI +│ │ ├── Home.jsx # Hlavné UI pre fact-checking │ │ └── About.jsx │ └── package.json -└── factchecker.db # SQLite database (auto-created) +└── factchecker.db # SQLite databáza (vytvára sa automaticky) ``` -## Key Commands +## Základné príkazy ### Backend ```bash cd backend -source venv/bin/activate # or: venv\Scripts\activate on Windows -python app.py # Start Flask on port 5000 -python clear_cache.py # Clear cache -python view_db.py # View database contents +source venv/bin/activate # alebo na Windows: venv\Scripts\activate +python app.py # Spustí Flask server na porte 5000 +python clear_cache.py # Vymaže vyrovnávaciu pamäť (cache) +python view_db.py # Zobrazí obsah databázy v termináli ``` ### Frontend ```bash cd frontend -npm install -npm run dev # Vite dev server -npm run build # Production build -npm run lint # ESLint +npm install # Nainštaluje závislosti +npm run dev # Spustí Vite vývojový server +npm run build # Vytvorí produkčný build +npm run lint # Spustí kontrolu kódu (ESLint) ``` -## API Endpoints +## API Endpointy -- `POST /api/check` - Verify a claim (body: claim, language, dateFrom, dateTo, selectedSource, model) -- `GET /api/history` - Get check history (query: limit) -- `GET /api/stats` - Get database statistics -- `POST /api/admin/add-fact` - Add manually verified fact (admin) +- `POST /api/check` - Overí tvrdenie (body: claim, language, dateFrom, dateTo, selectedSource, model) +- `GET /api/history` - Získa históriu overovaní (query limit: limit počtu) +- `GET /api/stats` - Získa štatistiky z databázy +- `POST /api/admin/add-fact` - Pridá manuálne overený fakt (pre admina) -## Models +## Modely -Dva NLI modely dostupné s rôznymi компромismi: -1. **RoBERTa** (`ynie/roberta-large-snli_mnli_fever_anli_R1_R2_R3-nli`) - Rýchly, vyžaduje preklad do angličtiny -2. **mDeBERTa** (`MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7`) - Najlepší pre slovenčinu, multilingválny +Dva NLI modely dostupné s rôznymi kompromismi: +1. **RoBERTa** (`ynie/roberta-large-snli_mnli_fever_anli_R1_R2_R3-nli`) - Je rýchly, ale vyžaduje preklad vstupu do angličtiny. +2. **mDeBERTa** (`MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7`) - Je najlepší a najpresnejší pre slovenčinu a natívne podporuje viaceré jazyky. -## Database Schema +## Schéma Databázy -- `fact_checks` - Cached results with claim hash, verdict, NLI votes, evidence, sources -- `verified_facts` - Manually verified facts (admin-added) +- `fact_checks` - Cashované (uložené) výsledky vrátane hashu tvrdenia, verdiktu, NLI hlasov, dôkazov a zdrojov. +- `verified_facts` - Manuálne a napevno overené fakty (pridávané adminom). -## Important Notes +## Dôležité poznámky -- The `.env` file contains the SerpAPI key - do not commit -- Models are loaded on-demand; switching triggers reload with cache clearing -- Slovak claims are auto-translated for RoBERTa; mDeBERTa handles Slovak natively -- Domain whitelist/blacklist filters search results for quality -- Results are cached by claim hash to avoid redundant API calls +- Súbor `.env` musí obsahovať kľúč pre SerpAPI - **nezahŕňajte/necommitujte ho do Gitu!** +- Modely sa načítavajú až na požiadanie. Prepnutie modelu v UI môže spustiť reset bežiaceho modelu a vymazanie RAM. +- Slovenské tvrdenia sú pre model RoBERTa pred spustením NLI vždy automaticky prekladané. Model mDeBERTa zvláda slovenčinu natívne, bez potreby prekladu do angličtiny. +- Výsledky vyhľadávania prechádzajú filtrom domén (whitelist vs. blacklist), primárne so zameraním na slovenské aj celosvetové spravodajské portály a inštitúcie. +- Výsledky sa vždy ukladajú do cache, aby sa predišlo opakovaným a drahým volaniam vyhľadávacieho API pre rovnaké dotazy. + +## Návod na inštaláciu a spustenie + +Ak si projekt práve vyklonoval z repozitára a chceš ho rozbehať lokálne, postupuj podľa týchto krokov: + +### 1. Klonovanie repozitára a prerekvizity +Najprv si naklonuj projekt a presuň sa do hlavnej zložky: +```bash +git clone # napr. git clone git@github.com:Meno/factchecker.git +cd factchecker +``` +*Poznámka: Pre beh projektu potrebuješ mať nainštalovaný **Python** (pre backend) a **Node.js + npm** (pre frontend).* + +### 2. Príprava a spustenie backendu (Umelá inteligencia a API) +Otvor si prvý terminál a prekopíruj tieto príkazy: + +```bash +cd backend + +# Vytvorenie a aktivácia virtuálneho prostredia (pre Windows) +python -m venv venv +venv\Scripts\activate +# Pre Mac/Linux zvoľ: source venv/bin/activate + +# Inštalácia všetkých Python potrebných knižníc +pip install flask flask-cors transformers torch requests python-dotenv deep-translator +``` + +Ďalej musíš **vytvoriť `.env` súbor** v priečinku `backend/`. +Vytvor ho ručne a nastav si v ňom kľúč pre vyhľadávanie cez Serp API (ak ho nemáš, vytvor si zdarma účet na [serpapi.com](https://serpapi.com/)): +```env +SERPAPI_API_KEY=tvoj_tajny_api_kluc +``` + +Nakoniec backend spusti pomocou: +```bash +python app.py +``` +*(Server by mal teraz nabehnúť na adrese `http://127.0.0.1:5000`. Tento terminál nechaj bežať a nevypínaj.)* + +### 3. Príprava a spustenie frontendu (Rozhranie aplikácie) +Otvor si druhý, úplne **nový preklikávací terminál / okno na pozadí**, uisti sa že si v koreňovom priečinku `factchecker` a presuň sa do frontendu: + +```bash +cd frontend + +# Inštalácia Node.js závislostí z package.json +npm install + +# Spustenie Vite vývojového servera +npm run dev +``` + +Ak všetko prebehne úspešne, terminál ti vyhodí odkaz (zvyčajne to býva `http://localhost:5173/` alebo `http://localhost:5174/`). Otvor si ho v prehliadači a hotovo – môžeš začať s Fact-Checkingom!