readme
This commit is contained in:
parent
c80694f543
commit
06a865ca6f
152
README.md
152
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 <url-tvojho-repozitara> # 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!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user