Tru8 Evidence Research

Tru8 — AI-Powered Evidence Research Platform

Tru8 organises evidence so you can decide what matters. Submit a claim or URL, and Tru8 retrieves evidence from the open web and specialist APIs, classifies it by tier (primary / reporting / commentary) and type (data / official / news / analysis / opinion / academic), decomposes claims into elements, maps evidence to those elements, and presents the full landscape — structured, not summarised.

Mission: "We organise; you decide."

Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• Node.js 20+

1. Start Infrastructure

docker-compose up -d    # PostgreSQL 16, Redis 7, Qdrant

2. Backend

cd backend
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Edit with your API keys
alembic upgrade head
uvicorn app.main:app --reload    # http://localhost:8000

3. Frontend

cd web
npm install
npm run dev    # http://localhost:3000

Project Structure

tru8/
├── backend/              # FastAPI backend + evidence pipeline
│   ├── app/
│   │   ├── api/v1/       # REST endpoints (checks, agent, verify, payments)
│   │   ├── core/         # Config, auth, pricing, manifest signing
│   │   ├── models/       # SQLModel schemas (Check, Claim, Evidence, ClaimConsensus)
│   │   ├── pipeline/     # Two-phase evidence pipeline
│   │   ├── services/     # API adapters, search, payments, consensus
│   │   └── utils/        # Classifiers, deduplication, query planning
│   ├── alembic/          # Database migrations
│   ├── tru8_mcp/         # MCP server package for AI agents
│   └── tests/            # 990 unit + integration tests
├── web/                  # Next.js 14 frontend
│   ├── app/              # Pages (dashboard, developers, public reports)
│   ├── components/       # Evidence views, claim map, marketing
│   └── lib/              # API client, tiers, diagnostics
├── shared/               # Shared TypeScript types
├── docker-compose.yml    # PostgreSQL, Redis, Qdrant, MinIO (optional)
└── .claude/CLAUDE.md     # Full engineering context

Pipeline

Two-phase pipeline with user claim selection gate (article mode):

Phase 1:  Ingest → Extract claims → Classify article → Rank claims
          [PAUSE — user selects claims]

Phase 2:  Fact-check lookup → Decompose into elements → Retrieve evidence →
          Score relevance → Classify tier/type → Map evidence to elements →
          Derive orientation → Complete

Post:     Coverage recovery (Stage 5.1), video recommendations, auto-archiving

Evidence flows through web search plus specialist source adapters:

Category	Sources
Web search	Serper.dev, Brave Search, SerpAPI (fallback chain)
Fact-check	Google Fact-Check API
Government	GOV.UK, Hansard, GovInfo, Companies House, ONS
Legal	UK Legislation (legislation.gov.uk)
Economic	FRED, Marketaux, World Bank
Academic	Semantic Scholar, OpenAlex, PubMed
Climate	NOAA, WeatherAPI, Open-Meteo, GBIF
Archives	Wikipedia (+ reference mining), Library of Congress, Internet Archive
Health	WHO
Sports	Transfermarkt, Football-Data.org
Video	YouTube Data API

Six Evidence Views

View	Question it answers
Cartographer	What's the shape of this conversation?
Librarian	Is this the full set, clearly labelled?
Interpreter	Does this evidence answer this sub-question?
Projectionist	What's been said on camera?
Chronologist	When did the evidence appear?
Seeker	What don't we know yet?

API & Agent Access

Tru8 exposes a developer API and MCP server for AI agents.

Agent Commerce Gateway

# Quick check (~15s, heuristic classification)
curl -X POST https://api.trueight.com/api/v1/agent/quick \
  -H "X-API-Key: $TRU8_API_KEY" \
  -d '{"claim": "UK inflation is 3.2%"}'

# Smart endpoint with tier fallback (lookup → consensus → quick → full)
curl -X POST https://api.trueight.com/api/v1/agent/check \
  -H "X-API-Key: $TRU8_API_KEY" \
  -d '{"claim": "UK inflation is 3.2%", "max_tier": "full"}'

Tier	Cost	Time	What you get
Lookup	~£0.02	instant	Cached prior analysis
Consensus	~£0.03	instant	Cross-user aggregate landscape (k>=3 checks)
Quick	~£0.07	~15s	Web search + heuristic classification
Full	~£0.15	~60-90s	web + specialist APIs, LLM classification, element decomposition

Three payment rails: x402 (USDC/SIWE), Skyfire (JWT), prepaid credits.

MCP Server

{
  "mcpServers": {
    "tru8": {
      "command": "python",
      "args": ["-m", "tru8_mcp"],
      "env": { "TRU8_API_KEY": "tru8_sk_..." }
    }
  }
}

Tools: tru8_check (evidence research with tier fallback), tru8_get_result (with analytics), tru8_get_result_raw.

Manifest Verification

Every completed check receives an HMAC-SHA256 signed manifest. Verify the signed fields haven't changed since signing:

curl https://api.trueight.com/verify/{check_id}

Testing

cd backend
pytest tests/ -v                        # Full suite (990 tests)
pytest tests/unit/pipeline/ -v          # Pipeline unit tests
pytest tests/unit/agent/ -v             # Agent/commerce tests
pytest tests/integration/ -v            # Integration tests

Infrastructure

Service	Port	Purpose
PostgreSQL 16	5433	Primary database (SQLModel)
Redis 7	6379	Cache + rate limiting
Qdrant	6333	Vector similarity search
MinIO (optional)	9000	Local S3 for file uploads

Auth: Clerk (JWT + JWKS) for dashboard, API keys for developer access. Payments: Stripe (4 subscription tiers) + Agent per-use payments.

API Documentation

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• Health: http://localhost:8000/api/v1/health/

Environment Variables

Copy backend/.env.example to backend/.env. Key groups:

Group	Required	Variables
Database	Yes	DATABASE_URL
Redis	Yes	REDIS_URL
Auth	Yes	CLERK_SECRET_KEY, CLERK_JWT_ISSUER
LLM	Yes	GOOGLE_AI_API_KEY, OPENAI_API_KEY
Search	Yes (at least one)	SERPER_API_KEY, BRAVE_API_KEY, SERP_API_KEY
Payments	For subscriptions	STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
Government APIs	Optional	FRED_API_KEY, NOAA_API_KEY, etc.
Manifest signing	Optional	MANIFEST_SIGNING_ENABLED, MANIFEST_SIGNING_KEY

Feature flags (all default to sensible values): ENABLE_API_RETRIEVAL, ENABLE_LLM_RELEVANCE_SCORER, ENABLE_QUERY_PLANNING, etc. See backend/.env.example for the full list.

Licence

Private — All rights reserved.