TrustLens

Evidence-grounded multimodal intelligence platform for misinformation and incident verification.

1. Project Purpose

TrustLens is designed to perform rigorous, automated, and human-in-the-loop verification of factual claims using live search, request-scoped temporary workspaces, explicit stance detection, source evaluation, calibrated confidence scoring, and strict evidence lineage.

2. Canonical Architecture

TrustLens adheres strictly to the canonical architectural principles established in the Master Project Context:

1. Live Search + Temporary RAG: TrustLens does NOT maintain a permanent global web vector index. All verification workspaces are temporary and scoped to the verification request.
2. Request-Scoped Temporary Workspace: An isolated temporary vector workspace (Qdrant) is created per request, shared across extracted claims, and destroyed upon completion or failure.
3. Claim-Level Verification: Verification occurs at the granular claim level rather than through coarse document-level classification.
4. Hybrid Retrieval & Cross-Encoder Reranking: Evidence is retrieved via combined semantic and lexical search and re-ranked using cross-encoders.
5. Explicit NLI / Stance Detection: Claims are compared against evidence passages using distinct natural language inference labels (SUPPORTS, CONTRADICTS, NEUTRAL, INSUFFICIENT).
6. Constrained Evidence-Grounded LLM Reasoning: The LLM reasons strictly over the validated evidence package assembled by the pipeline.
7. Calibrated Confidence & Explicit Risk Scoring: Machine learning confidence is calibrated independently of raw LLM outputs, and automated risk scoring determines routing.
8. Auditable Workflow Contract: The canonical 21-state workflow is defined in shared contracts; its executable orchestration is introduced in a later phase.

Important

Phase 0 Scope Statement: Phase 0 establishes the project foundation, repository structure, runtime environments, configuration, structured logging, request correlation middleware, modular routing, and shared schema contracts. Phase 0 does NOT implement verification logic, live search, claim extraction, embeddings, retrieval, RAG, or application database tables. Qdrant in Phase 0 is infrastructure-only; no collections or embeddings are created.

3. Canonical Repository Structure

TrustLens/
├── apps/
│   ├── api/                     # FastAPI application shell & routes
│   └── web/                     # React + TypeScript + Vite frontend shell
├── services/                    # Domain services (deferred to future phases)
│   ├── ingestion/               # Phase 1: Ingestion
│   ├── claims/                  # Phase 2: Claim extraction
│   ├── search/                  # Phase 3: Search providers
│   ├── evidence/                # Phase 3: Evidence collection
│   ├── retrieval/               # Phase 4: Hybrid retrieval
│   ├── verification/            # Phase 5: Verification engine
│   ├── multimodal/              # Phase 7: Vision & multimodal
│   ├── source_intelligence/     # Phase 5: Source credibility
│   ├── reasoning/               # Phase 5: Evidence-grounded reasoning
│   ├── scoring/                 # Phase 6: Calibration & scoring
│   ├── reporting/               # Phase 5/8: Reporting
│   └── review/                  # Phase 8: Human review queue
├── models/                      # ML model runtimes (deferred to future phases)
│   ├── embeddings/
│   ├── reranker/
│   ├── nli/
│   └── vision/
├── shared/                      # Reusable core contracts & infrastructure
│   ├── schemas/                 # Shared Pydantic contracts & enums
│   ├── config/                  # Shared settings & environment loader
│   ├── logging/                 # Shared structured JSON logging & correlation context
│   ├── storage/                 # Storage abstractions
│   └── utils/                   # Shared utilities
├── workflows/
│   └── verification_graph/      # Workflow state machine orchestration
├── tests/
│   ├── unit/                    # Fast unit tests
│   ├── integration/             # Integration tests
│   ├── retrieval/               # Retrieval benchmark tests
│   ├── models/                  # Model unit tests
│   └── end_to_end/              # Full pipeline tests
├── evaluation/                  # Benchmarks, datasets, experiments
├── infra/                       # Docker, database, and CI definitions
└── docs/                        # Architecture & Architectural Decision Records

4. Local Setup & Environment

Prerequisites

• Python 3.11+
• Node.js 22+ & npm
• Docker & Docker Compose

Environment Configuration

Copy the template to create your local .env:

cp .env.example .env

Settings are loaded using Pydantic Settings with safe default fallbacks.

Python Environment

Install backend packages with development dependencies:

pip install -e ".[dev]"

Frontend Environment

Install frontend packages deterministically:

cd apps/web
npm ci

5. Running the Application

Via Docker Compose

To build and start all infrastructure services (FastAPI, React frontend, PostgreSQL, Qdrant):

docker compose up -d --build

To view service status and health:

docker compose ps

To stop containers:

docker compose down

(Note: Do not pass -v unless you intend to wipe local persistent volumes).

Local Development

Run backend API locally:

uvicorn apps.api.app.main:app --reload --port 8000

Run frontend locally:

cd apps/web && npm run dev

6. Health & System Endpoints

• Health Check: GET /api/v1/health

  curl -i http://localhost:8000/api/v1/health

  Returns:

  {
    "status": "ok",
    "service": "trustlens-api",
    "version": "0.1.0"
  }

  Response includes the X-Request-ID header containing the validated/generated UUID4 request identifier.

7. Testing, Linting & Type Checking

Run all backend unit tests:

pytest -v

Run code formatting and linting:

ruff check .
ruff format --check .

Run static type checking:

mypy apps shared tests

Build the frontend:

cd apps/web && npm run build