fact_checker/README.md

README.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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.

Tech 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

Frontend (React/Vite):

• React 19 with Vite 7
• React Router for navigation
• Axios for HTTP requests
• CSS custom properties for theming

Architecture

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
├── frontend/
│   ├── src/
│   │   ├── App.jsx     # Router setup
│   │   ├── main.jsx    # React entry point
│   │   ├── components/
│   │   │   └── Layout.jsx
│   │   └── pages/
│   │       ├── Home.jsx    # Main fact-check UI
│   │       └── About.jsx
│   └── package.json
└── factchecker.db      # SQLite database (auto-created)

Key Commands

Backend

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

Frontend

cd frontend
npm install
npm run dev               # Vite dev server
npm run build             # Production build
npm run lint              # ESLint

API Endpoints

• 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)

Models

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

Database Schema

• fact_checks - Cached results with claim hash, verdict, NLI votes, evidence, sources
• verified_facts - Manually verified facts (admin-added)

Important Notes

• 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