README.md

metadata

title: TruthCheck AI
emoji: 🛡️
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

TruthCheck: AI-Powered Fact Verification System

A state-of-the-art Automated Fact-Checking System that uses a multi-stage neural pipeline to verify text claims in real-time. It combines Web Scraping, Semantic Search, and Natural Language Inference (NLI) to determine the truthfulness of statements with high precision.

---

🌟 Key Features

🧠 Advanced AI Core

• Multi-Model Consensus: Aggregates judgments from RoBERTa-large-MNLI and DeBERTa-v3-large for robust accuracy.
• Semantic Filtering: Uses Sentence-Transformers to ensure only relevant evidence is analyzed.
• Credibility Weighting: Automatically assigns higher trust scores to .gov, .edu, and scientific domains.

💻 Modern "Cyber-Noir" Interface

• Futuristic UI: deep space blue theme with neon cyan/purple accents using Tailwind CSS.
• Real-Time Dashboard: Track system stats, truth rates, and scan history in the Command Center.
• Interactive Visuals: Animated confidence gauges, evidence streams, and live "scanning" effects.

⚙️ Enterprise-Ready

• REST API: Fully documented endpoint (/api/verify) for external integration.
• Persistence: Built-in SQLite database stores all verification history.
• Scalable Architecture: Modular design separating Extraction, Retrieval, and Classification layers.

---

🏛️ System Architecture (Top-to-Bottom)

The application follows a strictly layered pipeline architecture:

1. Input Layer:

   • User submits a claim via the Web UI or API.
   • The ClaimExtractor identifies factual statements using spaCy.

2. Retrieval Layer:

   • KeywordExtractor pulls search terms (Entities/Nouns).
   • EvidenceRetriever scrapes trusted sources (Wikipedia, Google, DuckDuckGo).
   • Evidence is filtered by domain credibility and semantic similarity.

3. Inference Layer (The "Brain"):

   • Filtered evidence is paired with the claim (Premise + Hypothesis).
   • NLI Models classify each pair as Entailment, Contradiction, or Neutral.
   • A weighted voting algorithm calculates the final Verdict and Confidence Score.

4. Presentation Layer:

   • Results are returned to the user with a color-coded verdict (Green/Red/Amber).
   • Data is archived in the history.db SQLite database.

---

🚀 Installation & Setup Guide

Follow these steps to deploy the system locally.

Prerequisites

• Python 3.10+ installed.
• Git installed.
• Internet connection (for downloading models).

Step 1: Clone the Repository

git clone https://github.com/CHRISDANIEL145/truth-check.git
cd truth-check

Step 2: Create Virtual Environment

Isolate dependencies to avoid conflicts.

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

This will install PyTorch, Transformers, spaCy, and Flask.

pip install -r requirements.txt

Step 4: Download Language Models

Pre-download the necessary NLI and spaCy models.

python -m spacy download en_core_web_sm

Note: The Transformer models (RoBERTa/DeBERTa) will automatically download on the first run (approx. 3GB).

Step 5: Run the Application

Start the Flask server.

python run.py

You should see output indicating the server is running on http://127.0.0.1:5000.

---

📖 Usage Guide

1. Using the Analyzer

• Navigate to http://127.0.0.1:5000.
• Type a factual claim (e.g., "The Great Wall of China is visible from space").
• Click INIT_SCAN.
• View the Verdict, Confidence Score, and supporting/contradicting Evidence.

2. The Dashboard

• Click Dashboard in the top navigation.
• View global statistics (Truth Rate, Total Scans).
• Review your complete verification history.

3. API Integration

Invoke the verification engine programmatically:

Endpoint: POST /api/verify

Request:

{
  "claim": "Water boils at 100 degrees Celsius."
}

Response:

{
  "label": "True",
  "confidence": 0.99,
  "evidence": "..."
}

---

📂 Project Structure

TruthCheck/
├── app.py                 # Main Flask application & routes
├── run.py                 # Entry point
├── history.db             # SQLite database (auto-created)
├── models/                # AI Core
│   ├── claim_extractor.py # Identifies claims
│   ├── evidence_retriever.py # Web scraping logic
│   ├── keyword_extractor.py  # NLP keyword extraction
│   └── nli_classifier.py     # RoBERTa/DeBERTa inference pipeline
├── static/                # Frontend Assets
│   ├── css/style.css      # Custom animations & styles
│   └── js/main.js         # Frontend logic
├── templates/             # HTML Views
│   ├── index.html         # Analyzer UI
│   ├── dashboard.html     # Stats & History
│   ├── how_it_works.html  # Architecture Docs
│   └── api.html           # API Docs
└── utils/                 # Helpers
    └── config.py          # App configuration

---

🤝 Contributing

Contributions are welcome! Please fork the repository and submit a Pull Request.

📄 License

This project is licensed under the MIT License.