An open-source, evidence-first political statement registry mapping public assertions over time. Powered by Natural Language Inference (NLI) and semantic vector similarity search, the platform tracks statement consistency without accusing politicians of lying. It highlights discrepancies, details confidence metrics, and provides timestamped transcript links so users can review the evidence and form their own conclusions.
- Core Philosophy
- System Architecture
- Technology Stack
- Project Directory Structure
- Database Schema
- AI & ML Pipeline Mechanics
- API Endpoints Directory
- Installation & Setup Guide
- Testing & Quality Assurance
- Production & Scaling Considerations
This platform is built on several key engineering and editorial principles:
- Evidence-First Design: The system prioritizes neutral, verifiable citations. Statements are mapped directly to source audio or video segments with word-level timestamps.
- Explainable AI: Flagged inconsistencies feature clear explanations detailing the linguistic logic mismatches.
- Neutrality & Civility: The platform never accuses politicians of lying or calls statements "false." It matches statements by the same speaker and marks them as semantically incompatible based on logic rules, letting the audience make their own judgments.
The platform uses a modular monolith backend and Celery workers to handle heavy machine learning operations.
This diagram outlines the relationships between frontend views, backend modules, database layers, and background workers.
graph TD
User([User / Journalist / Auditor]) -->|HTTPS| Frontend[Next.js 15 Web App]
Frontend -->|REST APIs / JWT| API[FastAPI Gateway & Core Service]
subgraph CoreBackend ["Backend Services"]
API --> Auth[Auth & RBAC Module]
API --> Profiles[Politician Profiles Module]
API --> Search[Hybrid Search Module]
API --> Ingestion[Ingestion Controller]
API --> Admin[Admin Moderation Module]
end
Ingestion -->|Publish Job| Redis[Redis Broker & Cache]
Redis -->|Consume Job| Workers[Celery AI Workers]
subgraph AIPipeline ["AI Worker Services"]
Workers --> Preprocess[Audio Extractor]
Workers --> Transcribe[WhisperX Service]
Workers --> ClaimExtractor[spaCy / HF Sentence Extractor]
Workers --> Embedder[Sentence Transformer Embeddings]
Workers --> NLIEngine[DeBERTa-v3 MNLI Classifier]
end
CoreBackend -->|SQL / pgvector| PostgreSQL[(PostgreSQL DB)]
Workers -->|Save Transcripts/Claims| PostgreSQL
Shows the step-by-step processing lifecycle when a user submits a political debate or speech URL.
sequenceDiagram
autonumber
actor User as Admin / Moderator
participant FE as Next.js UI
participant BE as FastAPI API
participant DB as PostgreSQL
participant R as Redis (Queue)
participant W as Celery Worker
participant AI as AI Pipeline (WhisperX / DeBERTa)
User->>FE: Submit Ingestion Form (YouTube URL)
FE->>BE: POST /api/v1/speeches/ingest/url (Metadata & Source URL)
BE->>DB: Create Speech Record (status: queued)
BE->>R: Push job `process_speech(speech_id)`
BE-->>FE: Return Job ID (status: queued)
FE->>User: Display processing spinner
Note over W: Worker polls Redis
R->>W: Fetch job `process_speech(speech_id)`
W->>DB: Update Speech (status: PROCESSING)
W->>W: Download Media & Extract Audio (ffmpeg)
W->>AI: Transcribe audio (WhisperX)
AI-->>W: Transcript with word-level timestamps
W->>DB: Save Transcript Segments
W->>AI: Extract claims (spaCy entity + sent segment)
AI-->>W: List of Claims
W->>AI: Generate Embeddings & Query Database for Similar Claims
AI-->>W: Neighboring Claims (Cosine Similarity > 0.70)
loop For each neighbor
W->>AI: Perform NLI (DeBERTa-v3 MNLI)
AI-->>W: NLI Labels (Entailment, Neutral, Contradiction)
alt Contradiction detected
W->>DB: Create Contradiction Record (status: PENDING_REVIEW)
end
end
W->>DB: Update Speech (status: COMPLETED)
Note over FE: Frontend polls status or via WebSockets
FE->>BE: GET /api/v1/speeches/ingest/{id}/status
BE-->>FE: Return status: completed
FE->>User: Display completed transcript & flagged contradictions
The system is built to deploy easily on standard environments and is pre-configured to utilize GPU worker nodes when available.
graph TD
Browser([User Browser]) -->|Cloudflare CDN| Nginx[Nginx Reverse Proxy]
Nginx -->|Route /api/*| CoreBackend[FastAPI App - Gunicorn/Uvicorn]
Nginx -->|Route /*| Front[Next.js App Server]
CoreBackend --> PostgreSQL[(PostgreSQL + pgvector)]
CoreBackend --> Redis[(Redis)]
Redis <--> CeleryGPU[Celery Worker CPU/GPU - WhisperX & NLI]
CeleryGPU --> PostgreSQL
Outlines how raw unstructured media files are transformed into verifiable, structured semantic inconsistency listings.
flowchart TD
RawMedia[Raw YouTube URL / MP4 File]
RawMedia -->|Audio Extraction| Audio[16kHz Mono WAV Audio]
Audio -->|WhisperX Speech-to-Text| Segments[Transcript Segments with Timestamps]
Segments -->|Sentence Segmentation| CleanSentences[Cleaned Sentences]
CleanSentences -->|NER & Coreference Resolution| Claims[Extracted Claims / Assertions]
Claims -->|all-MiniLM-L6-v2| Vectors[Claim Vector Embeddings]
Vectors -->|pgvector Cosine Search| NeighborClaims[Historical Claims with Sim > 0.7]
NeighborClaims -->|DeBERTa-v3-large-MNLI| NLIPair[Premise / Hypothesis Pair]
Claims -->|DeBERTa-v3-large-MNLI| NLIPair
NLIPair -->|NLI Classification| Decision{Contradiction Probability > 0.75?}
Decision -->|Yes| Flagged["Flagged Contradiction & Generate Confidence Score"]
Decision -->|No| SavedClaim["Save Regular Claim to Database"]
- Core: Next.js 15 (App Router), React, TypeScript
- Styling: Tailwind CSS, shadcn/ui components
- State & Fetching: Zustand (global client state), TanStack Query (server state & caching)
- Animations: Framer Motion
- Icons: Lucide React
- API Framework: Python FastAPI
- Database Mapping: SQLAlchemy ORM, Alembic migrations
- Task Queuing: Celery, Redis (as broker & result backend)
- Production Server: Uvicorn / Gunicorn
- Sentence Segmentation & NLP: spaCy (
en_core_web_sm) - Vector Embeddings: Sentence-Transformers (
all-MiniLM-L6-v2- 384 dimensions) - Natural Language Inference (NLI): Hugging Face pipelines (
cross-encoder/nli-deberta-v3-xsmall) - Transcription Core: Whisper / WhisperX ready
- Containerization: Docker, Docker Compose
authenticity/
βββ docker-compose.yml # Container configuration for all services
βββ README.md # System documentation and setup guide
β
βββ backend/ # FastAPI App & Celery Worker
β βββ Dockerfile
β βββ requirements.txt # Backend dependencies
β βββ alembic/ # DB migrations folder
β βββ app/
β βββ main.py # FastAPI App bootstrap
β βββ core/ # Configuration, security, DB connections
β βββ models/ # SQLAlchemy DB schemas
β βββ schemas/ # Pydantic validation structures
β βββ routers/ # API Endpoints (Auth, Profiles, Search, Admin)
β βββ worker/ # Celery application & worker task runners
β βββ tests/ # Pytest suites
β
βββ frontend/ # Next.js 15 App Router Frontend
βββ package.json
βββ tailwind.config.ts
βββ tsconfig.json
βββ src/
βββ app/ # Layouts, pages, route controllers
βββ components/ # Reusable Tailwind / shadcn elements
βββ lib/ # API fetch helpers
βββ store/ # Zustand global client state
βββ types/ # TypeScript typings
We use PostgreSQL with the pgvector extension to support both structured political data and semantic claim embeddings in a single database.
-- Core schemas summary
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
email VARCHAR(255) UNIQUE NOT NULL,
hashed_password VARCHAR(255) NOT NULL,
role VARCHAR(50) NOT NULL DEFAULT 'user' -- 'user', 'journalist', 'admin'
);
CREATE TABLE politicians (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
party VARCHAR(100) NOT NULL,
current_office VARCHAR(255),
bio TEXT,
image_url VARCHAR(512)
);
CREATE TABLE sources (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
name VARCHAR(255) UNIQUE NOT NULL,
classification VARCHAR(50) NOT NULL DEFAULT 'unverified',
base_score NUMERIC(3, 2) NOT NULL DEFAULT 0.60,
website_url VARCHAR(512),
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE speeches (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
politician_id UUID NOT NULL REFERENCES politicians(id) ON DELETE CASCADE,
title VARCHAR(512) NOT NULL,
source_url VARCHAR(512),
media_type VARCHAR(50) NOT NULL, -- 'youtube', 'mp4', 'manual'
status VARCHAR(50) NOT NULL DEFAULT 'pending', -- 'pending', 'processing', 'completed', 'failed'
date_delivered DATE NOT NULL,
file_size_bytes BIGINT,
duration_seconds NUMERIC(8, 2),
audio_codec VARCHAR(50),
download_speed_kbps NUMERIC(8, 2),
error_log TEXT,
source_id UUID REFERENCES sources(id) ON DELETE SET NULL,
credibility_score NUMERIC(3, 2) DEFAULT 0.60,
credibility_breakdown TEXT
);
CREATE TABLE transcript_segments (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
speech_id UUID NOT NULL REFERENCES speeches(id) ON DELETE CASCADE,
sequence_number INT NOT NULL,
start_time NUMERIC(8, 2) NOT NULL, -- seconds
end_time NUMERIC(8, 2) NOT NULL,
text_content TEXT NOT NULL,
language_code VARCHAR(10) NOT NULL DEFAULT 'en',
translated_text TEXT
);
CREATE TABLE claims (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
politician_id UUID NOT NULL REFERENCES politicians(id) ON DELETE CASCADE,
speech_id UUID NOT NULL REFERENCES speeches(id) ON DELETE CASCADE,
segment_id UUID REFERENCES transcript_segments(id) ON DELETE SET NULL,
claim_text TEXT NOT NULL,
embedding VECTOR(384) NOT NULL, -- HNSW Indexed for Cosine Distance search
category VARCHAR(100),
language_code VARCHAR(10) NOT NULL DEFAULT 'en',
original_claim_text TEXT,
typology VARCHAR(50) NOT NULL DEFAULT 'general', -- 'promise', 'statistical', 'legislative', 'general'
extraction_confidence NUMERIC(5, 4) NOT NULL DEFAULT 1.0000,
is_decomposed BOOLEAN NOT NULL DEFAULT FALSE,
parent_claim_id UUID REFERENCES claims(id) ON DELETE SET NULL
);
CREATE TABLE contradictions (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
original_claim_id UUID NOT NULL REFERENCES claims(id) ON DELETE CASCADE,
contradicting_claim_id UUID NOT NULL REFERENCES claims(id) ON DELETE CASCADE,
confidence_score NUMERIC(5, 4) NOT NULL,
explanation TEXT NOT NULL,
review_status VARCHAR(50) NOT NULL DEFAULT 'pending_review' -- 'pending_review', 'verified', 'dismissed'
);
CREATE TABLE promises (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
politician_id UUID NOT NULL REFERENCES politicians(id) ON DELETE CASCADE,
title VARCHAR(512) NOT NULL,
description TEXT NOT NULL,
status VARCHAR(50) NOT NULL DEFAULT 'proposed', -- 'proposed', 'in_progress', 'fulfilled', 'broken', 'stalled'
category VARCHAR(100) NOT NULL,
target_completion_date DATE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE promise_evidence (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
promise_id UUID NOT NULL REFERENCES promises(id) ON DELETE CASCADE,
claim_id UUID REFERENCES claims(id) ON DELETE SET NULL,
evidence_type VARCHAR(50) NOT NULL, -- 'statement', 'bill_vote', 'department_report'
notes TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE audit_logs (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(id) ON DELETE SET NULL,
action VARCHAR(100) NOT NULL,
target_id UUID NOT NULL,
payload TEXT,
prev_hash VARCHAR(64),
signature_hash VARCHAR(64) UNIQUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE subscriptions (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
politician_id UUID REFERENCES politicians(id) ON DELETE CASCADE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT unique_user_politician_sub UNIQUE (user_id, politician_id)
);
CREATE TABLE notifications (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
title VARCHAR(255) NOT NULL,
body VARCHAR(1024) NOT NULL,
is_read BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE feedback_reports (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(id) ON DELETE SET NULL,
target_id UUID NOT NULL,
target_type VARCHAR(50) NOT NULL,
report_type VARCHAR(50) NOT NULL,
description TEXT NOT NULL,
status VARCHAR(50) NOT NULL DEFAULT 'open',
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);When a speech or transcript is ingested, it traverses a structured pipelines run inside Celery:
+--------------+ +--------------+ +--------------+
| Ingest Audio +------>| WhisperX +------>| spaCy Segment|
| Extraction | |Transcriptions| | & Filtering |
+--------------+ +--------------+ +------+-------+
|
v
+--------------+ +--------------+ +------+-------+
| Flag/Publish +<------+ NLI Model |<------+ pgvector Sim |
|Contradictions| | Verification | | Query Top K |
+--------------+ +--------------+ +--------------+
- Transcription & Diarization: WhisperX processes audio files, outputting timestamped segments.
- Claim Extraction: The transcript text is run through a spaCy dependency parser. Conversational filler is discarded; only sentences containing active verbs and subjects are retained as claims.
-
Embeddings & pgvector Search: We generate a dense embedding using
all-MiniLM-L6-v2for each claim. We query the database for historical claims by the same politician:SELECT id, claim_text, (1 - (embedding <=> :query_vector)) AS similarity FROM claims WHERE politician_id = :pid ORDER BY embedding <=> :query_vector LIMIT 5
-
NLI Verification: If cosine similarity exceeds
0.65, the claim pair is submitted to our Natural Language Inference classifier (cross-encoder/nli-deberta-v3-xsmall). If the model indicates acontradictionprobability$>0.70$ , a contradiction record is created and placed in the review queue.
POST /api/v1/auth/register- Create a user profile.POST /api/v1/auth/login- Validate credentials and return JWT bearer token.GET /api/v1/auth/me- Fetch profile metadata of the current user.
GET /api/v1/politicians- Search and list politicians.POST /api/v1/politicians- Add a new politician profile (Requires journalist/admin).GET /api/v1/politicians/{id}- Retrieve politician profile details.GET /api/v1/politicians/{id}/timeline- Fetch statement timeline.
GET /api/v1/speeches- List speeches.POST /api/v1/speeches- Ingest video/transcript and trigger background workers (Requires journalist/admin).POST /api/v1/speeches/ingest/url- Queue media ingestion from external streaming URL (YouTube) with SSRF checks (Requires journalist/admin).POST /api/v1/speeches/ingest/file- Multipart form media file upload, validating types and sizes under 100MB (Requires journalist/admin).GET /api/v1/speeches/ingest/{id}/status- Check background conversion and VAD chunking queue progression stats.GET /api/v1/speeches/{id}- Fetch speech details and full timestamped transcripts.
GET /api/v1/search/claims- Perform hybrid semantic/keyword search over database, supportingtypologyfilters.GET /api/v1/search/claims/hybrid- Perform advanced hybrid dense/sparse search using Reciprocal Rank Fusion (RRF).GET /api/v1/search/claims/{id}/related- Retrieve similar statements delivered by other politicians.
POST /api/v1/promises- Register a new campaign promise (Requires journalist/admin).GET /api/v1/promises- Retrieve list of promises filtered by politician, status, and category.POST /api/v1/promises/evidence- Link supporting/opposing evidence claims to active promises, evaluating status overrides (Requires journalist/admin).
GET /api/v1/sources- List registered media sources.POST /api/v1/sources- Register a new media source profile (Requires journalist/admin).
GET /api/v1/graph/politician/{id}/network- Fetch politician relationship network nodes and edges.
GET /api/v1/admin/contradictions/queue- Retrieve flagged contradictions (Requires journalist/admin).POST /api/v1/admin/contradictions/{id}/review- Approve or dismiss contradiction (Requires journalist/admin).GET /api/v1/admin/speeches/queue- Audit pipeline logs and speech workers (Requires journalist/admin).
POST /api/v1/export/api-keys- Register a new API key.GET /api/v1/export/api-keys- List active API keys.GET /api/v1/export/politician/{id}- Stream bulk politician records (JSON/CSV).
POST /api/v1/notifications/subscribe/{politician_id}- Toggle alert subscription.GET /api/v1/notifications- Retrieve chronological alert log.POST /api/v1/notifications/read-all- Mark all notifications as read.
GET /api/v1/audit/logs- Retrieve sequentially chained audit ledger.GET /api/v1/audit/verify- Verify cryptographic chain sequence integrity.
POST /api/v1/feedback- Submit crowdsourced corrections/context reports.GET /api/v1/admin/feedback/queue- Retrieve pending suggestions queue (Requires journalist/admin).
Make sure you have Docker and Docker Compose installed on your machine.
- Clone the Repository:
git clone https://github.com/your-org/authenticity.git cd authenticity - Build and Run Container Services:
This compiles the backend image, downloads models, sets up PostgreSQL and Redis, installs frontend dependencies, and boots the local dev servers.
docker compose up --build
- Verify running ports:
- Frontend web interface: http://localhost:3000
- FastAPI backend endpoints: http://localhost:8000
- Interactive API Swagger Docs: http://localhost:8000/docs
All core endpoint configurations, token signatures, model parameters, and database schemas are verified.
To run the backend test suite:
- Ensure the containers are running or run a test-runner command:
docker compose run --rm api pytest app/tests
- For testing locally, create a virtual environment in the
backend/directory, install testing packages and run:cd backend python -m venv venv source venv/bin/activate # On Windows: .\venv\Scripts\activate pip install -r requirements.txt pytest app/tests
When shifting this MVP to production:
- Model Offloading: Move the Celery worker nodes to dedicated GPU instances (e.g., AWS EC2 with Nvidia T4/A10G) scheduled via Kubernetes node pools.
- Database Partitioning: Partition the
claimstable by range (e.g., year) or list (politician_id) to keep pgvector indices within memory limits as claims scale into the millions. - Observability: Hook up OpenTelemetry middlewares in FastAPI and Celery to trace inference times across workers, reporting metrics to Prometheus and Sentry.