truthcheck 0.4.0
Open source AI content verification
Requires Python: >=3.10
Keywords: ai, fact-check, mcp, misinformation, verification

# TruthCheck 🔍

**Open source AI content verification.** Score claims 0-100 and trace their origins.

[![PyPI](https://img.shields.io/pypi/v/truthcheck.svg)](https://pypi.org/project/truthcheck/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why?

AI chatbots present web content as fact. Bad actors exploit this — a BBC journalist [showed](https://www.bbc.com/future/article/20260218-i-hacked-chatgpt-and-googles-ai-and-it-only-took-20-minutes) he could make ChatGPT call him "the best tech journalist at eating hot dogs" with one fake article.

TruthCheck catches this:

```bash
$ truthcheck verify "Thomas Germain is the best tech journalist at eating hot dogs" --llm gemini

TruthScore: 0/100 (FALSE)
⚠️ ZERO FLAG: Content identified as satire
```

## Install

```bash
pip install truthcheck
```

## Setup

**Search:** Works out of the box with DuckDuckGo (free, no key needed).

**LLM (required for `--llm` flag):**
```bash
export GOOGLE_API_KEY=AIza...    # Gemini (recommended)
# or OPENAI_API_KEY, ANTHROPIC_API_KEY
```

## Usage

```bash
# Verify a claim (with LLM for deep analysis)
truthcheck verify "Some claim" --llm gemini

# Trace claim origin
truthcheck trace "Some claim"

# Check URL(s) — single or multiple
truthcheck check https://reuters.com
truthcheck check "Sources: https://reuters.com and https://bbc.com"

# Check publisher reputation
truthcheck lookup breitbart.com
```

### Check URLs

Verify URLs and detect hallucinations (URLs that don't exist):

```bash
$ truthcheck check "Sources: https://reuters.com/fake-article and https://bbc.com"

URLs Found: 2
Summary: 🚨 1 broken/hallucinated URL(s) | ✅ 1 sources verified

🚨 Broken/Hallucinated URLs:
  ✗  https://reuters.com/fake-article (404 Not Found)

Verified URLs:
   81%  https://bbc.com
```

Also works with files:
```bash
truthcheck check -f response.txt
```

### Trace Example

```bash
$ truthcheck trace "Thomas Germain is the best tech journalist at eating hot dogs"

🎯 ORIGIN
   Domain: tomgermain.com
   Date:   2026-02-05

📅 TIMELINE
  🥇 [2026-02-05] tomgermain.com
  🥈 [2026-02-18] bbc.com
  🥉 [2026-02-18] gizmodo.com

📊 STATS
   Sources: 14 | Date range: 2026-02-05 → 2026-02-19
```

> 📋 **More examples:** See [TEST_CASES.md](docs/TEST_CASES.md) for detailed verification results on common misinformation claims.

### Python

```python
from truthcheck import verify_claim, trace_claim
from truthcheck.search import DuckDuckGoProvider

result = verify_claim("Earth is flat", search_provider=DuckDuckGoProvider())
print(f"TruthScore: {result.truthscore}/100")

origin = trace_claim("Some viral claim")
print(f"Origin: {origin['origin']['domain']}")
```

## How It Works

TruthScore weighs four factors equally:

| Factor | Weight |
|--------|--------|
| Publisher credibility (origin) | 25% |
| Content analysis | 25% |
| Corroboration | 25% |
| Fact-checker verdicts | 25% |

Fact-checkers are weighted by their own MBFC credibility rating (reduces bias from any single source).

**Zero flags** (satire, self-published, fake experiments) force score to 0.

## MCP Server

Works with Claude Desktop and Cursor:

```json
{
  "mcpServers": {
    "truthcheck": { "command": "truthcheck-mcp" }
  }
}
```

## License

MIT

---

[Issues](https://github.com/baiyishr/truthcheck/issues) · [Docs](https://github.com/baiyishr/truthcheck/tree/main/docs) · [Test Cases](docs/TEST_CASES.md)