TruthCheck Docs

Prerequisites

• Node.js 20+
• DeepSeek API key — platform.deepseek.com
• Brave Search API key (optional — required on Vercel/cloud where DuckDuckGo is blocked)

Setup

git clone <repo-url>
cd truth-checker
npm install

# Copy and fill in environment variables
cp .env.example .env.local
# Required: DEEPSEEK_API_KEY
# Optional: BRAVE_SEARCH_API_KEY
# Optional: FACTCHECK_* pipeline budgets (see docs/DEVELOPMENT.md)

npm run dev

App available at http://localhost:3000

Common Commands

npm run dev          # Start dev server
npm run build        # Production build
npm run start        # Start production server
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit
npm test             # Run all tests (Vitest)
npm run test:watch   # Watch mode

Adding a Translation Key

1. Add the English string to dict.en in lib/i18n.ts
2. Add the Spanish string to dict.es with the same key
3. Use it in any client component: const { t } = useLanguage(); t('my_key')

The test suite automatically enforces that dict.en and dict.es have identical keys.

Styling

Tailwind CSS v4. Custom utility classes in app/globals.css:

• .glass — glassmorphism with backdrop blur
• .gradient-text — indigo-to-cyan gradient text
• .hero-pattern — radial dot grid background

Docker

docker compose up -d --build   # Build and start
docker compose down             # Stop

POST/api/extract

Extracts atomic factual claims from a body of text using deepseek-chat. Returns at most 10 claims.

// Request
{ "text": "...", "language": "en" }

// Response — originalTextQuote is always verbatim from the input, never translated
{ "claims": [{ "id": "claim-0", "text": "...", "originalTextQuote": "...",
               "quoteStart": 0, "quoteEnd": 45 }] }

POST/api/verify

Verifies a single claim via web search + DeepSeek Reasoner. Pass "language": "es" to receive reasoning in Spanish.

// Request
{ "claim": { "id": "claim-0", "text": "...", "originalTextQuote": "..." }, "language": "en" }

// Response — read "verdict", not "legacyScore"
{ "result": { "claimId": "claim-0", "score": 0, "reasoning": "...",
              "sources": [...], "citations": [], "pipelineStatus": "ok",
              "phase2": {
                "verdict": "contradicted",
                "confidence": { "level": "high", "score": 0.91, "rationale": "..." },
                "evidenceQuality": { "level": "high", "rationale": "...", "limitations": [] },
                "summary": "...", "caveats": [],
                "supportingEvidence": [], "contradictingEvidence": [...],
                "legacyScore": 0 } } }

// Response when the search providers are down — an error, not a verdict
{ "result": { "claimId": "claim-0", "score": -1, "reasoning": "...",
              "sources": [], "citations": [],
              "pipelineStatus": "search_unavailable",
              "warnings": [{ "code": "search_provider_failed" }] } }

Pipeline Status

Verdicts

The primary result. A verdict describes what the evidence showed — it is never a statement that the claim is true or false in the abstract.

Confidence and evidence quality

Confidence (high / medium / low) is how firmly the verdict follows from the evidence. Evidence quality (high / medium / low / insufficient) is how good that evidence was — its independence, primacy, and directness. They are separate on purpose: strong agreement among weak sources is not the same as a firm conclusion. A directional verdict can never be reported as high confidence on low or insufficient evidence; that cap is enforced by the server, not by the model.

Caveats

A verdict can carry caveats naming what qualifies it — missing context, time sensitivity, geographic or population scope, ambiguous definitions, correlation reported as causation, units and quantities, conflicting sources, or thin primary evidence. Caveats marked materialare ones that shaped the verdict itself. Caveat detection is the weakest part of this pipeline today and misses a meaningful share of what it should catch — read the absence of a caveat as "not found", not as "not applicable".

Legacy Score Interpretation

The 0–5 score predates verdicts and is now derived from them for backward compatibility. It is lossy — insufficient_evidence and not_checkable both collapse to 1. New clients should read verdict.