readme
This commit is contained in:
parent
c80694f543
commit
06a865ca6f
152
README.md
152
README.md
@ -1,90 +1,144 @@
|
|||||||
# README.md
|
# 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):**
|
**Backend (Python/Flask):**
|
||||||
- Flask REST API with CORS
|
- Flask REST API s CORS kompatibilitou
|
||||||
- ML: HuggingFace Transformers (RoBERTa, mDeBERTa-v3)
|
- Strojové učenie: HuggingFace Transformers (RoBERTa, mDeBERTa-v3)
|
||||||
- Translation: deep_translator (Google Translate)
|
- Preklad: deep_translator (Google Translate)
|
||||||
- Database: SQLite with caching layer
|
- Databáza: SQLite s cache vrstvou
|
||||||
- Search: SerpAPI for Google search results
|
- Vyhľadávanie: SerpAPI pre extrakciu výsledkov z Google
|
||||||
|
|
||||||
**Frontend (React/Vite):**
|
**Frontend (React/Vite):**
|
||||||
- React 19 with Vite 7
|
- React 19 s Vite 7
|
||||||
- React Router for navigation
|
- React Router pre navigáciu medzi stránkami
|
||||||
- Axios for HTTP requests
|
- Axios pre HTTP požiadavky
|
||||||
- CSS custom properties for theming
|
- Vlastné CSS pre vizuálne témy a dizajn
|
||||||
|
|
||||||
## Architecture
|
## Architektúra
|
||||||
|
|
||||||
```
|
```
|
||||||
factchecker/
|
factchecker/
|
||||||
├── backend/
|
├── backend/
|
||||||
│ ├── app.py # Flask API, NLI logic, model switching
|
│ ├── app.py # Flask API, NLI logika, prepínanie modelov
|
||||||
│ ├── database.py # SQLite cache, verified facts, stats
|
│ ├── database.py # SQLite cache, overené fakty, štatistiky
|
||||||
│ ├── .env # SERPAPI_API_KEY (required)
|
│ ├── .env # SERPAPI_API_KEY (povinné)
|
||||||
│ └── venv/ # Python virtual environment
|
│ └── venv/ # Virtuálne prostredie Pythonu
|
||||||
├── frontend/
|
├── frontend/
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── App.jsx # Router setup
|
│ │ ├── App.jsx # Nastavenie routera
|
||||||
│ │ ├── main.jsx # React entry point
|
│ │ ├── main.jsx # Vstupný bod pre React
|
||||||
│ │ ├── components/
|
│ │ ├── components/
|
||||||
│ │ │ └── Layout.jsx
|
│ │ │ └── Layout.jsx
|
||||||
│ │ └── pages/
|
│ │ └── pages/
|
||||||
│ │ ├── Home.jsx # Main fact-check UI
|
│ │ ├── Home.jsx # Hlavné UI pre fact-checking
|
||||||
│ │ └── About.jsx
|
│ │ └── About.jsx
|
||||||
│ └── package.json
|
│ └── package.json
|
||||||
└── factchecker.db # SQLite database (auto-created)
|
└── factchecker.db # SQLite databáza (vytvára sa automaticky)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Key Commands
|
## Základné príkazy
|
||||||
|
|
||||||
### Backend
|
### Backend
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
source venv/bin/activate # or: venv\Scripts\activate on Windows
|
source venv/bin/activate # alebo na Windows: venv\Scripts\activate
|
||||||
python app.py # Start Flask on port 5000
|
python app.py # Spustí Flask server na porte 5000
|
||||||
python clear_cache.py # Clear cache
|
python clear_cache.py # Vymaže vyrovnávaciu pamäť (cache)
|
||||||
python view_db.py # View database contents
|
python view_db.py # Zobrazí obsah databázy v termináli
|
||||||
```
|
```
|
||||||
|
|
||||||
### Frontend
|
### Frontend
|
||||||
```bash
|
```bash
|
||||||
cd frontend
|
cd frontend
|
||||||
npm install
|
npm install # Nainštaluje závislosti
|
||||||
npm run dev # Vite dev server
|
npm run dev # Spustí Vite vývojový server
|
||||||
npm run build # Production build
|
npm run build # Vytvorí produkčný build
|
||||||
npm run lint # ESLint
|
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)
|
- `POST /api/check` - Overí tvrdenie (body: claim, language, dateFrom, dateTo, selectedSource, model)
|
||||||
- `GET /api/history` - Get check history (query: limit)
|
- `GET /api/history` - Získa históriu overovaní (query limit: limit počtu)
|
||||||
- `GET /api/stats` - Get database statistics
|
- `GET /api/stats` - Získa štatistiky z databázy
|
||||||
- `POST /api/admin/add-fact` - Add manually verified fact (admin)
|
- `POST /api/admin/add-fact` - Pridá manuálne overený fakt (pre admina)
|
||||||
|
|
||||||
## Models
|
## Modely
|
||||||
|
|
||||||
Dva NLI modely dostupné s rôznymi компромismi:
|
Dva NLI modely dostupné s rôznymi kompromismi:
|
||||||
1. **RoBERTa** (`ynie/roberta-large-snli_mnli_fever_anli_R1_R2_R3-nli`) - Rýchly, vyžaduje preklad do angličtiny
|
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`) - Najlepší pre slovenčinu, multilingválny
|
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
|
- `fact_checks` - Cashované (uložené) výsledky vrátane hashu tvrdenia, verdiktu, NLI hlasov, dôkazov a zdrojov.
|
||||||
- `verified_facts` - Manually verified facts (admin-added)
|
- `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
|
- Súbor `.env` musí obsahovať kľúč pre SerpAPI - **nezahŕňajte/necommitujte ho do Gitu!**
|
||||||
- Models are loaded on-demand; switching triggers reload with cache clearing
|
- Modely sa načítavajú až na požiadanie. Prepnutie modelu v UI môže spustiť reset bežiaceho modelu a vymazanie RAM.
|
||||||
- Slovak claims are auto-translated for RoBERTa; mDeBERTa handles Slovak natively
|
- 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.
|
||||||
- Domain whitelist/blacklist filters search results for quality
|
- 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.
|
||||||
- Results are cached by claim hash to avoid redundant API calls
|
- 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