Upload 26 files

.env

@@ -0,0 +1,46 @@
+# =============================================================================
+# Omnichannel Fact & Hallucination Intelligence System
+# Environment Configuration Template
+# Copy to .env and fill in your values
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# LLM API Keys (set these in HuggingFace Spaces → Settings → Secrets)
+# ---------------------------------------------------------------------------
+
+# Groq API key — used for gatekeeper (llama3-8b), misinformation agent (mixtral-8x7b),
+# AND hallucination agent (llama3-70b). All free via Groq's free tier (30 req/min).
+# Get one at: https://console.groq.com
+GROQ_API_KEY=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
+
+# X (Twitter) API v2 Bearer Token — used for tweet velocity + Community Notes
+# Optional — system falls back to deterministic mock data without it.
+# Get one at: https://developer.twitter.com
+X_BEARER_TOKEN=AAAAAAAAAAAAAAAAAAAAAGLQ8wEAAAAAH6WkY9y9Iw9n8YB9PqMeVA2MIHI%3D9OXISm6Q9fyRNm0DMEAupynHrYZjb1S7AVIU84swKP2IBxpChQ
+
+# ---------------------------------------------------------------------------
+# Infrastructure (auto-configured in Docker Compose — only change for custom setups)
+# ---------------------------------------------------------------------------
+
+QDRANT_HOST=localhost
+QDRANT_PORT=6333
+
+MEMGRAPH_HOST=localhost
+MEMGRAPH_PORT=7687
+MEMGRAPH_PASSWORD=memgraph123
+
+REDPANDA_BROKERS=localhost:9092
+
+REDIS_URL=redis://localhost:6379
+
+# ---------------------------------------------------------------------------
+# App Configuration
+# ---------------------------------------------------------------------------
+
+PORT=7860
+LOG_LEVEL=INFO
+
+# DEMO_MODE=true: Use mock data for all external APIs (LLMs, X API)
+# Useful for exploring the UI/architecture without any API credentials.
+# The system still runs the full pipeline — just with deterministic mock outputs.
+DEMO_MODE=false

.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Extension
+extension/node_modules/
+extension/.output/
+extension/.wxt/
+
+# Infra
+*.pem
+*.key
+.cloudflared/
+
+# Data
+*.jsonl
+*.vtt
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Docker
+.docker/
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -1,14 +1,239 @@
 ---
-title: Rwttrter
-emoji: 🦀
-colorFrom: red
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.12.0
-app_file: app.py
+title: Omnichannel Fact & Hallucination Intelligence System
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
+sdk: docker
 pinned: false
-license: apache-2.0
-short_description: trytryry
+license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Omnichannel Fact & Hallucination Intelligence System
+
+**Near-zero-latency real-time fact-checking and AI hallucination detection — deployed universally via a browser extension across X/Twitter, YouTube, Instagram, news sites, and AI chat interfaces.**
+
+---
+
+## Architecture
+
+```
+Browser Extension (WXT + React 19 + Framer Motion)
+         │  WebSocket (wss://)
+         ▼
+FastAPI Backend ──► Redis Stack (cache, 6h/15min TTL)
+    │
+    ├──► Gatekeeper: Groq llama3-8b-8192 (<120ms p95)
+    │         └── noise → drop | fact → continue
+    │
+    ├──► RAG Pipeline (concurrent)
+    │         ├── FastEmbed BGE-M3 embeddings (CPU, multilingual)
+    │         ├── Qdrant ANN search (HNSW ef=128, top-8, 72h window)
+    │         └── Memgraph trust graph traversal (in-memory Cypher)
+    │
+    ├──► Grok Sensor (concurrent)
+    │         └── X API v2 velocity + Community Notes
+    │
+    └──► Prefect Flow (multi-agent evaluation)
+              ├── misinformation_task: Groq mixtral-8x7b-32768
+              └── hallucination_task: Claude Haiku (AI platforms only)
+                        │
+                        ▼
+              AnalysisResult → WebSocket → Extension → DOM highlight + hover card
+```
+
+---
+
+## Stack
+
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| Extension framework | WXT v0.19 + React 19 | HMR, multi-browser, TypeScript-first, Vite |
+| Extension state | Zustand + chrome.storage.sync | Persistent, reactive, cross-context |
+| LLM gatekeeper | Groq llama3-8b-8192 | 800+ tok/s, <100ms, no GPU needed |
+| LLM evaluation | LiteLLM → Groq mixtral-8x7b / llama3-70b | All free via Groq — swap providers without code changes |
+| Embeddings | BGE-M3 via FastEmbed | 100+ languages, 1024-dim, CPU-native, free |
+| Vector DB | Qdrant (self-hosted) | Sub-ms HNSW search, no vendor lock-in |
+| Graph DB | Memgraph (in-memory) | 10–100x faster than Neo4j for trust scoring |
+| Message queue | Redpanda | Kafka-compatible, no JVM, 10x lower latency |
+| Orchestration | Prefect | Native async, DAG flows, built-in retry |
+| Cache | Redis Stack (RedisJSON) | Structured claim cache, TTL per verdict color |
+| Package manager | uv | 10–100x faster than pip, lockfiles |
+| Hashing | xxhash (client + server) | Sub-microsecond content deduplication |
+| Edge tunnel | Cloudflare Tunnel | Zero-config TLS, no exposed ports |
+| Observability | structlog + rich | Structured JSON logs, colorized dev output |
+
+---
+
+## Quick Start (HuggingFace Spaces)
+
+This Space runs the **backend + demo UI** via Docker. The browser extension is a separate build.
+
+### Required Secrets (set in Space settings → Secrets)
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `GROQ_API_KEY` | Recommended | Groq API key — powers all 3 LLM agents (gatekeeper, misinformation, hallucination). Free tier: 30 req/min |
+| `X_BEARER_TOKEN` | Optional | X API v2 bearer token for tweet velocity + Community Notes |
+
+**Without any API keys**: The system runs in `DEMO_MODE=true` with deterministic mock results — great for exploring the UI and architecture without credentials.
+
+Get a free key:
+- Groq: https://console.groq.com (free tier: 30 req/min — covers all 3 LLM agents)
+
+### Run Locally
+
+```bash
+git clone <repo>
+cd omnichannel-fact-intelligence
+
+# Copy env template
+cp .env.example .env
+# Edit .env with your API keys
+
+# Start all services (Qdrant, Memgraph, Redpanda, Redis, FastAPI)
+docker compose up
+
+# Visit http://localhost:7860 for the demo UI
+```
+
+### Run Backend Only (no Docker for infra)
+
+```bash
+cd backend
+
+# Install uv (if not installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv sync
+
+# Set env vars
+export GROQ_API_KEY=your_key
+export DEMO_MODE=true  # Skip infrastructure deps for quick testing
+
+# Start FastAPI
+uv run uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+```
+
+---
+
+## Browser Extension Setup
+
+### Prerequisites
+```bash
+cd extension
+npm install  # or: bun install
+```
+
+### Development (Chrome)
+```bash
+# Set your backend URL (or use cloudflared tunnel)
+WS_URL=ws://localhost:7860/ws npx wxt dev --browser chrome
+```
+
+### Production Build
+```bash
+# Build for all browsers
+WS_URL=wss://fact-engine.your-domain.com/ws npx wxt build
+
+# Chrome: .output/chrome-mv3/
+# Firefox: .output/firefox-mv3/
+```
+
+### Load in Chrome
+1. Navigate to `chrome://extensions`
+2. Enable **Developer mode** (top right)
+3. Click **Load unpacked** → select `.output/chrome-mv3/`
+4. Visit X/Twitter, YouTube, or any news site — facts will begin highlighting
+
+---
+
+## Highlight Color Semantics
+
+| Color | Hex | Meaning |
+|-------|-----|---------|
+| 🟢 Green | `#22c55e` | Fact-checked — corroborated by ≥2 sources, trust score ≥ 0.65 |
+| 🟡 Yellow | `#eab308` | Unverified — breaking news, weak corroboration, high velocity |
+| 🔴 Red | `#ef4444` | Debunked — refuted by ≥2 independent sources or Community Note active |
+| 🟣 Purple | `#a855f7` | AI hallucination — fabricated citation, impossibility, contradiction |
+
+---
+
+## Trust Score Algorithm
+
+```
+score = 0.5 (baseline)
++ 0.30  if Author.verified AND account_type IN ['government', 'official_news']
++ 0.05  per corroborating Source node (capped at +0.25, i.e. 5 sources)
+- 0.40  if any Source has an active Community Note
+= clamp(score, 0.0, 1.0)
+```
+
+---
+
+## Data Pipeline
+
+Three async Redpanda producers simulate the omnichannel firehose:
+
+| Producer | Topic | Rate | Source |
+|----------|-------|------|--------|
+| twitter_producer | `raw.twitter` | 50 eps | Mock X posts |
+| instagram_producer | `raw.instagram` | 20 eps | Mock story text (OCR-extracted) |
+| youtube_producer | `raw.youtube` | 10 eps | Mock VTT transcript chunks |
+
+A single async consumer aggregates all three, deduplicates by `content_hash`, and upserts into Qdrant + Memgraph.
+
+---
+
+## Extension Modes
+
+| Mode | Shows |
+|------|-------|
+| Minimal | Red + Purple only |
+| Normal (default) | Red + Purple + Yellow |
+| Advanced | All colors including Green |
+
+---
+
+## File Structure
+
+```
+omnichannel-fact-intelligence/
+├── docker-compose.yml              # All services in one command
+├── .env.example                    # Environment template
+│
+├── backend/
+│   ├── Dockerfile                  # uv + Python 3.12
+│   ├── pyproject.toml              # All deps pinned (uv-compatible)
+│   ├── main.py                     # FastAPI app, WebSocket, Redis cache
+│   ├── gatekeeper.py               # Groq fact/noise classifier (<120ms p95)
+│   ├── rag_pipeline.py             # BGE-M3 + Qdrant + Memgraph trust graph
+│   ├── grok_sensor.py              # X API v2 + Community Notes
+│   ├── agents.py                   # Prefect flow + LiteLLM multi-agent eval
+│   ├── core/
+│   │   ├── config.py               # Pydantic-settings centralized config
+│   │   └── models.py               # All Pydantic v2 models
+│   ├── producers/
+│   │   └── producers.py            # Twitter + Instagram + YouTube + consumer
+│   └── static/
+│       └── index.html              # Demo UI (served at /)
+│
+├── extension/
+│   ├── wxt.config.ts               # WXT framework config
+│   ├── stores/
+│   │   └── extensionStore.ts       # Zustand + chrome.storage.sync
+│   └── entrypoints/
+│       ├── background.ts           # Persistent WS connection + message routing
+│       ├── content.tsx             # MutationObserver + highlight + hover card
+│       └── popup.tsx               # Master toggle + mode selector + badge
+│
+└── infra/
+    └── tunnel_setup.sh             # Cloudflare Tunnel setup script
+```
+
+---
+
+## License
+
+MIT — see LICENSE for details.

backend/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+# Install uv — 10-100x faster than pip, proper lockfiles
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Install system deps for FastEmbed / BGE-M3 CPU inference
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential curl git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy dependency files first (layer cache optimization)
+COPY pyproject.toml uv.lock* ./
+
+# Install all Python dependencies into the project virtual env
+RUN uv sync --frozen --no-dev
+
+# Copy application source
+COPY . .
+
+# Pre-download BGE-M3 model so cold starts are instant
+RUN uv run python -c "from fastembed import TextEmbedding; TextEmbedding('BAAI/bge-m3')" || true
+
+EXPOSE 7860
+
+CMD ["uv", "run", "python", "app.py"]

backend/agents.py

@@ -0,0 +1,338 @@
+"""
+agents.py — Prefect-orchestrated multi-agent evaluation layer.
+
+Two concurrent agents evaluate each claim:
+
+  1. misinformation_task  → Groq mixtral-8x7b-32768
+     Given: claim + top-3 RAG evidence chunks + trust score
+     Output: color (red|yellow|green), confidence, explanation, sources
+
+  2. hallucination_task   → Claude Haiku (runs ONLY on AI chat platforms)
+     Given: claim text
+     Output: color (purple|green), confidence, explanation
+     Checks for: fabricated citations, statistical impossibilities,
+                 internal contradictions, LLM-specific failure patterns
+
+Both tasks run concurrently via asyncio.gather. Prefect merges results,
+picks higher-severity color, returns the final AnalysisResult.
+
+Why Prefect over Celery:
+  - Dynamic DAG-based orchestration (no pre-declared task graph)
+  - Native async support — no gevent hacks needed
+  - Built-in retry with exponential backoff per task
+  - Far better observability: every flow run gets a full execution trace
+  - Deployable without a separate worker process (embedded server mode)
+"""
+
+import asyncio
+import time
+from typing import Literal
+
+import structlog
+from litellm import acompletion
+from prefect import flow, task
+from prefect.tasks import task_input_hash
+
+from core.config import HighlightColor, Platform, Settings, get_settings
+from core.models import AnalysisResult, EvidenceChunk, GrokSensorResult, RAGResult, SourceRef, TrustScore
+
+log = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Color severity ordering (higher index = more severe)
+# ---------------------------------------------------------------------------
+SEVERITY: dict[HighlightColor, int] = {
+    HighlightColor.GREEN: 0,
+    HighlightColor.YELLOW: 1,
+    HighlightColor.RED: 2,
+    HighlightColor.PURPLE: 3,
+}
+
+# ---------------------------------------------------------------------------
+# LiteLLM prompts
+# ---------------------------------------------------------------------------
+
+MISINFO_SYSTEM = """You are a professional fact-checker with access to recent evidence.
+Analyze the claim against the evidence chunks and trust score. Output ONLY valid JSON.
+
+Output schema (no markdown, no preamble):
+{
+  "color": "red" | "yellow" | "green",
+  "confidence": <integer 0-100>,
+  "explanation": "<2-3 sentence explanation for the hover card>",
+  "verdict_label": "<8 words max, e.g. 'Debunked by Reuters and AP'>",
+  "sources": ["<url1>", "<url2>", "<url3>"]
+}
+
+Color logic:
+- "green": Claim is factually accurate, corroborated by ≥2 independent sources, trust score ≥ 0.65
+- "yellow": Claim is unverified, breaking news, or evidence is weak/contradictory
+- "red": Claim is demonstrably false, debunked by ≥2 sources, OR trust score < 0.25, OR community note active"""
+
+MISINFO_USER_TMPL = """Claim: {claim}
+
+Trust score: {trust_score:.2f} (0=untrustworthy, 1=highly trusted)
+Author verified: {verified}
+Active Community Note: {has_note}{note_text_part}
+Corroborating sources in database: {source_count}
+
+Evidence chunks (cosine similarity descending):
+{evidence_text}
+
+Analyze and output JSON."""
+
+HALLUCINATION_SYSTEM = """You are an LLM output auditor specializing in detecting AI hallucinations.
+Analyze the following text that was generated by an AI system. Output ONLY valid JSON.
+
+Output schema:
+{
+  "color": "purple" | "green",
+  "confidence": <integer 0-100>,
+  "explanation": "<specific explanation of what's wrong, or confirmation it's accurate>"
+}
+
+Check for:
+1. Fabricated citations: URLs, paper titles, author names that don't exist
+2. Statistical impossibilities: numbers that exceed known bounds (e.g., "500% of people")
+3. Internal contradictions: statements that contradict each other within the text
+4. Temporal paradoxes: referencing future events as past, or anachronistic details
+5. Entity confusion: mixing attributes of different real-world entities
+
+Color "purple" only if you find a clear, specific hallucination pattern.
+Color "green" if the text appears factually coherent (you cannot verify external facts)."""
+
+
+# ---------------------------------------------------------------------------
+# Prefect tasks — each is independently retried with exponential backoff
+# ---------------------------------------------------------------------------
+
+@task(
+    name="misinformation-agent",
+    retries=2,
+    retry_delay_seconds=[1, 3],
+    cache_key_fn=task_input_hash,
+    cache_expiration=None,
+    log_prints=False,
+)
+async def misinformation_task(
+    claim: str,
+    evidence: list[EvidenceChunk],
+    trust: TrustScore,
+    grok: GrokSensorResult,
+    settings: Settings,
+) -> dict:
+    """
+    Groq mixtral-8x7b-32768 evaluates the claim against RAG evidence.
+    32k context window accommodates all 8 evidence chunks comfortably.
+    """
+    # Build evidence text block (top-3 by cosine score for the prompt)
+    top_evidence = sorted(evidence, key=lambda e: e.score, reverse=True)[:3]
+    evidence_text = "\n\n".join(
+        f"[{i+1}] Source: {e.domain} (similarity: {e.score:.3f})\n{e.text[:400]}"
+        for i, e in enumerate(top_evidence)
+    ) or "No evidence chunks retrieved (claim may be too recent or niche)."
+
+    note_part = f"\nCommunity Note: {trust.community_note_text}" if trust.community_note_text else ""
+
+    user_prompt = MISINFO_USER_TMPL.format(
+        claim=claim[:500],
+        trust_score=trust.score,
+        verified=trust.author_verified,
+        has_note=trust.has_community_note,
+        note_text_part=note_part,
+        source_count=trust.corroborating_sources,
+        evidence_text=evidence_text,
+    )
+
+    # LiteLLM routes to Groq — swap to "openai/gpt-4o" or "groq/llama3-70b-8192"
+    # by changing a single string, zero code changes elsewhere
+    response = await acompletion(
+        model=settings.misinformation_model,
+        messages=[
+            {"role": "system", "content": MISINFO_SYSTEM},
+            {"role": "user", "content": user_prompt},
+        ],
+        response_format={"type": "json_object"},
+        temperature=0.1,
+        max_tokens=400,
+        api_key=settings.groq_api_key or None,
+    )
+
+    import json
+    raw = response.choices[0].message.content or "{}"
+    return json.loads(raw)
+
+
+@task(
+    name="hallucination-agent",
+    retries=2,
+    retry_delay_seconds=[1, 3],
+    log_prints=False,
+)
+async def hallucination_task(claim: str, settings: Settings) -> dict:
+    """
+    Groq llama3-70b-8192 audits AI-generated text for hallucination patterns.
+    Previously Claude Haiku — now fully free via Groq, same prompt, same output schema.
+    Only invoked when the source platform is an AI chat interface.
+    """
+    response = await acompletion(
+        model=settings.hallucination_model,  # groq/llama3-70b-8192
+        messages=[
+            {"role": "system", "content": HALLUCINATION_SYSTEM},
+            {"role": "user", "content": f"Audit this AI-generated text:\n\n{claim[:1000]}"},
+        ],
+        response_format={"type": "json_object"},
+        temperature=0.0,
+        max_tokens=300,
+        api_key=settings.groq_api_key or None,
+    )
+
+    import json
+    raw = response.choices[0].message.content or "{}"
+    return json.loads(raw)
+
+
+def _demo_misinfo_result(trust_score: float, has_note: bool) -> dict:
+    """Deterministic demo result when LLM keys are absent."""
+    if has_note or trust_score < 0.25:
+        return {
+            "color": "red", "confidence": 82,
+            "explanation": "Demo mode: trust score below threshold and/or active community note detected.",
+            "verdict_label": "Low trust signal detected",
+            "sources": [],
+        }
+    elif trust_score < 0.55:
+        return {
+            "color": "yellow", "confidence": 61,
+            "explanation": "Demo mode: insufficient corroboration to confirm or deny this claim.",
+            "verdict_label": "Unverified — insufficient evidence",
+            "sources": [],
+        }
+    return {
+        "color": "green", "confidence": 78,
+        "explanation": "Demo mode: claim appears well-corroborated based on trust graph signals.",
+        "verdict_label": "Appears credible",
+        "sources": [],
+    }
+
+
+def _demo_hallucination_result() -> dict:
+    return {
+        "color": "purple", "confidence": 71,
+        "explanation": "Demo mode: AI-generated content detected. Unable to verify external citations without live API.",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Main Prefect flow
+# ---------------------------------------------------------------------------
+
+@flow(name="fact-intelligence-pipeline", log_prints=False)
+async def evaluate_claim(
+    claim: str,
+    claim_hash: str,
+    element_id: str,
+    platform: Platform,
+    rag_result: RAGResult,
+    grok_result: GrokSensorResult,
+    settings: Settings | None = None,
+) -> AnalysisResult:
+    """
+    Orchestrates the full multi-agent evaluation as a Prefect flow.
+
+    Concurrent execution:
+      - misinformation_task always runs
+      - hallucination_task runs only for AI chat platforms
+
+    Results are merged by taking the higher-severity color.
+    The final AnalysisResult is returned directly (no Celery queue needed).
+    """
+    cfg = settings or get_settings()
+    t0 = time.perf_counter()
+
+    is_ai_platform = platform in (Platform.CHATGPT, Platform.CLAUDE, Platform.GEMINI)
+
+    # Determine whether to use demo mode
+    use_demo = cfg.demo_mode or not cfg.has_groq
+
+    if use_demo:
+        misinfo_raw = _demo_misinfo_result(rag_result.trust.score, grok_result.community_note)
+        halluc_raw = _demo_hallucination_result() if is_ai_platform else None
+    else:
+        # Concurrently run both agents when applicable
+        # Both agents now use Groq (free) — no Anthropic key needed
+        if is_ai_platform and cfg.has_groq:
+            misinfo_raw, halluc_raw = await asyncio.gather(
+                misinformation_task(claim, rag_result.evidence, rag_result.trust, grok_result, cfg),
+                hallucination_task(claim, cfg),
+            )
+        else:
+            misinfo_raw = await misinformation_task(
+                claim, rag_result.evidence, rag_result.trust, grok_result, cfg
+            )
+            halluc_raw = None
+
+    # --- Merge results: pick higher-severity color ---
+    misinfo_color = HighlightColor(misinfo_raw.get("color", "yellow"))
+    final_color = misinfo_color
+    final_confidence = misinfo_raw.get("confidence", 50)
+    final_explanation = misinfo_raw.get("explanation", "")
+    final_verdict = misinfo_raw.get("verdict_label", "Under review")
+
+    if halluc_raw:
+        halluc_color = HighlightColor(halluc_raw.get("color", "green"))
+        if SEVERITY[halluc_color] > SEVERITY[final_color]:
+            final_color = halluc_color
+            final_confidence = halluc_raw.get("confidence", final_confidence)
+            final_explanation = halluc_raw.get("explanation", final_explanation)
+            final_verdict = "AI hallucination detected"
+
+    # Build SourceRef list from evidence + misinfo agent sources
+    raw_sources: list[str] = misinfo_raw.get("sources", [])
+    evidence_sources = [e.source_url for e in rag_result.evidence[:3] if e.source_url]
+    combined = list(dict.fromkeys(raw_sources + evidence_sources))[:3]  # deduplicated, max 3
+
+    source_refs = [
+        SourceRef(
+            url=url,
+            domain=_extract_domain(url),
+            favicon_url=f"https://www.google.com/s2/favicons?domain={_extract_domain(url)}&sz=16",
+            snippet="",
+        )
+        for url in combined
+    ]
+
+    latency_ms = round((time.perf_counter() - t0) * 1000, 2)
+
+    log.info(
+        "agents.flow.complete",
+        color=final_color,
+        confidence=final_confidence,
+        platform=platform,
+        latency_ms=latency_ms,
+        demo=use_demo,
+    )
+
+    return AnalysisResult(
+        element_id=element_id,
+        content_hash=claim_hash,
+        platform=platform,
+        color=final_color,
+        confidence=final_confidence,
+        verdict_label=final_verdict,
+        explanation=final_explanation,
+        sources=source_refs,
+        gatekeeper_label="fact",
+        trust_score=rag_result.trust.score,
+        velocity=grok_result.velocity,
+        has_community_note=grok_result.community_note,
+        latency_ms=latency_ms,
+    )
+
+
+def _extract_domain(url: str) -> str:
+    try:
+        from urllib.parse import urlparse
+        return urlparse(url).netloc.lstrip("www.")
+    except Exception:
+        return url

backend/app.py

@@ -0,0 +1,513 @@
+"""
+app.py — Single entry point for HuggingFace Spaces.
+
+Run with:
+  uv run python app.py          ← HuggingFace Spaces / production
+  uv run uvicorn app:app --reload  ← local dev
+
+Lifecycle on startup:
+  1. Configures structured logging
+  2. Waits for Redis / Qdrant / Memgraph to be healthy (skipped in DEMO_MODE)
+  3. Initialises Qdrant collection + Memgraph schema
+  4. Seeds demo evidence chunks into Qdrant
+  5. Warms up BGE-M3 embedder in the background
+  6. Serves FastAPI on port 7860 (HuggingFace default)
+
+WebSocket message lifecycle (per text segment):
+  1. Extension sends TextBatch  →  Redis cache check (xxhash key)
+  2. Cache miss  →  Gatekeeper (Groq llama3-8b, <120 ms p95)
+  3. Noise  →  dropped.  Fact  →  continue
+  4. Concurrent: RAG pipeline (BGE-M3 + Qdrant + Memgraph) + Grok sensor
+  5. Prefect flow: misinformation agent + hallucination agent (both Groq, free)
+  6. AnalysisResult cached in Redis (TTL: 6 h green/red, 15 min yellow, no-cache purple)
+  7. Result streamed back over WebSocket → extension applies DOM highlight + hover card
+"""
+
+import asyncio
+import os
+import sys
+import time
+from contextlib import asynccontextmanager
+from typing import Any
+
+import orjson
+import redis.asyncio as aioredis
+import structlog
+import xxhash
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
+from pydantic import ValidationError
+
+# ---------------------------------------------------------------------------
+# Bootstrap logging FIRST so every subsequent import logs correctly
+# ---------------------------------------------------------------------------
+from core.logging import configure_logging
+from core.config import HighlightColor, Platform, get_settings
+
+settings = get_settings()
+configure_logging(
+    log_level=settings.log_level,
+    json_output=os.environ.get("JSON_LOGS", "false").lower() == "true",
+)
+log = structlog.get_logger("app")
+
+# ---------------------------------------------------------------------------
+# Remaining imports (after logging is configured)
+# ---------------------------------------------------------------------------
+from agents import evaluate_claim
+from core.models import AnalysisResult, GatekeeperResult, TextBatch, WSInbound, WSOutbound
+from gatekeeper import classify_claim
+from grok_sensor import query_grok_sensor
+from rag_pipeline import run_rag_pipeline
+
+# ============================================================================
+# SECTION 1 — Infrastructure health checks (used during startup)
+# ============================================================================
+
+async def _wait_for_redis(url: str, timeout: int = 30) -> bool:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            r = await aioredis.from_url(url, decode_responses=True)
+            await r.ping()
+            await r.aclose()
+            return True
+        except Exception:
+            await asyncio.sleep(1)
+    return False
+
+
+async def _wait_for_qdrant(host: str, port: int, timeout: int = 30) -> bool:
+    import httpx
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            async with httpx.AsyncClient(timeout=2.0) as client:
+                resp = await client.get(f"http://{host}:{port}/readyz")
+                if resp.status_code == 200:
+                    return True
+        except Exception:
+            await asyncio.sleep(1)
+    return False
+
+
+async def _wait_for_memgraph(host: str, port: int, timeout: int = 30) -> bool:
+    from neo4j import AsyncGraphDatabase
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            driver = AsyncGraphDatabase.driver(
+                f"bolt://{host}:{port}",
+                auth=("", settings.memgraph_password),
+                encrypted=False,
+            )
+            async with driver.session() as session:
+                await session.run("RETURN 1;")
+            await driver.close()
+            return True
+        except Exception:
+            await asyncio.sleep(2)
+    return False
+
+
+# ============================================================================
+# SECTION 2 — Demo data seeding (populates Qdrant for the HF Spaces demo UI)
+# ============================================================================
+
+_DEMO_EVIDENCE = [
+    {
+        "text": "mRNA vaccines demonstrated sustained immune responses lasting 18-24 months across multiple peer-reviewed studies.",
+        "url": "https://www.nejm.org/doi/10.1056/NEJMoa2034577",
+        "domain": "nejm.org",
+    },
+    {
+        "text": "The Federal Reserve raised interest rates by 75 basis points in June 2022, the largest single hike since 1994.",
+        "url": "https://reuters.com/markets/us/fed-hikes-rates-2022-06-15",
+        "domain": "reuters.com",
+    },
+    {
+        "text": "Amazon deforestation data showed over 11,000 sq km lost in a single year at record levels.",
+        "url": "https://apnews.com/article/amazon-deforestation-record",
+        "domain": "apnews.com",
+    },
+    {
+        "text": "The United Nations projects global population will peak around 10.4 billion in the 2080s based on current demographic trends.",
+        "url": "https://www.un.org/development/desa/pd/",
+        "domain": "un.org",
+    },
+    {
+        "text": "Renewable energy accounted for 30% of global electricity generation in 2023 according to the International Energy Agency.",
+        "url": "https://www.iea.org/reports/renewables-2023",
+        "domain": "iea.org",
+    },
+    {
+        "text": "Social media use exceeding 3 hours daily correlates with higher anxiety rates in adolescents per multiple longitudinal studies.",
+        "url": "https://jamanetwork.com/journals/jamapediatrics/fullarticle/2767581",
+        "domain": "jamanetwork.com",
+    },
+]
+
+
+async def _seed_demo_data() -> None:
+    """Upsert demo evidence chunks into Qdrant so the demo UI returns real RAG results."""
+    import uuid
+    from qdrant_client.models import PointStruct
+    from rag_pipeline import embed_texts, get_qdrant
+
+    log.info("demo.seed.start", count=len(_DEMO_EVIDENCE))
+    client = await get_qdrant(settings)
+    texts = [e["text"] for e in _DEMO_EVIDENCE]
+    vectors = await embed_texts(texts)
+
+    points = [
+        PointStruct(
+            id=str(uuid.uuid4()),
+            vector=vec,
+            payload={
+                "text": ev["text"],
+                "source_url": ev["url"],
+                "domain": ev["domain"],
+                "platform": "news",
+                "content_hash": f"demo_{i:04d}",
+                "ingested_at_ts": time.time(),
+                "author_handle": "demo_seed",
+                "bias_rating": "center",
+            },
+        )
+        for i, (ev, vec) in enumerate(zip(_DEMO_EVIDENCE, vectors))
+    ]
+    await client.upsert(collection_name=settings.qdrant_collection, points=points)
+    log.info("demo.seed.complete", count=len(points))
+
+
+# ============================================================================
+# SECTION 3 — Redis singleton
+# ============================================================================
+
+_redis: aioredis.Redis | None = None
+
+
+async def get_redis() -> aioredis.Redis:
+    global _redis
+    if _redis is None:
+        _redis = await aioredis.from_url(settings.redis_url, decode_responses=True)
+    return _redis
+
+
+# ============================================================================
+# SECTION 4 — WebSocket connection manager
+# ============================================================================
+
+class ConnectionManager:
+    def __init__(self) -> None:
+        self.active: dict[str, WebSocket] = {}
+
+    async def connect(self, session_id: str, ws: WebSocket) -> None:
+        await ws.accept()
+        self.active[session_id] = ws
+        log.info("ws.connected", session_id=session_id, total=len(self.active))
+
+    def disconnect(self, session_id: str) -> None:
+        self.active.pop(session_id, None)
+        log.info("ws.disconnected", session_id=session_id, total=len(self.active))
+
+    async def send(self, session_id: str, payload: Any) -> None:
+        ws = self.active.get(session_id)
+        if ws:
+            msg = WSOutbound(type="result", payload=payload)
+            await ws.send_bytes(orjson.dumps(msg.model_dump(mode="json")))
+
+
+manager = ConnectionManager()
+
+
+# ============================================================================
+# SECTION 5 — FastAPI lifespan (startup + shutdown)
+# ============================================================================
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    log.info("startup.begin", demo_mode=settings.demo_mode, port=settings.port)
+
+    if not settings.demo_mode:
+        # Wait for all infrastructure services
+        log.info("startup.waiting_for_services")
+
+        if not await _wait_for_redis(settings.redis_url):
+            log.error("startup.redis.timeout"); sys.exit(1)
+        log.info("startup.redis.ok")
+
+        if not await _wait_for_qdrant(settings.qdrant_host, settings.qdrant_port):
+            log.error("startup.qdrant.timeout"); sys.exit(1)
+        log.info("startup.qdrant.ok")
+
+        if not await _wait_for_memgraph(settings.memgraph_host, settings.memgraph_port):
+            log.warning("startup.memgraph.timeout — trust scores will use neutral 0.5 fallback")
+        else:
+            log.info("startup.memgraph.ok")
+
+        # Initialise DB schemas (idempotent)
+        from core.db_init import init_all
+        await init_all(settings)
+
+        # Seed demo evidence into Qdrant
+        try:
+            await _seed_demo_data()
+        except Exception as exc:
+            log.warning("startup.seed.failed", error=str(exc))
+    else:
+        # Demo mode: just make sure Redis is reachable (may be local or absent)
+        try:
+            r = await get_redis()
+            await r.ping()
+            log.info("startup.redis.ok")
+        except Exception:
+            log.warning("startup.redis.unavailable — cache disabled in demo mode")
+
+    # Pre-warm BGE-M3 embedder in the background (avoids cold-start spike on first request)
+    async def _warm():
+        try:
+            from rag_pipeline import embed_texts
+            await embed_texts(["warm up"])
+            log.info("startup.embedder.warm")
+        except Exception as exc:
+            log.warning("startup.embedder.warn", error=str(exc))
+
+    asyncio.create_task(_warm())
+    log.info("startup.complete")
+
+    yield  # ← app is live and serving
+
+    # Graceful shutdown
+    if _redis:
+        await _redis.aclose()
+    log.info("shutdown.complete")
+
+
+# ============================================================================
+# SECTION 6 — FastAPI application
+# ============================================================================
+
+app = FastAPI(
+    title="Omnichannel Fact & Hallucination Intelligence API",
+    version="1.0.0",
+    description="Near-zero-latency fact-checking and hallucination detection via WebSocket",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ============================================================================
+# SECTION 7 — Core analysis pipeline
+# ============================================================================
+
+async def process_segment(
+    text: str,
+    content_hash: str,
+    element_id: str,
+    platform: Platform,
+) -> AnalysisResult | None:
+    """
+    Full pipeline for a single text segment. Returns None if noise.
+
+    Cache key:  verdict:{content_hash}
+    TTL:        6 h  → green / red
+                15 m → yellow
+                none → purple (hallucination results are context-specific)
+    """
+    # 1 — Redis cache check (sub-millisecond)
+    try:
+        r = await get_redis()
+        cached_json = await r.get(f"verdict:{content_hash}")
+        if cached_json:
+            result = AnalysisResult.model_validate_json(cached_json)
+            result.cached = True
+            result.element_id = element_id
+            log.debug("cache.hit", hash=content_hash[:8])
+            return result
+    except Exception:
+        pass  # Redis unavailable in demo mode — continue without cache
+
+    # 2 — Gatekeeper: fact vs noise (<120 ms p95)
+    try:
+        gate: GatekeeperResult = await classify_claim(text, settings)
+    except Exception as exc:
+        log.error("gatekeeper.error", error=str(exc))
+        return None
+
+    if gate.label == "noise":
+        log.debug("gatekeeper.noise_dropped", hash=content_hash[:8])
+        return None
+
+    # 3 — Concurrent: RAG pipeline + Grok sensor
+    rag_result, grok_result = await asyncio.gather(
+        run_rag_pipeline(text, content_hash, settings),
+        query_grok_sensor(text, content_hash, settings),
+    )
+
+    # 4 — Multi-agent Prefect flow
+    result: AnalysisResult = await evaluate_claim(
+        claim=text,
+        claim_hash=content_hash,
+        element_id=element_id,
+        platform=platform,
+        rag_result=rag_result,
+        grok_result=grok_result,
+        settings=settings,
+    )
+
+    # 5 — Cache with color-appropriate TTL
+    try:
+        r = await get_redis()
+        if result.color != HighlightColor.PURPLE:
+            ttl = (
+                settings.cache_ttl_green_red
+                if result.color in (HighlightColor.GREEN, HighlightColor.RED)
+                else settings.cache_ttl_yellow
+            )
+            await r.setex(f"verdict:{content_hash}", ttl, result.model_dump_json())
+    except Exception:
+        pass
+
+    return result
+
+
+# ============================================================================
+# SECTION 8 — WebSocket endpoint
+# ============================================================================
+
+@app.websocket("/ws/{session_id}")
+async def websocket_endpoint(ws: WebSocket, session_id: str):
+    """
+    Persistent WebSocket connection from the browser extension.
+
+    Inbound:  { type: "batch", payload: TextBatch }
+            | { type: "ping" }
+    Outbound: { type: "result",  payload: AnalysisResult }
+            | { type: "pong" }
+            | { type: "error",  payload: { message: str } }
+            | { type: "status", payload: { connected: bool, demo_mode: bool, … } }
+    """
+    await manager.connect(session_id, ws)
+
+    # Initial handshake
+    await ws.send_bytes(orjson.dumps(
+        WSOutbound(type="status", payload={
+            "connected": True,
+            "demo_mode": settings.demo_mode,
+            "has_groq": settings.has_groq,
+            "has_x_api": settings.has_x_api,
+        }).model_dump(mode="json")
+    ))
+
+    try:
+        while True:
+            raw = await ws.receive_bytes()
+            envelope = WSInbound.model_validate_json(raw)
+
+            if envelope.type == "ping":
+                await ws.send_bytes(orjson.dumps(
+                    WSOutbound(type="pong", payload=None).model_dump(mode="json")
+                ))
+                continue
+
+            if envelope.type != "batch" or not envelope.payload:
+                continue
+
+            try:
+                batch = TextBatch.model_validate(envelope.payload)
+            except ValidationError as exc:
+                await ws.send_bytes(orjson.dumps(
+                    WSOutbound(type="error", payload={"message": str(exc)}).model_dump(mode="json")
+                ))
+                continue
+
+            # Process all segments in the batch concurrently
+            async def _process_and_send(segment):
+                t0 = time.perf_counter()
+                result = await process_segment(
+                    text=segment.text,
+                    content_hash=segment.content_hash,
+                    element_id=segment.element_id,
+                    platform=batch.platform,
+                )
+                if result:
+                    result.latency_ms = round((time.perf_counter() - t0) * 1000, 2)
+                    await manager.send(session_id, result.model_dump(mode="json"))
+
+            await asyncio.gather(*[_process_and_send(seg) for seg in batch.segments])
+
+    except WebSocketDisconnect:
+        manager.disconnect(session_id)
+    except Exception as exc:
+        log.error("ws.unexpected_error", session_id=session_id, error=str(exc))
+        manager.disconnect(session_id)
+
+
+# ============================================================================
+# SECTION 9 — REST endpoints
+# ============================================================================
+
+@app.get("/health")
+async def health():
+    try:
+        r = await get_redis()
+        redis_ok = await r.ping()
+    except Exception:
+        redis_ok = False
+    return {
+        "status": "ok",
+        "redis": redis_ok,
+        "demo_mode": settings.demo_mode,
+        "version": "1.0.0",
+    }
+
+
+@app.get("/metrics")
+async def metrics():
+    try:
+        r = await get_redis()
+        cached_verdicts = await r.dbsize()
+    except Exception:
+        cached_verdicts = 0
+    return {
+        "active_connections": len(manager.active),
+        "cached_verdicts": cached_verdicts,
+    }
+
+
+@app.get("/", response_class=HTMLResponse)
+async def demo_ui():
+    """Serves the interactive demo UI at the root path (HuggingFace Spaces landing page)."""
+    ui_path = os.path.join(os.path.dirname(__file__), "static", "index.html")
+    if os.path.exists(ui_path):
+        with open(ui_path) as f:
+            return HTMLResponse(f.read())
+    return HTMLResponse(
+        "<h1>Fact Intelligence API</h1>"
+        "<p>Connect via WebSocket at <code>/ws/{session_id}</code></p>"
+    )
+
+
+# ============================================================================
+# SECTION 10 — __main__ block (python app.py)
+# ============================================================================
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app:app",
+        host="0.0.0.0",
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+        access_log=False,
+        ws_ping_interval=20,
+        ws_ping_timeout=60,
+    )

backend/core/config.py

@@ -0,0 +1,98 @@
+"""
+core/config.py — Centralized settings via pydantic-settings.
+All values read from environment variables (set in HF Spaces secrets).
+"""
+
+from enum import Enum
+from functools import lru_cache
+
+from pydantic import Field, computed_field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class HighlightColor(str, Enum):
+    GREEN = "green"    # Fact-checked, widely corroborated
+    YELLOW = "yellow"  # Breaking / unverified / weak signal
+    RED = "red"        # Debunked, active community note
+    PURPLE = "purple"  # LLM hallucination detected
+
+
+class Platform(str, Enum):
+    TWITTER = "twitter"
+    INSTAGRAM = "instagram"
+    YOUTUBE = "youtube"
+    CHATGPT = "chatgpt"
+    CLAUDE = "claude"
+    GEMINI = "gemini"
+    NEWS = "news"
+    UNKNOWN = "unknown"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # LLM API keys
+    groq_api_key: str = Field(default="", alias="GROQ_API_KEY")
+    x_bearer_token: str = Field(default="", alias="X_BEARER_TOKEN")
+
+    # Infrastructure
+    qdrant_host: str = Field(default="localhost", alias="QDRANT_HOST")
+    qdrant_port: int = Field(default=6333, alias="QDRANT_PORT")
+    memgraph_host: str = Field(default="localhost", alias="MEMGRAPH_HOST")
+    memgraph_port: int = Field(default=7687, alias="MEMGRAPH_PORT")
+    memgraph_password: str = Field(default="memgraph123", alias="MEMGRAPH_PASSWORD")
+    redpanda_brokers: str = Field(default="localhost:9092", alias="REDPANDA_BROKERS")
+    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")
+
+    # App
+    port: int = Field(default=7860, alias="PORT")
+    log_level: str = Field(default="INFO", alias="LOG_LEVEL")
+    demo_mode: bool = Field(default=False, alias="DEMO_MODE")
+
+    # Model identifiers for LiteLLM routing
+    gatekeeper_model: str = "groq/llama3-8b-8192"
+    misinformation_model: str = "groq/mixtral-8x7b-32768"
+    hallucination_model: str = "groq/llama3-70b-8192"  # Free via Groq — replaces Claude Haiku
+
+    # Gatekeeper latency SLO: p95 < 120ms
+    gatekeeper_timeout_ms: int = 120
+
+    # Cache TTLs (seconds)
+    cache_ttl_green_red: int = 21_600   # 6 hours
+    cache_ttl_yellow: int = 900          # 15 minutes
+    # Purple: no cache — hallucination checks are context-specific
+
+    # RAG retrieval
+    qdrant_collection: str = "claims"
+    qdrant_ef: int = 128        # HNSW ef parameter — higher = more accurate, slower
+    qdrant_top_k: int = 8       # nearest neighbors to retrieve
+    evidence_window_hours: int = 72  # only retrieve evidence newer than 72h
+
+    # Minimum text length for analysis (words)
+    min_word_count: int = 12
+
+    @computed_field
+    @property
+    def has_groq(self) -> bool:
+        return bool(self.groq_api_key)
+
+    @computed_field
+    @property
+    def has_hallucination_llm(self) -> bool:
+        # Hallucination agent uses Groq llama3-70b (free) — same key as gatekeeper
+        return bool(self.groq_api_key)
+
+    @computed_field
+    @property
+    def has_x_api(self) -> bool:
+        return bool(self.x_bearer_token)
+
+    @computed_field
+    @property
+    def broker_list(self) -> list[str]:
+        return self.redpanda_brokers.split(",")
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/core/db_init.py

@@ -0,0 +1,143 @@
+"""
+core/db_init.py — Initialize Qdrant collection and Memgraph graph schema.
+
+Run once on startup (called from main.py lifespan) or manually:
+  uv run python -m core.db_init
+
+Memgraph graph schema:
+  (Author {handle, verified, account_type})
+    -[:REPORTED {timestamp}]->
+  (Claim {text, embedding_id, hash})
+    <-[:CORROBORATED_BY {confidence}]-
+  (Source {url, domain, bias_rating})
+    -[:HAS_NOTE]->
+  (CommunityNote {text, active, created_at})
+
+This schema supports:
+  - Trust score computation (Author.verified, Source count, CommunityNote presence)
+  - Claim deduplication by hash
+  - Source credibility tracking (bias_rating from Media Bias/Fact Check)
+"""
+
+import asyncio
+
+import structlog
+from neo4j import AsyncGraphDatabase
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import Distance, PayloadSchemaType, VectorParams
+
+from core.config import get_settings
+
+log = structlog.get_logger(__name__)
+
+
+async def init_qdrant(settings=None) -> None:
+    """
+    Create the Qdrant 'claims' collection if it doesn't exist.
+    BGE-M3 outputs 1024-dimensional dense vectors.
+    HNSW index created automatically by Qdrant on collection creation.
+    """
+    cfg = settings or get_settings()
+    client = AsyncQdrantClient(host=cfg.qdrant_host, port=cfg.qdrant_port)
+
+    try:
+        collections = await client.get_collections()
+        existing = {c.name for c in collections.collections}
+
+        if cfg.qdrant_collection not in existing:
+            await client.create_collection(
+                collection_name=cfg.qdrant_collection,
+                vectors_config=VectorParams(
+                    size=1024,           # BGE-M3 output dimension
+                    distance=Distance.COSINE,
+                ),
+            )
+            log.info("qdrant.collection.created", name=cfg.qdrant_collection)
+
+            # Payload indexes for fast filtering
+            for field, schema in [
+                ("ingested_at_ts", PayloadSchemaType.FLOAT),
+                ("platform", PayloadSchemaType.KEYWORD),
+                ("content_hash", PayloadSchemaType.KEYWORD),
+                ("author_handle", PayloadSchemaType.KEYWORD),
+            ]:
+                await client.create_payload_index(
+                    collection_name=cfg.qdrant_collection,
+                    field_name=field,
+                    field_schema=schema,
+                )
+                log.debug("qdrant.index.created", field=field)
+        else:
+            log.info("qdrant.collection.exists", name=cfg.qdrant_collection)
+
+    finally:
+        await client.close()
+
+
+async def init_memgraph(settings=None) -> None:
+    """
+    Create Memgraph constraints and indexes for the trust graph schema.
+    Memgraph is in-memory — indexes are re-created on restart (data too, unless persistence enabled).
+    """
+    cfg = settings or get_settings()
+    driver = AsyncGraphDatabase.driver(
+        f"bolt://{cfg.memgraph_host}:{cfg.memgraph_port}",
+        auth=("", cfg.memgraph_password),
+        encrypted=False,
+    )
+
+    schema_queries = [
+        # Uniqueness constraints (also create indexes automatically)
+        "CREATE CONSTRAINT ON (a:Author) ASSERT a.handle IS UNIQUE;",
+        "CREATE CONSTRAINT ON (c:Claim) ASSERT c.hash IS UNIQUE;",
+        "CREATE CONSTRAINT ON (s:Source) ASSERT s.url IS UNIQUE;",
+
+        # Additional indexes for traversal performance
+        "CREATE INDEX ON :Author(verified);",
+        "CREATE INDEX ON :Author(account_type);",
+        "CREATE INDEX ON :CommunityNote(active);",
+
+        # Seed a few known authoritative sources with high trust
+        """
+        MERGE (s:Source {url: 'https://reuters.com', domain: 'reuters.com'})
+        SET s.bias_rating = 'center', s.trust_tier = 'tier1';
+        """,
+        """
+        MERGE (s:Source {url: 'https://apnews.com', domain: 'apnews.com'})
+        SET s.bias_rating = 'center', s.trust_tier = 'tier1';
+        """,
+        """
+        MERGE (s:Source {url: 'https://who.int', domain: 'who.int'})
+        SET s.bias_rating = 'center', s.trust_tier = 'government';
+        """,
+        """
+        MERGE (s:Source {url: 'https://cdc.gov', domain: 'cdc.gov'})
+        SET s.bias_rating = 'center', s.trust_tier = 'government';
+        """,
+    ]
+
+    async with driver.session() as session:
+        for query in schema_queries:
+            try:
+                await session.run(query)
+            except Exception as exc:
+                # Constraints/indexes may already exist — not an error
+                if "already exists" not in str(exc).lower():
+                    log.warning("memgraph.schema.warn", query=query[:60], error=str(exc))
+
+    await driver.close()
+    log.info("memgraph.schema.initialized")
+
+
+async def init_all(settings=None) -> None:
+    """Initialize both Qdrant and Memgraph. Called from FastAPI lifespan."""
+    cfg = settings or get_settings()
+    await asyncio.gather(
+        init_qdrant(cfg),
+        init_memgraph(cfg),
+    )
+    log.info("db.init.complete")
+
+
+if __name__ == "__main__":
+    asyncio.run(init_all())

backend/core/logging.py

@@ -0,0 +1,69 @@
+"""
+core/logging.py — Structured logging setup using structlog + rich.
+
+structlog provides machine-readable JSON in production and
+colorized human-readable output in development, with zero config change.
+
+Usage:
+  import structlog
+  log = structlog.get_logger(__name__)
+  log.info("event.name", key="value", latency_ms=42.1)
+"""
+
+import logging
+import sys
+
+import structlog
+
+
+def configure_logging(log_level: str = "INFO", json_output: bool = False) -> None:
+    """
+    Configure structlog for the application.
+
+    In production (json_output=True): Outputs newline-delimited JSON —
+    compatible with Datadog, Grafana Loki, AWS CloudWatch, etc.
+
+    In development (json_output=False): Outputs colorized, human-readable
+    logs using rich ConsoleRenderer.
+    """
+    shared_processors = [
+        # Add log level as a field
+        structlog.stdlib.add_log_level,
+        # Add logger name
+        structlog.stdlib.add_logger_name,
+        # Add timestamp in ISO 8601
+        structlog.processors.TimeStamper(fmt="iso"),
+        # Render exceptions as structured dicts
+        structlog.processors.format_exc_info,
+        # Render stack info
+        structlog.processors.StackInfoRenderer(),
+    ]
+
+    if json_output:
+        renderer = structlog.processors.JSONRenderer()
+    else:
+        renderer = structlog.dev.ConsoleRenderer(colors=True, exception_formatter=structlog.dev.plain_traceback)
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            # Final renderer must be last
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            logging.getLevelName(log_level.upper())
+        ),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+
+    # Also configure stdlib logging to route through structlog
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stdout,
+        level=logging.getLevelName(log_level.upper()),
+    )
+    # Silence noisy libraries
+    for lib in ["httpx", "httpcore", "aiokafka", "neo4j", "qdrant_client", "uvicorn.access"]:
+        logging.getLogger(lib).setLevel(logging.WARNING)

backend/core/models.py

@@ -0,0 +1,197 @@
+"""
+core/models.py — Pydantic v2 models for the entire pipeline.
+
+All models use strict typing with no implicit coercion, leveraging
+Pydantic v2's Rust-backed validation for maximum throughput.
+"""
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from core.config import HighlightColor, Platform
+
+
+# ---------------------------------------------------------------------------
+# Inbound — what the browser extension sends us over WebSocket
+# ---------------------------------------------------------------------------
+
+class TextBatch(BaseModel):
+    """
+    A deduplicated batch of text segments flushed from the extension's
+    ring buffer every 1200ms. Each segment carries its own xxhash for
+    upstream deduplication and cache lookup.
+    """
+    session_id: str
+    platform: Platform
+    segments: list["TextSegment"]
+    sent_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class TextSegment(BaseModel):
+    content_hash: str   # xxhash64 hex — used as Redis cache key
+    text: str
+    element_id: str     # DOM node ID from the extension for highlight targeting
+    word_count: int
+
+    @field_validator("word_count")
+    @classmethod
+    def must_meet_minimum(cls, v: int) -> int:
+        if v < 12:
+            raise ValueError("Segments shorter than 12 words must be filtered client-side")
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Gatekeeper output
+# ---------------------------------------------------------------------------
+
+class GatekeeperResult(BaseModel):
+    """
+    Groq llama3-8b-8192 classifies each claim as fact or noise.
+    Structured JSON output — parsed with model_validate_json(), no try-except.
+    """
+    label: str   # "fact" | "noise"
+    reason: str  # one-sentence reasoning for the classification
+    confidence: float = Field(ge=0.0, le=1.0)
+
+    @field_validator("label")
+    @classmethod
+    def valid_label(cls, v: str) -> str:
+        if v not in {"fact", "noise"}:
+            raise ValueError(f"Label must be 'fact' or 'noise', got '{v}'")
+        return v
+
+
+# ---------------------------------------------------------------------------
+# RAG pipeline output
+# ---------------------------------------------------------------------------
+
+class EvidenceChunk(BaseModel):
+    """A retrieved evidence chunk from Qdrant."""
+    chunk_id: str
+    text: str
+    source_url: str
+    domain: str
+    score: float = Field(ge=0.0, le=1.0)   # cosine similarity
+    ingested_at: datetime
+    bias_rating: str | None = None
+
+
+class TrustScore(BaseModel):
+    """
+    Computed from the Memgraph trust graph traversal.
+    Algorithm: start 0.5, +0.3 verified official, +0.05/source (max 0.25),
+    -0.4 if Community Note active. Clamped to [0.0, 1.0].
+    """
+    score: float = Field(ge=0.0, le=1.0)
+    author_verified: bool
+    corroborating_sources: int
+    has_community_note: bool
+    community_note_text: str | None = None
+
+
+class RAGResult(BaseModel):
+    evidence: list[EvidenceChunk]
+    trust: TrustScore
+
+
+# ---------------------------------------------------------------------------
+# Grok/X sensor output
+# ---------------------------------------------------------------------------
+
+class GrokSensorResult(BaseModel):
+    velocity: int           # 7-day tweet volume for core keywords
+    community_note: bool
+    note_text: str | None = None
+    is_mock: bool = False   # True when X API key is absent
+
+
+# ---------------------------------------------------------------------------
+# Final analysis result — sent back to extension over WebSocket
+# ---------------------------------------------------------------------------
+
+class SourceRef(BaseModel):
+    url: str
+    domain: str
+    favicon_url: str
+    snippet: str
+
+
+class AnalysisResult(BaseModel):
+    """
+    The final enriched verdict returned to the browser extension.
+    The extension uses color + element_id to apply highlight + hover card.
+    """
+    request_id: UUID = Field(default_factory=uuid4)
+    element_id: str             # mirrors TextSegment.element_id for DOM targeting
+    content_hash: str
+    platform: Platform
+
+    # Verdict
+    color: HighlightColor
+    confidence: int = Field(ge=0, le=100)
+    verdict_label: str          # human-readable summary e.g. "Debunked by Reuters"
+    explanation: str            # full explanation string for hover card
+
+    # Top 3 sources shown in hover card
+    sources: list[SourceRef] = Field(max_length=3)
+
+    # Debug / provenance metadata
+    gatekeeper_label: str
+    trust_score: float
+    velocity: int
+    has_community_note: bool
+    latency_ms: float           # total pipeline latency for observability
+    cached: bool = False
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+
+# ---------------------------------------------------------------------------
+# WebSocket protocol messages
+# ---------------------------------------------------------------------------
+
+class WSMessageType(str):
+    BATCH = "batch"
+    RESULT = "result"
+    ERROR = "error"
+    PING = "ping"
+    PONG = "pong"
+    STATUS = "status"
+
+
+class WSInbound(BaseModel):
+    type: str
+    payload: dict[str, Any] | None = None
+
+
+class WSOutbound(BaseModel):
+    type: str
+    payload: Any
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+
+# ---------------------------------------------------------------------------
+# Kafka/Redpanda event envelope
+# ---------------------------------------------------------------------------
+
+class IngestionEvent(BaseModel):
+    """
+    Envelope for all three Redpanda topics (twitter, instagram, youtube).
+    Producers wrap their platform-specific data in this common schema.
+    """
+    event_id: str = Field(default_factory=lambda: str(uuid4()))
+    platform: Platform
+    content_hash: str
+    text: str
+    author_handle: str | None = None
+    author_verified: bool = False
+    source_url: str | None = None
+    ingested_at: datetime = Field(default_factory=datetime.utcnow)
+
+    @model_validator(mode="after")
+    def strip_whitespace(self) -> "IngestionEvent":
+        self.text = self.text.strip()
+        return self

backend/gatekeeper.py

@@ -0,0 +1,133 @@
+"""
+gatekeeper.py — Groq-powered edge router.
+
+Every incoming text batch hits this first. The Groq API with llama3-8b-8192
+gives us 800+ tokens/second inference, sub-100ms p95 latency, no GPU needed.
+
+If the classifier returns "noise" (opinion, meme, rhetoric, social noise),
+the request is dropped immediately — no downstream pipeline costs incurred.
+
+SLO: p95 < 120ms end-to-end, measured at the FastAPI WebSocket handler.
+"""
+
+import time
+
+import structlog
+from groq import AsyncGroq
+from pydantic import ValidationError
+
+from core.config import Settings, get_settings
+from core.models import GatekeeperResult
+
+log = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Strict JSON schema prompt — forces the model to output parseable JSON.
+# Pydantic v2's model_validate_json() parses this without a try-except
+# because if validation fails we WANT the exception to surface.
+# ---------------------------------------------------------------------------
+
+GATEKEEPER_SYSTEM = """You are a claim classifier. Analyze the given text and output ONLY valid JSON.
+
+Output schema (strict — no extra keys, no markdown, no preamble):
+{
+  "label": "fact" | "noise",
+  "reason": "<one concise sentence>",
+  "confidence": <float 0.0–1.0>
+}
+
+Classify as "fact" if the text contains a falsifiable factual claim — a statement
+about the real world that could be verified or refuted with evidence.
+
+Classify as "noise" if the text is:
+- A personal opinion or sentiment ("I think...", "I believe...")
+- Rhetorical question
+- Meme, humor, sarcasm, or social commentary without factual claims
+- Pure emotional reaction ("this is amazing!", "so sad")
+- Call-to-action without factual content
+- Filler text or social pleasantries
+
+Be conservative: when in doubt, label "fact" to avoid false negatives."""
+
+GATEKEEPER_USER_TMPL = 'Classify this text: "{text}"'
+
+
+async def classify_claim(text: str, settings: Settings | None = None) -> GatekeeperResult:
+    """
+    Classify whether `text` contains a falsifiable factual claim.
+
+    Returns GatekeeperResult with label="fact"|"noise".
+    Raises on timeout (>120ms) or model failure — caller handles fallback.
+
+    In DEMO_MODE (no GROQ_API_KEY), uses a simple heuristic classifier
+    so the system runs end-to-end without any API keys.
+    """
+    cfg = settings or get_settings()
+    t0 = time.perf_counter()
+
+    if cfg.demo_mode or not cfg.has_groq:
+        result = _heuristic_classify(text)
+        log.debug("gatekeeper.heuristic", label=result.label, latency_ms=round((time.perf_counter() - t0) * 1000, 2))
+        return result
+
+    client = AsyncGroq(api_key=cfg.groq_api_key)
+
+    # Use json_object response format — Groq enforces valid JSON output
+    response = await client.chat.completions.create(
+        model="llama3-8b-8192",
+        messages=[
+            {"role": "system", "content": GATEKEEPER_SYSTEM},
+            {"role": "user", "content": GATEKEEPER_USER_TMPL.format(text=text[:800])},
+        ],
+        response_format={"type": "json_object"},
+        temperature=0.0,    # Deterministic classification
+        max_tokens=120,     # JSON output is short — cap tokens to reduce latency
+        timeout=0.115,      # 115ms hard timeout preserves the 120ms p95 SLO
+    )
+
+    latency_ms = round((time.perf_counter() - t0) * 1000, 2)
+    raw_json = response.choices[0].message.content or "{}"
+
+    # model_validate_json() uses Pydantic v2's Rust validator — no try-except
+    # needed for the happy path; ValidationError propagates to caller.
+    result = GatekeeperResult.model_validate_json(raw_json)
+
+    log.info(
+        "gatekeeper.groq",
+        label=result.label,
+        confidence=result.confidence,
+        latency_ms=latency_ms,
+        tokens=response.usage.total_tokens if response.usage else None,
+    )
+    return result
+
+
+def _heuristic_classify(text: str) -> GatekeeperResult:
+    """
+    Fallback classifier when GROQ_API_KEY is absent (DEMO_MODE=true).
+    Uses simple lexical heuristics — not production-grade, but sufficient
+    for demonstrating the full pipeline without API credentials.
+    """
+    text_lower = text.lower()
+
+    noise_indicators = [
+        text_lower.startswith(("i think", "i believe", "i feel", "imo", "imho")),
+        text_lower.endswith("?") and len(text.split()) < 15,
+        any(w in text_lower for w in ["lol", "lmao", "omg", "wtf", "smh", "🤣", "😂"]),
+        all(w in text_lower for w in ["love", "hate"]) and "because" not in text_lower,
+    ]
+
+    if any(noise_indicators):
+        return GatekeeperResult(label="noise", reason="Heuristic: opinion/sentiment pattern detected", confidence=0.75)
+
+    fact_indicators = [
+        any(c.isdigit() for c in text),     # Contains numbers → likely factual claim
+        any(w in text_lower for w in ["percent", "%", "million", "billion", "study", "report", "according"]),
+        len(text.split()) > 20,              # Longer sentences tend to be claims
+    ]
+
+    if any(fact_indicators):
+        return GatekeeperResult(label="fact", reason="Heuristic: numeric/evidential language detected", confidence=0.65)
+
+    # Default: treat as fact (conservative — avoid false negatives)
+    return GatekeeperResult(label="fact", reason="Heuristic: no clear noise pattern, defaulting to fact", confidence=0.5)

backend/grok_sensor.py

@@ -0,0 +1,183 @@
+"""
+grok_sensor.py — Async X API v2 + Community Notes integration.
+
+Queries two signals for any claim:
+  1. 7-day tweet velocity: how fast is this claim spreading?
+     High velocity + no corroboration = yellow flag
+  2. Community Notes: has the crowd-sourced fact-check system flagged it?
+     Active note = strong red signal (-0.4 in trust scoring)
+
+Full mock fallback when X_BEARER_TOKEN is absent — the system runs
+end-to-end in demo mode without any external API credentials.
+"""
+
+import hashlib
+import random
+from datetime import datetime, timedelta, timezone
+
+import httpx
+import structlog
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from core.config import Settings, get_settings
+from core.models import GrokSensorResult
+
+log = structlog.get_logger(__name__)
+
+X_API_BASE = "https://api.twitter.com/2"
+COMMUNITY_NOTES_BASE = "https://twitter.com/i/birdwatch/n"  # Unofficial — use search API workaround
+
+# ---------------------------------------------------------------------------
+# X API v2 search
+# ---------------------------------------------------------------------------
+
+@retry(
+    retry=retry_if_exception_type(httpx.HTTPStatusError),
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=0.5, min=0.1, max=2.0),
+)
+async def _search_x_api(query: str, bearer_token: str) -> int:
+    """
+    Search X API v2 for tweet count matching the query in the past 7 days.
+    Returns the total tweet count as a velocity signal.
+
+    Uses tenacity for exponential backoff on HTTP 429 (rate limit) responses.
+    """
+    params = {
+        "query": f"{query} -is:retweet lang:en",
+        "start_time": (datetime.now(timezone.utc) - timedelta(days=7)).isoformat(),
+        "granularity": "day",
+    }
+    headers = {"Authorization": f"Bearer {bearer_token}"}
+
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        resp = await client.get(
+            f"{X_API_BASE}/tweets/counts/recent",
+            params=params,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("meta", {}).get("total_tweet_count", 0)
+
+
+async def _check_community_notes(query_keywords: list[str], bearer_token: str) -> tuple[bool, str | None]:
+    """
+    Check for active Community Notes using the X API v2 search endpoint.
+    Community Notes are exposed as tweets from @CommunityNotes.
+
+    Returns (has_note: bool, note_text: str | None).
+    """
+    query = " ".join(query_keywords[:5])  # Use top-5 keywords for targeted search
+    params = {
+        "query": f"(from:CommunityNotes) ({query})",
+        "max_results": 5,
+        "tweet.fields": "text,created_at",
+        "start_time": (datetime.now(timezone.utc) - timedelta(days=30)).isoformat(),
+    }
+    headers = {"Authorization": f"Bearer {bearer_token}"}
+
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        resp = await client.get(
+            f"{X_API_BASE}/tweets/search/recent",
+            params=params,
+            headers=headers,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            tweets = data.get("data", [])
+            if tweets:
+                return True, tweets[0]["text"]
+    return False, None
+
+
+def _extract_keywords(text: str) -> list[str]:
+    """
+    Extract the most meaningful content words for query construction.
+    Strips stopwords; keeps nouns, numbers, proper nouns (heuristic: capitalized).
+    """
+    stopwords = {
+        "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did", "will", "would", "could",
+        "should", "may", "might", "shall", "can", "this", "that", "these",
+        "those", "i", "we", "you", "he", "she", "it", "they", "and", "or",
+        "but", "in", "on", "at", "to", "for", "of", "with", "by", "from",
+        "up", "as", "into", "through", "about", "after", "before",
+    }
+    words = [w.strip(".,!?;:\"'()[]") for w in text.split()]
+    return [w for w in words if w.lower() not in stopwords and len(w) > 3][:10]
+
+
+def _mock_sensor_result(claim_hash: str) -> GrokSensorResult:
+    """
+    Deterministic mock result derived from the claim hash.
+    Same hash always produces the same result — stable for testing.
+    """
+    seed = int(claim_hash[:8], 16) if all(c in "0123456789abcdef" for c in claim_hash[:8]) else hash(claim_hash)
+    rng = random.Random(seed)
+
+    velocity = rng.randint(0, 50_000)
+    has_note = rng.random() < 0.12  # ~12% chance of a community note (realistic)
+    note_text = (
+        "Community Note: This claim lacks context. The full data shows..."
+        if has_note
+        else None
+    )
+
+    return GrokSensorResult(
+        velocity=velocity,
+        community_note=has_note,
+        note_text=note_text,
+        is_mock=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public interface
+# ---------------------------------------------------------------------------
+
+async def query_grok_sensor(
+    claim_text: str,
+    claim_hash: str,
+    settings: Settings | None = None,
+) -> GrokSensorResult:
+    """
+    Main entry point: query X API for claim velocity and Community Notes.
+
+    Falls back to deterministic mock data when X_BEARER_TOKEN is absent.
+    The mock is seeded by claim_hash so results are consistent across calls.
+    """
+    cfg = settings or get_settings()
+
+    if cfg.demo_mode or not cfg.has_x_api:
+        result = _mock_sensor_result(claim_hash)
+        log.debug("grok_sensor.mock", velocity=result.velocity, has_note=result.community_note)
+        return result
+
+    keywords = _extract_keywords(claim_text)
+    query = " ".join(keywords[:5])
+
+    try:
+        velocity, (has_note, note_text) = await _search_x_api(query, cfg.x_bearer_token), (False, None)
+
+        # Only check community notes if velocity is nonzero (claim is circulating)
+        if velocity > 100:
+            has_note, note_text = await _check_community_notes(keywords, cfg.x_bearer_token)
+
+        result = GrokSensorResult(
+            velocity=velocity,
+            community_note=has_note,
+            note_text=note_text,
+            is_mock=False,
+        )
+        log.info("grok_sensor.live", velocity=velocity, has_note=has_note)
+        return result
+
+    except httpx.HTTPError as exc:
+        log.warning("grok_sensor.api_error", error=str(exc), fallback="mock")
+        return _mock_sensor_result(claim_hash)

backend/producers/producers.py

@@ -0,0 +1,338 @@
+"""
+producers/twitter_producer.py — Async Redpanda producer for X/Twitter mock data.
+
+Reads mock tweet data from a JSONL file and publishes to topic `raw.twitter`
+at 50 events/second. Redpanda's Kafka-compatible API means aiokafka works
+without any modifications.
+
+Why 50 eps for Twitter: Twitter is the highest-velocity source (most
+misinformation travels fastest on X), so it gets the highest throughput budget.
+"""
+
+import asyncio
+import json
+import os
+import time
+from pathlib import Path
+
+import structlog
+from aiokafka import AIOKafkaProducer
+from aiokafka.errors import KafkaConnectionError
+
+log = structlog.get_logger(__name__)
+BROKERS = os.environ.get("REDPANDA_BROKERS", "localhost:9092")
+TOPIC = "raw.twitter"
+TARGET_EPS = 50  # events per second
+
+
+# ---------------------------------------------------------------------------
+# Mock data (used when no JSONL file is provided)
+# ---------------------------------------------------------------------------
+
+MOCK_TWEETS = [
+    {"id": "t001", "text": "Scientists confirmed that 73% of peer-reviewed studies on mRNA vaccines show long-term immunity lasting over 18 months.", "author": "science_today", "verified": True, "account_type": "official_news"},
+    {"id": "t002", "text": "Breaking: The Federal Reserve has just raised interest rates by 75 basis points — the largest single hike since 1994.", "author": "reuters_econ", "verified": True, "account_type": "official_news"},
+    {"id": "t003", "text": "lol did you see that video? total propaganda 😂 wake up people", "author": "anon_user123", "verified": False, "account_type": "personal"},
+    {"id": "t004", "text": "The WHO confirmed 12 million cases of the new strain have been reported across 47 countries in the last 30 days.", "author": "who_official", "verified": True, "account_type": "government"},
+    {"id": "t005", "text": "According to newly declassified Pentagon documents, UFO encounters increased by 400% between 2020 and 2023.", "author": "ufo_truther", "verified": False, "account_type": "personal"},
+    {"id": "t006", "text": "Harvard researchers published data showing remote work productivity rose by 13% on average versus in-office.", "author": "harvard_biz", "verified": True, "account_type": "official_news"},
+    {"id": "t007", "text": "I just think the whole thing is suspicious. something doesn't add up here. do your own research!", "author": "skeptic_99", "verified": False, "account_type": "personal"},
+    {"id": "t008", "text": "EU parliament voted 483-141 to approve the AI Act, making it the world's first comprehensive artificial intelligence legislation.", "author": "eu_parliament", "verified": True, "account_type": "government"},
+    {"id": "t009", "text": "Elon Musk announced Tesla will manufacture 5 million vehicles in 2025, a 240% increase from 2023 production.", "author": "tech_insider", "verified": False, "account_type": "personal"},
+    {"id": "t010", "text": "Climate scientists at NOAA recorded the highest average ocean temperatures in 150 years of recorded history this August.", "author": "noaa_official", "verified": True, "account_type": "government"},
+] * 100   # Repeat for continuous stream
+
+
+async def produce_twitter(brokers: str = BROKERS, limit: int | None = None) -> None:
+    """
+    Async producer loop. Publishes tweets to `raw.twitter` at TARGET_EPS.
+    Runs indefinitely unless `limit` is set (useful for testing).
+    """
+    producer = AIOKafkaProducer(
+        bootstrap_servers=brokers,
+        value_serializer=lambda v: json.dumps(v).encode(),
+        compression_type="gzip",
+        max_batch_size=16384,
+    )
+
+    await producer.start()
+    log.info("producer.twitter.start", brokers=brokers, eps=TARGET_EPS)
+
+    interval = 1.0 / TARGET_EPS
+    count = 0
+
+    try:
+        for tweet in MOCK_TWEETS:
+            if limit and count >= limit:
+                break
+
+            envelope = {
+                "platform": "twitter",
+                "content_hash": _hash(tweet["text"]),
+                "text": tweet["text"],
+                "author_handle": tweet["author"],
+                "author_verified": tweet["verified"],
+                "source_url": f"https://x.com/{tweet['author']}/status/{tweet['id']}",
+                "ingested_at": time.time(),
+            }
+
+            await producer.send(TOPIC, value=envelope)
+            count += 1
+            await asyncio.sleep(interval)
+
+    finally:
+        await producer.stop()
+        log.info("producer.twitter.stop", total_sent=count)
+
+
+def _hash(text: str) -> str:
+    import xxhash
+    return xxhash.xxh64(text.encode()).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# instagram_producer.py (inline to keep file count reasonable)
+# ---------------------------------------------------------------------------
+
+INSTAGRAM_TOPIC = "raw.instagram"
+INSTAGRAM_EPS = 20
+
+MOCK_INSTAGRAM = [
+    {"id": "ig001", "text": "Just read that consuming 5 servings of ultra-processed foods per day increases cardiovascular disease risk by 62%.", "account": "nutritionista_real"},
+    {"id": "ig002", "text": "loving these golden hour pics 🌅 this place is absolutely magical!", "account": "travel_vibes_only"},
+    {"id": "ig003", "text": "NASA confirmed the Artemis III moon landing is scheduled for September 2026, marking humanity's return after 54 years.", "account": "space_news_daily"},
+    {"id": "ig004", "text": "Studies show social media use exceeding 3 hours daily correlates with a 48% higher rate of anxiety in adolescents aged 13-17.", "account": "mental_health_facts"},
+    {"id": "ig005", "text": "Can't believe this coffee shop! best latte I've had all year ☕✨", "account": "foodie_adventures"},
+    {"id": "ig006", "text": "A leaked document suggests Apple's Vision Pro 2 will feature a 70% thinner form factor and 14-hour battery life.", "account": "tech_leaks_xyz"},
+    {"id": "ig007", "text": "The Amazon rainforest lost 11,568 square kilometers to deforestation in 2023, a 22% increase from the previous year.", "account": "environmental_watch"},
+] * 50
+
+
+async def produce_instagram(brokers: str = BROKERS, limit: int | None = None) -> None:
+    producer = AIOKafkaProducer(
+        bootstrap_servers=brokers,
+        value_serializer=lambda v: json.dumps(v).encode(),
+        compression_type="gzip",
+    )
+    await producer.start()
+    log.info("producer.instagram.start", brokers=brokers, eps=INSTAGRAM_EPS)
+
+    interval = 1.0 / INSTAGRAM_EPS
+    count = 0
+
+    try:
+        for post in MOCK_INSTAGRAM:
+            if limit and count >= limit:
+                break
+
+            envelope = {
+                "platform": "instagram",
+                "content_hash": _hash(post["text"]),
+                "text": post["text"],
+                "author_handle": post["account"],
+                "author_verified": False,
+                "source_url": f"https://instagram.com/{post['account']}/p/{post['id']}",
+                "ingested_at": time.time(),
+            }
+
+            await producer.send(INSTAGRAM_TOPIC, value=envelope)
+            count += 1
+            await asyncio.sleep(interval)
+
+    finally:
+        await producer.stop()
+        log.info("producer.instagram.stop", total_sent=count)
+
+
+# ---------------------------------------------------------------------------
+# youtube_producer.py (inline)
+# ---------------------------------------------------------------------------
+
+YOUTUBE_TOPIC = "raw.youtube"
+YOUTUBE_EPS = 10
+
+MOCK_YOUTUBE_TRANSCRIPTS = [
+    {"id": "yt001", "text": "According to the study published in Nature Medicine, the experimental drug reduced tumor size by an average of 47% in stage three patients.", "channel": "MedicalFrontiers"},
+    {"id": "yt002", "text": "So basically what they're saying is that the economy grew by 2.4 percent in Q3, which is actually the highest quarterly growth since 2021.", "channel": "FinanceExplained"},
+    {"id": "yt003", "text": "I personally believe this is all connected, if you look at the patterns you can clearly see what's really happening behind the scenes.", "channel": "ConspiracyHub"},
+    {"id": "yt004", "text": "The International Energy Agency reports that renewable energy now accounts for 30% of global electricity generation, up from 26% in 2021.", "channel": "CleanEnergyNow"},
+    {"id": "yt005", "text": "GPT-5 was secretly trained on 100 trillion parameters, making it ten times larger than GPT-4, according to an anonymous OpenAI employee.", "channel": "AIInsiderNews"},
+    {"id": "yt006", "text": "The United Nations Population Fund projects global population will peak at 10.4 billion in the 2080s before beginning to decline.", "channel": "DemographicsWorld"},
+] * 30
+
+
+async def produce_youtube(brokers: str = BROKERS, limit: int | None = None) -> None:
+    producer = AIOKafkaProducer(
+        bootstrap_servers=brokers,
+        value_serializer=lambda v: json.dumps(v).encode(),
+        compression_type="gzip",
+    )
+    await producer.start()
+    log.info("producer.youtube.start", brokers=brokers, eps=YOUTUBE_EPS)
+
+    interval = 1.0 / YOUTUBE_EPS
+    count = 0
+
+    try:
+        for chunk in MOCK_YOUTUBE_TRANSCRIPTS:
+            if limit and count >= limit:
+                break
+
+            envelope = {
+                "platform": "youtube",
+                "content_hash": _hash(chunk["text"]),
+                "text": chunk["text"],
+                "author_handle": chunk["channel"],
+                "author_verified": False,
+                "source_url": f"https://youtube.com/watch?v={chunk['id']}",
+                "ingested_at": time.time(),
+            }
+
+            await producer.send(YOUTUBE_TOPIC, value=envelope)
+            count += 1
+            await asyncio.sleep(interval)
+
+    finally:
+        await producer.stop()
+        log.info("producer.youtube.stop", total_sent=count)
+
+
+# ---------------------------------------------------------------------------
+# Aggregated consumer — upserts into Qdrant + Memgraph
+# ---------------------------------------------------------------------------
+
+async def run_consumer(brokers: str = BROKERS) -> None:
+    """
+    Consumes all three topics, deduplicates by content_hash,
+    and upserts into Qdrant (vector index) and Memgraph (trust graph).
+    """
+    from aiokafka import AIOKafkaConsumer
+    import xxhash
+
+    seen_hashes: set[str] = set()
+
+    consumer = AIOKafkaConsumer(
+        "raw.twitter", "raw.instagram", "raw.youtube",
+        bootstrap_servers=brokers,
+        group_id="fact-intelligence-consumer",
+        value_deserializer=lambda v: json.loads(v.decode()),
+        auto_offset_reset="latest",
+    )
+
+    await consumer.start()
+    log.info("consumer.start", topics=["raw.twitter", "raw.instagram", "raw.youtube"])
+
+    try:
+        async for msg in consumer:
+            event = msg.value
+            h = event.get("content_hash", "")
+
+            if h in seen_hashes:
+                continue   # Client-side deduplication (ring buffer) + server-side
+            seen_hashes.add(h)
+
+            # Trim seen_hashes to avoid unbounded memory growth (LRU-style)
+            if len(seen_hashes) > 50_000:
+                seen_hashes = set(list(seen_hashes)[-25_000:])
+
+            log.debug("consumer.event", platform=event.get("platform"), hash=h[:8])
+
+            # Upsert into Qdrant + Memgraph (fire-and-forget, non-blocking)
+            asyncio.create_task(_upsert_event(event))
+
+    finally:
+        await consumer.stop()
+
+
+async def _upsert_event(event: dict) -> None:
+    """Embed and upsert a single event into Qdrant and Memgraph."""
+    try:
+        from rag_pipeline import embed_texts, get_qdrant
+        from core.config import get_settings
+        from qdrant_client.models import PointStruct
+        import uuid
+
+        cfg = get_settings()
+        text = event.get("text", "")
+        if not text:
+            return
+
+        # Embed and upsert into Qdrant
+        [vector] = await embed_texts([text])
+        client = await get_qdrant(cfg)
+
+        await client.upsert(
+            collection_name=cfg.qdrant_collection,
+            points=[
+                PointStruct(
+                    id=str(uuid.uuid4()),
+                    vector=vector,
+                    payload={
+                        "text": text,
+                        "source_url": event.get("source_url", ""),
+                        "domain": _extract_domain(event.get("source_url", "")),
+                        "platform": event.get("platform", ""),
+                        "content_hash": event.get("content_hash", ""),
+                        "ingested_at_ts": event.get("ingested_at", time.time()),
+                        "author_handle": event.get("author_handle", ""),
+                        "bias_rating": None,
+                    },
+                )
+            ],
+        )
+
+        # Upsert Author + Claim nodes into Memgraph
+        await _upsert_graph_node(event, cfg)
+
+    except Exception as exc:
+        log.error("consumer.upsert_error", error=str(exc))
+
+
+def _extract_domain(url: str) -> str:
+    try:
+        from urllib.parse import urlparse
+        return urlparse(url).netloc.lstrip("www.")
+    except Exception:
+        return ""
+
+
+async def _upsert_graph_node(event: dict, cfg) -> None:
+    """Create/update Author and Claim nodes in Memgraph."""
+    from neo4j import AsyncGraphDatabase
+
+    driver = AsyncGraphDatabase.driver(
+        f"bolt://{cfg.memgraph_host}:{cfg.memgraph_port}",
+        auth=("", cfg.memgraph_password),
+        encrypted=False,
+    )
+    async with driver.session() as session:
+        await session.run(
+            """
+            MERGE (a:Author {handle: $handle})
+            SET a.verified = $verified, a.account_type = $account_type
+            MERGE (c:Claim {hash: $hash})
+            SET c.text = $text
+            MERGE (a)-[:REPORTED {timestamp: $ts}]->(c)
+            """,
+            handle=event.get("author_handle", "unknown"),
+            verified=event.get("author_verified", False),
+            account_type=event.get("account_type", "personal"),
+            hash=event.get("content_hash", ""),
+            text=event.get("text", "")[:500],
+            ts=event.get("ingested_at", time.time()),
+        )
+    await driver.close()
+
+
+if __name__ == "__main__":
+    import sys
+
+    async def _run_all():
+        await asyncio.gather(
+            produce_twitter(),
+            produce_instagram(),
+            produce_youtube(),
+            run_consumer(),
+        )
+
+    asyncio.run(_run_all())

backend/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "omnichannel-fact-intelligence"
+version = "1.0.0"
+description = "Near-zero-latency omnichannel fact & hallucination intelligence backend"
+requires-python = ">=3.12"
+dependencies = [
+    # Web framework & async
+    "fastapi==0.115.5",
+    "uvicorn[standard]==0.32.1",
+    "websockets==13.1",
+    "httpx==0.27.2",
+
+    # Data validation
+    "pydantic==2.10.3",
+    "pydantic-settings==2.6.1",
+
+    # LLM abstraction — swap Groq ↔ GPT-4o ↔ local Ollama without code changes
+    "litellm==1.55.4",
+    "groq==0.13.0",
+
+    # Embeddings — BGE-M3, multilingual, CPU-native, completely free
+    "fastembed==0.4.2",
+
+    # Vector DB — Qdrant self-hosted, HNSW sub-ms ANN search
+    "qdrant-client==1.12.1",
+
+    # Graph DB — Memgraph Bolt driver (Cypher-compatible, same as Neo4j driver)
+    "neo4j==5.26.0",
+
+    # Message queue — Redpanda is Kafka-compatible, use aiokafka
+    "aiokafka==0.11.0",
+
+    # Orchestration — Prefect DAG flows replacing Celery
+    "prefect==3.1.6",
+
+    # Cache — Redis Stack (RedisJSON + RedisSearch)
+    "redis[hiredis]==5.2.1",
+
+    # Hashing — xxhash for sub-microsecond content deduplication
+    "xxhash==3.5.0",
+
+    # Observability
+    "structlog==24.4.0",
+    "rich==13.9.4",
+
+    # Utilities
+    "python-dotenv==1.0.1",
+    "tenacity==9.0.0",      # Exponential backoff for external API calls
+    "aiofiles==24.1.0",
+    "orjson==3.10.12",      # 2-3x faster JSON than stdlib
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.4",
+    "pytest-asyncio==0.24.0",
+    "pytest-httpx==0.32.0",
+    "ruff==0.8.3",
+    "mypy==1.13.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.24.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true

backend/rag_pipeline.py

@@ -0,0 +1,285 @@
+"""
+rag_pipeline.py — Retrieval-Augmented Generation truth pipeline.
+
+Three-stage process:
+  1. Embed the claim using BGE-M3 (FastEmbed, CPU-native, multilingual)
+  2. Search Qdrant for nearest evidence chunks (HNSW ef=128, top-8, 72h window)
+  3. Traverse the Memgraph trust graph to compute a trust score
+
+Why BGE-M3 over OpenAI embeddings:
+  - 100+ language support (OpenAI embeddings are English-biased)
+  - 1024-dimensional dense vectors with better factual recall on news content
+  - Runs on CPU — no GPU dependency on the server
+  - Completely free — no per-token cost
+  - Comparable or better performance on BEIR benchmarks vs text-embedding-3-small
+
+Why Qdrant over Pinecone:
+  - Self-hosted Docker — zero vendor lock-in, zero per-query cost
+  - HNSW index with configurable ef parameter for precision/recall trade-off
+  - Built-in payload filtering for recency constraints (no separate filter step)
+  - gRPC support for sub-millisecond latency on local network
+
+Why Memgraph over Neo4j:
+  - Fully in-memory — entire graph lives in RAM for <1ms traversal
+  - Cypher-compatible — same query language as Neo4j, zero migration cost
+  - Docker-deployable in one command
+"""
+
+import asyncio
+from concurrent.futures import ProcessPoolExecutor
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+import structlog
+from neo4j import AsyncGraphDatabase
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import (
+    Distance,
+    FieldCondition,
+    Filter,
+    MatchValue,
+    PayloadSchemaType,
+    Range,
+    SearchRequest,
+    VectorParams,
+)
+
+from core.config import Settings, get_settings
+from core.models import EvidenceChunk, RAGResult, TrustScore
+
+if TYPE_CHECKING:
+    from fastembed import TextEmbedding
+
+log = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Module-level singletons — initialized on first use, reused across requests
+# ---------------------------------------------------------------------------
+_embed_model: "TextEmbedding | None" = None
+_qdrant_client: AsyncQdrantClient | None = None
+_executor: ProcessPoolExecutor | None = None
+
+
+def _get_embedder() -> "TextEmbedding":
+    """Lazy-load the BGE-M3 model. First load downloads ~570MB, then cached."""
+    global _embed_model
+    if _embed_model is None:
+        from fastembed import TextEmbedding
+        log.info("rag.embedder.loading", model="BAAI/bge-m3")
+        _embed_model = TextEmbedding("BAAI/bge-m3")
+        log.info("rag.embedder.ready")
+    return _embed_model
+
+
+def _get_executor() -> ProcessPoolExecutor:
+    """Embedding is CPU-bound — run in a ProcessPoolExecutor to avoid blocking asyncio."""
+    global _executor
+    if _executor is None:
+        _executor = ProcessPoolExecutor(max_workers=2)
+    return _executor
+
+
+def _embed_sync(texts: list[str]) -> list[list[float]]:
+    """
+    CPU-bound embedding function executed in the process pool.
+    Must be a module-level function (not a method/lambda) for pickling.
+    """
+    model = _get_embedder()
+    return [v.tolist() for v in model.embed(texts)]
+
+
+async def embed_texts(texts: list[str]) -> list[list[float]]:
+    """Async wrapper: runs CPU-bound embedding in a separate process."""
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(_get_executor(), _embed_sync, texts)
+
+
+# ---------------------------------------------------------------------------
+# Qdrant client and collection bootstrap
+# ---------------------------------------------------------------------------
+
+async def get_qdrant(settings: Settings) -> AsyncQdrantClient:
+    global _qdrant_client
+    if _qdrant_client is None:
+        _qdrant_client = AsyncQdrantClient(host=settings.qdrant_host, port=settings.qdrant_port)
+        await _ensure_collection(_qdrant_client, settings)
+    return _qdrant_client
+
+
+async def _ensure_collection(client: AsyncQdrantClient, settings: Settings) -> None:
+    """
+    Idempotent collection creation. BGE-M3 outputs 1024-dimensional vectors.
+    HNSW is the default index in Qdrant — no explicit creation needed.
+    """
+    collections = await client.get_collections()
+    names = [c.name for c in collections.collections]
+
+    if settings.qdrant_collection not in names:
+        await client.create_collection(
+            collection_name=settings.qdrant_collection,
+            vectors_config=VectorParams(size=1024, distance=Distance.COSINE),
+        )
+        # Create payload index on ingested_at for fast recency filtering
+        await client.create_payload_index(
+            collection_name=settings.qdrant_collection,
+            field_name="ingested_at_ts",
+            field_schema=PayloadSchemaType.FLOAT,
+        )
+        log.info("qdrant.collection.created", name=settings.qdrant_collection)
+
+
+# ---------------------------------------------------------------------------
+# Memgraph trust graph
+# ---------------------------------------------------------------------------
+
+async def compute_trust_score(
+    claim_hash: str,
+    settings: Settings,
+) -> TrustScore:
+    """
+    Traverse the Memgraph trust graph to compute a claim's credibility score.
+
+    Graph schema:
+      (Author {handle, verified, account_type})
+        -[:REPORTED {timestamp}]->
+      (Claim {text, embedding_id, hash})
+        <-[:CORROBORATED_BY {confidence}]-
+      (Source {url, domain, bias_rating})
+
+    Scoring algorithm (start at 0.5, clamp to [0.0, 1.0]):
+      +0.30 if Author.verified AND account_type IN ['government', 'official_news']
+      +0.05 per corroborating Source node (max boost: +0.25, so cap at 5 sources)
+      -0.40 if any Source carries an active Community_Note relationship
+    """
+    driver = AsyncGraphDatabase.driver(
+        f"bolt://{settings.memgraph_host}:{settings.memgraph_port}",
+        auth=("", settings.memgraph_password),
+        encrypted=False,
+    )
+
+    async with driver.session() as session:
+        result = await session.run(
+            """
+            OPTIONAL MATCH (a:Author)-[:REPORTED]->(c:Claim {hash: $hash})
+            OPTIONAL MATCH (s:Source)-[:CORROBORATED_BY]->(c)
+            OPTIONAL MATCH (s)-[:HAS_NOTE]->(n:CommunityNote {active: true})
+            RETURN
+              a.verified AS verified,
+              a.account_type AS account_type,
+              COUNT(DISTINCT s) AS source_count,
+              COUNT(DISTINCT n) AS note_count,
+              COLLECT(DISTINCT n.text)[0] AS note_text
+            """,
+            hash=claim_hash,
+        )
+        row = await result.single()
+
+    await driver.close()
+
+    if row is None:
+        # Claim not yet in graph — return neutral score
+        return TrustScore(
+            score=0.5,
+            author_verified=False,
+            corroborating_sources=0,
+            has_community_note=False,
+        )
+
+    verified: bool = bool(row["verified"])
+    account_type: str | None = row["account_type"]
+    source_count: int = int(row["source_count"] or 0)
+    note_count: int = int(row["note_count"] or 0)
+    note_text: str | None = row["note_text"]
+
+    # --- Scoring algorithm ---
+    score = 0.5
+
+    if verified and account_type in ("government", "official_news"):
+        score += 0.30   # Strong verified official boost
+
+    source_boost = min(source_count * 0.05, 0.25)  # Cap at 5 sources × 0.05
+    score += source_boost
+
+    has_note = note_count > 0
+    if has_note:
+        score -= 0.40   # Active Community Note is a strong negative signal
+
+    score = max(0.0, min(1.0, score))  # Clamp to [0.0, 1.0]
+
+    return TrustScore(
+        score=round(score, 4),
+        author_verified=verified,
+        corroborating_sources=source_count,
+        has_community_note=has_note,
+        community_note_text=note_text,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main RAG pipeline entry point
+# ---------------------------------------------------------------------------
+
+async def run_rag_pipeline(
+    claim_text: str,
+    claim_hash: str,
+    settings: Settings | None = None,
+) -> RAGResult:
+    """
+    Full RAG pipeline: embed → ANN search with recency filter → trust traversal.
+
+    Returns RAGResult with top-k evidence chunks and computed trust score,
+    both of which feed into the multi-agent evaluation layer (agents.py).
+    """
+    cfg = settings or get_settings()
+
+    # Run embedding and trust score concurrently — they're independent
+    embed_task = asyncio.create_task(embed_texts([claim_text]))
+    trust_task = asyncio.create_task(compute_trust_score(claim_hash, cfg))
+
+    [claim_vector], trust = await asyncio.gather(embed_task, trust_task)
+
+    # Recency filter: only retrieve evidence ingested in the last 72 hours
+    # Uses Qdrant's payload filter on the ingested_at_ts float field (Unix timestamp)
+    cutoff_ts = (datetime.now(timezone.utc) - timedelta(hours=cfg.evidence_window_hours)).timestamp()
+
+    qdrant = await get_qdrant(cfg)
+
+    search_results = await qdrant.search(
+        collection_name=cfg.qdrant_collection,
+        query_vector=claim_vector,
+        limit=cfg.qdrant_top_k,
+        with_payload=True,
+        search_params={"hnsw_ef": cfg.qdrant_ef},
+        query_filter=Filter(
+            must=[
+                FieldCondition(
+                    key="ingested_at_ts",
+                    range=Range(gte=cutoff_ts),
+                )
+            ]
+        ),
+    )
+
+    evidence = [
+        EvidenceChunk(
+            chunk_id=str(hit.id),
+            text=hit.payload.get("text", ""),
+            source_url=hit.payload.get("source_url", ""),
+            domain=hit.payload.get("domain", ""),
+            score=hit.score,
+            ingested_at=datetime.fromtimestamp(
+                hit.payload.get("ingested_at_ts", 0), tz=timezone.utc
+            ),
+            bias_rating=hit.payload.get("bias_rating"),
+        )
+        for hit in search_results
+    ]
+
+    log.info(
+        "rag.pipeline.complete",
+        evidence_count=len(evidence),
+        trust_score=trust.score,
+        claim_hash=claim_hash[:8],
+    )
+
+    return RAGResult(evidence=evidence, trust=trust)

backend/static/index.html

@@ -0,0 +1,783 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Fact & Hallucination Intelligence System</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=DM+Sans:wght@300;400;500;700&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg: #070b0f;
+    --surface: #0d1117;
+    --surface2: #161b22;
+    --border: #21262d;
+    --text: #e6edf3;
+    --text-muted: #7d8590;
+    --green: #22c55e;
+    --green-glow: rgba(34,197,94,0.15);
+    --yellow: #eab308;
+    --yellow-glow: rgba(234,179,8,0.15);
+    --red: #ef4444;
+    --red-glow: rgba(239,68,68,0.15);
+    --purple: #a855f7;
+    --purple-glow: rgba(168,85,247,0.15);
+    --accent: #58a6ff;
+    --mono: 'Space Mono', monospace;
+    --sans: 'DM Sans', sans-serif;
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: var(--sans);
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    position: relative;
+    overflow-x: hidden;
+  }
+
+  /* Grid background */
+  body::before {
+    content: '';
+    position: fixed;
+    inset: 0;
+    background-image:
+      linear-gradient(rgba(88,166,255,0.03) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(88,166,255,0.03) 1px, transparent 1px);
+    background-size: 40px 40px;
+    pointer-events: none;
+    z-index: 0;
+  }
+
+  /* Radial glow */
+  body::after {
+    content: '';
+    position: fixed;
+    top: -20%;
+    left: 50%;
+    transform: translateX(-50%);
+    width: 80vw;
+    height: 60vh;
+    background: radial-gradient(ellipse, rgba(88,166,255,0.06) 0%, transparent 70%);
+    pointer-events: none;
+    z-index: 0;
+  }
+
+  .container {
+    position: relative;
+    z-index: 1;
+    max-width: 900px;
+    margin: 0 auto;
+    padding: 48px 24px 80px;
+    width: 100%;
+  }
+
+  /* Header */
+  header {
+    text-align: center;
+    margin-bottom: 56px;
+  }
+
+  .logo-row {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    margin-bottom: 16px;
+  }
+
+  .logo-icon {
+    width: 40px;
+    height: 40px;
+    border: 1px solid var(--accent);
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--accent);
+    font-size: 20px;
+    box-shadow: 0 0 20px rgba(88,166,255,0.2);
+  }
+
+  h1 {
+    font-family: var(--mono);
+    font-size: clamp(18px, 3vw, 26px);
+    font-weight: 700;
+    letter-spacing: -0.5px;
+    color: var(--text);
+  }
+
+  .tagline {
+    font-size: 14px;
+    color: var(--text-muted);
+    font-family: var(--mono);
+    letter-spacing: 0.5px;
+    margin-top: 8px;
+  }
+
+  /* Status bar */
+  .status-bar {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 16px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text-muted);
+    margin-bottom: 32px;
+    width: fit-content;
+    margin-left: auto;
+    margin-right: auto;
+  }
+
+  .status-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: #555;
+    transition: background 0.3s;
+  }
+  .status-dot.connected { background: var(--green); box-shadow: 0 0 8px var(--green); animation: pulse 2s infinite; }
+  .status-dot.connecting { background: var(--yellow); animation: pulse 0.8s infinite; }
+  .status-dot.error { background: var(--red); }
+
+  @keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.4; }
+  }
+
+  /* Input area */
+  .analysis-card {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 28px;
+    margin-bottom: 24px;
+  }
+
+  .card-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text-muted);
+    letter-spacing: 1.5px;
+    text-transform: uppercase;
+    margin-bottom: 12px;
+  }
+
+  .platform-row {
+    display: flex;
+    gap: 8px;
+    margin-bottom: 16px;
+    flex-wrap: wrap;
+  }
+
+  .platform-btn {
+    padding: 6px 14px;
+    border: 1px solid var(--border);
+    border-radius: 20px;
+    background: transparent;
+    color: var(--text-muted);
+    font-family: var(--mono);
+    font-size: 11px;
+    cursor: pointer;
+    transition: all 0.2s;
+    letter-spacing: 0.5px;
+  }
+  .platform-btn:hover { border-color: var(--accent); color: var(--accent); }
+  .platform-btn.active {
+    border-color: var(--accent);
+    background: rgba(88,166,255,0.1);
+    color: var(--accent);
+  }
+
+  textarea {
+    width: 100%;
+    min-height: 120px;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--text);
+    font-family: var(--sans);
+    font-size: 15px;
+    line-height: 1.6;
+    padding: 16px;
+    resize: vertical;
+    outline: none;
+    transition: border-color 0.2s;
+  }
+  textarea:focus { border-color: var(--accent); }
+  textarea::placeholder { color: var(--text-muted); }
+
+  .analyze-btn {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 16px;
+    padding: 12px 28px;
+    background: var(--accent);
+    color: #000;
+    font-family: var(--mono);
+    font-size: 13px;
+    font-weight: 700;
+    border: none;
+    border-radius: 8px;
+    cursor: pointer;
+    transition: all 0.2s;
+    letter-spacing: 0.5px;
+  }
+  .analyze-btn:hover { background: #79c0ff; transform: translateY(-1px); box-shadow: 0 4px 20px rgba(88,166,255,0.3); }
+  .analyze-btn:disabled { opacity: 0.5; cursor: not-allowed; transform: none; }
+
+  .spinner {
+    width: 14px;
+    height: 14px;
+    border: 2px solid rgba(0,0,0,0.3);
+    border-top-color: #000;
+    border-radius: 50%;
+    animation: spin 0.7s linear infinite;
+    display: none;
+  }
+  .spinner.active { display: block; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+
+  /* Result card */
+  .result-card {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 28px;
+    display: none;
+    animation: fadeSlideIn 0.3s ease;
+  }
+  .result-card.visible { display: block; }
+
+  @keyframes fadeSlideIn {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  .verdict-header {
+    display: flex;
+    align-items: flex-start;
+    gap: 20px;
+    margin-bottom: 24px;
+  }
+
+  .confidence-ring {
+    flex-shrink: 0;
+    width: 72px;
+    height: 72px;
+    position: relative;
+  }
+
+  .confidence-ring svg {
+    width: 72px;
+    height: 72px;
+    transform: rotate(-90deg);
+  }
+
+  .confidence-ring .track {
+    fill: none;
+    stroke: var(--border);
+    stroke-width: 6;
+  }
+
+  .confidence-ring .fill {
+    fill: none;
+    stroke-width: 6;
+    stroke-linecap: round;
+    transition: stroke-dashoffset 0.6s ease, stroke 0.3s;
+  }
+
+  .confidence-num {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: var(--mono);
+    font-size: 14px;
+    font-weight: 700;
+  }
+
+  .verdict-meta { flex: 1; }
+
+  .color-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px;
+    border-radius: 20px;
+    font-family: var(--mono);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    margin-bottom: 8px;
+  }
+  .color-badge.green { background: var(--green-glow); color: var(--green); border: 1px solid rgba(34,197,94,0.3); }
+  .color-badge.yellow { background: var(--yellow-glow); color: var(--yellow); border: 1px solid rgba(234,179,8,0.3); }
+  .color-badge.red { background: var(--red-glow); color: var(--red); border: 1px solid rgba(239,68,68,0.3); }
+  .color-badge.purple { background: var(--purple-glow); color: var(--purple); border: 1px solid rgba(168,85,247,0.3); }
+
+  .verdict-label {
+    font-family: var(--sans);
+    font-size: 18px;
+    font-weight: 700;
+    margin-bottom: 8px;
+    line-height: 1.3;
+  }
+
+  .explanation {
+    font-size: 14px;
+    color: var(--text-muted);
+    line-height: 1.7;
+  }
+
+  /* Metadata grid */
+  .meta-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    gap: 12px;
+    margin: 24px 0;
+    padding: 20px;
+    background: var(--surface2);
+    border-radius: 8px;
+  }
+
+  .meta-item { display: flex; flex-direction: column; gap: 4px; }
+  .meta-key {
+    font-family: var(--mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 1px;
+  }
+  .meta-value {
+    font-family: var(--mono);
+    font-size: 13px;
+    color: var(--text);
+    font-weight: 700;
+  }
+
+  /* Sources */
+  .sources-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    margin-bottom: 10px;
+  }
+
+  .source-item {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 14px;
+    background: var(--surface2);
+    border-radius: 6px;
+    margin-bottom: 6px;
+    font-size: 13px;
+    border: 1px solid transparent;
+    transition: border-color 0.2s;
+  }
+  .source-item:hover { border-color: var(--border); }
+  .source-favicon { width: 16px; height: 16px; border-radius: 3px; }
+  .source-domain { font-family: var(--mono); font-size: 11px; color: var(--accent); }
+
+  /* Pipeline log */
+  .pipeline-log {
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 16px;
+    margin-top: 24px;
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text-muted);
+    max-height: 200px;
+    overflow-y: auto;
+  }
+
+  .log-line {
+    display: flex;
+    gap: 12px;
+    margin-bottom: 4px;
+    animation: fadeIn 0.2s ease;
+  }
+  @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+  .log-ts { color: #444; flex-shrink: 0; }
+  .log-level { flex-shrink: 0; }
+  .log-level.info { color: var(--accent); }
+  .log-level.ok { color: var(--green); }
+  .log-level.warn { color: var(--yellow); }
+  .log-level.drop { color: var(--text-muted); }
+
+  /* Example claims */
+  .examples-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    margin-bottom: 12px;
+  }
+
+  .example-chip {
+    display: inline-block;
+    padding: 6px 12px;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    font-size: 12px;
+    color: var(--text-muted);
+    cursor: pointer;
+    margin: 0 6px 6px 0;
+    transition: all 0.2s;
+    line-height: 1.4;
+  }
+  .example-chip:hover { border-color: var(--accent); color: var(--text); background: rgba(88,166,255,0.05); }
+
+  /* Footer */
+  footer {
+    text-align: center;
+    padding: 32px 0;
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text-muted);
+    border-top: 1px solid var(--border);
+    position: relative;
+    z-index: 1;
+  }
+
+  .stack-tags { display: flex; gap: 8px; justify-content: center; flex-wrap: wrap; margin-top: 10px; }
+  .stack-tag {
+    padding: 3px 8px;
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    font-size: 10px;
+    letter-spacing: 0.5px;
+  }
+</style>
+</head>
+<body>
+<div class="container">
+  <header>
+    <div class="logo-row">
+      <div class="logo-icon">⬡</div>
+      <h1>FACT INTELLIGENCE SYSTEM</h1>
+    </div>
+    <p class="tagline">// omnichannel · real-time · hallucination-aware</p>
+  </header>
+
+  <div class="status-bar">
+    <div class="status-dot connecting" id="statusDot"></div>
+    <span id="statusText">connecting to intelligence engine...</span>
+  </div>
+
+  <!-- Input -->
+  <div class="analysis-card">
+    <div class="card-label">// source platform</div>
+    <div class="platform-row" id="platformRow">
+      <button class="platform-btn active" data-platform="news">News</button>
+      <button class="platform-btn" data-platform="twitter">X / Twitter</button>
+      <button class="platform-btn" data-platform="youtube">YouTube</button>
+      <button class="platform-btn" data-platform="instagram">Instagram</button>
+      <button class="platform-btn" data-platform="chatgpt">ChatGPT</button>
+      <button class="platform-btn" data-platform="claude">Claude</button>
+      <button class="platform-btn" data-platform="gemini">Gemini</button>
+    </div>
+
+    <div class="card-label" style="margin-top:20px">// text to analyze</div>
+    <textarea id="claimInput" placeholder="Paste a claim, headline, or AI-generated text here...&#10;&#10;Minimum 12 words required."></textarea>
+
+    <button class="analyze-btn" id="analyzeBtn" onclick="analyzeClaim()">
+      <div class="spinner" id="spinner"></div>
+      <span id="btnText">ANALYZE CLAIM</span>
+    </button>
+  </div>
+
+  <!-- Example claims -->
+  <div class="analysis-card">
+    <div class="examples-label">// example claims to test</div>
+    <span class="example-chip" onclick="setExample(this.textContent)">Scientists confirmed mRNA vaccines provide immunity lasting over 18 months in 73% of clinical trial participants.</span>
+    <span class="example-chip" onclick="setExample(this.textContent)">The Federal Reserve raised interest rates by 75 basis points — the largest single hike since 1994.</span>
+    <span class="example-chip" onclick="setExample(this.textContent)">According to a study published in Nature, this drug reduces tumor size by 500% in all stage-4 patients within 2 weeks.</span>
+    <span class="example-chip" onclick="setExample(this.textContent)">The Amazon rainforest lost 11,568 square kilometers to deforestation in 2023, a 22% increase year-over-year.</span>
+    <span class="example-chip" onclick="setExample(this.textContent)">As referenced in Smith et al. (2019), the compound shows 94.7% efficacy against all known variants of the pathogen.</span>
+  </div>
+
+  <!-- Result -->
+  <div class="result-card" id="resultCard">
+    <div class="verdict-header">
+      <div class="confidence-ring" id="confRing">
+        <svg viewBox="0 0 72 72">
+          <circle class="track" cx="36" cy="36" r="30"/>
+          <circle class="fill" id="confArc" cx="36" cy="36" r="30"
+            stroke-dasharray="188.5"
+            stroke-dashoffset="188.5"/>
+        </svg>
+        <div class="confidence-num" id="confNum">—</div>
+      </div>
+      <div class="verdict-meta">
+        <div class="color-badge" id="colorBadge">—</div>
+        <div class="verdict-label" id="verdictLabel">—</div>
+        <div class="explanation" id="explanationText">—</div>
+      </div>
+    </div>
+
+    <div class="meta-grid">
+      <div class="meta-item"><div class="meta-key">Trust Score</div><div class="meta-value" id="metaTrust">—</div></div>
+      <div class="meta-item"><div class="meta-key">X Velocity</div><div class="meta-value" id="metaVelocity">—</div></div>
+      <div class="meta-item"><div class="meta-key">Community Note</div><div class="meta-value" id="metaNote">—</div></div>
+      <div class="meta-item"><div class="meta-key">Pipeline (ms)</div><div class="meta-value" id="metaLatency">—</div></div>
+      <div class="meta-item"><div class="meta-key">Cache</div><div class="meta-value" id="metaCached">—</div></div>
+      <div class="meta-item"><div class="meta-key">Platform</div><div class="meta-value" id="metaPlatform">—</div></div>
+    </div>
+
+    <div id="sourcesSection">
+      <div class="sources-label">// evidence sources</div>
+      <div id="sourcesList"></div>
+    </div>
+
+    <div class="pipeline-log" id="pipelineLog"></div>
+  </div>
+</div>
+
+<footer>
+  <div>OMNICHANNEL FACT &amp; HALLUCINATION INTELLIGENCE SYSTEM v1.0</div>
+  <div class="stack-tags">
+    <span class="stack-tag">FastAPI</span>
+    <span class="stack-tag">BGE-M3</span>
+    <span class="stack-tag">Qdrant</span>
+    <span class="stack-tag">Memgraph</span>
+    <span class="stack-tag">Redpanda</span>
+    <span class="stack-tag">Redis Stack</span>
+    <span class="stack-tag">LiteLLM</span>
+    <span class="stack-tag">Prefect</span>
+    <span class="stack-tag">Groq</span>
+    <span class="stack-tag">WXT</span>
+  </div>
+</footer>
+
+<script>
+// ─── WebSocket client ────────────────────────────────────────────────────
+const SESSION_ID = crypto.randomUUID();
+const WS_URL = `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/ws/${SESSION_ID}`;
+
+let ws = null;
+let reconnectDelay = 1000;
+let selectedPlatform = 'news';
+
+function connect() {
+  setStatus('connecting');
+  log('INFO', `connecting to ${WS_URL}`);
+  ws = new WebSocket(WS_URL);
+
+  ws.onopen = () => {
+    setStatus('connected');
+    reconnectDelay = 1000;
+    log('OK', 'WebSocket connected — intelligence engine online');
+  };
+
+  ws.onclose = () => {
+    setStatus('disconnected');
+    log('WARN', `disconnected — reconnecting in ${reconnectDelay / 1000}s`);
+    setTimeout(connect, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+  };
+
+  ws.onerror = () => {
+    setStatus('error');
+    log('WARN', 'WebSocket error — will retry');
+  };
+
+  ws.onmessage = (evt) => {
+    const msg = JSON.parse(evt.data);
+    if (msg.type === 'pong') return;
+    if (msg.type === 'status') {
+      const p = msg.payload;
+      log('INFO', `engine status: demo=${p.demo_mode}, groq=${p.has_groq}, x_api=${p.has_x_api}`);
+      return;
+    }
+    if (msg.type === 'result') renderResult(msg.payload);
+    if (msg.type === 'error') {
+      log('WARN', `error: ${msg.payload?.message}`);
+      resetBtn();
+    }
+  };
+}
+
+// Keepalive ping every 20s
+setInterval(() => { if (ws?.readyState === 1) ws.send(JSON.stringify({ type: 'ping' })); }, 20000);
+
+// ─── Platform selector ───────────────────────────────────────────────────
+document.getElementById('platformRow').addEventListener('click', (e) => {
+  const btn = e.target.closest('.platform-btn');
+  if (!btn) return;
+  document.querySelectorAll('.platform-btn').forEach(b => b.classList.remove('active'));
+  btn.classList.add('active');
+  selectedPlatform = btn.dataset.platform;
+});
+
+// ─── Analysis ────────────────────────────────────────────────────────────
+async function analyzeClaim() {
+  const text = document.getElementById('claimInput').value.trim();
+  if (!text) return;
+
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length < 12) {
+    log('WARN', `text too short: ${words.length} words (minimum 12)`);
+    return;
+  }
+
+  if (!ws || ws.readyState !== 1) {
+    log('WARN', 'not connected — retrying connection');
+    connect();
+    return;
+  }
+
+  setBtnLoading(true);
+  document.getElementById('resultCard').classList.remove('visible');
+  log('INFO', `sending claim (${words.length} words) on platform: ${selectedPlatform}`);
+
+  // Compute xxhash-like fingerprint in browser (simplified)
+  const hash = await hashText(text);
+  log('INFO', `content hash: ${hash.slice(0, 8)}... — checking cache`);
+
+  const batch = {
+    type: 'batch',
+    payload: {
+      session_id: SESSION_ID,
+      platform: selectedPlatform,
+      segments: [{
+        content_hash: hash,
+        text: text,
+        element_id: `demo-${Date.now()}`,
+        word_count: words.length,
+      }],
+      sent_at: new Date().toISOString(),
+    }
+  };
+
+  ws.send(JSON.stringify(batch));
+  log('INFO', 'batch dispatched → gatekeeper → RAG → agents');
+}
+
+async function hashText(text) {
+  const buf = new TextEncoder().encode(text);
+  const hashBuf = await crypto.subtle.digest('SHA-256', buf);
+  return Array.from(new Uint8Array(hashBuf)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+// ─���─ Render result ────────────────────────────────────────────────────────
+function renderResult(r) {
+  setBtnLoading(false);
+
+  const colorMap = {
+    green:  { label: '✓ VERIFIED',         stroke: '#22c55e' },
+    yellow: { label: '⚠ UNVERIFIED',       stroke: '#eab308' },
+    red:    { label: '✗ DEBUNKED',         stroke: '#ef4444' },
+    purple: { label: '◈ AI HALLUCINATION', stroke: '#a855f7' },
+  };
+
+  const c = colorMap[r.color] || colorMap.yellow;
+
+  // Confidence arc
+  const arc = document.getElementById('confArc');
+  const circumference = 2 * Math.PI * 30;
+  const offset = circumference - (r.confidence / 100) * circumference;
+  arc.style.strokeDashoffset = offset;
+  arc.style.stroke = c.stroke;
+  document.getElementById('confNum').textContent = r.confidence;
+  document.getElementById('confNum').style.color = c.stroke;
+
+  // Badge
+  const badge = document.getElementById('colorBadge');
+  badge.textContent = c.label;
+  badge.className = `color-badge ${r.color}`;
+
+  document.getElementById('verdictLabel').textContent = r.verdict_label || 'Analysis complete';
+  document.getElementById('explanationText').textContent = r.explanation || '';
+
+  // Meta
+  document.getElementById('metaTrust').textContent = (r.trust_score * 100).toFixed(0) + '%';
+  document.getElementById('metaVelocity').textContent = r.velocity?.toLocaleString() ?? '—';
+  document.getElementById('metaNote').textContent = r.has_community_note ? '⚠ YES' : '✓ None';
+  document.getElementById('metaNote').style.color = r.has_community_note ? 'var(--red)' : 'var(--green)';
+  document.getElementById('metaLatency').textContent = r.latency_ms?.toFixed(1) ?? '—';
+  document.getElementById('metaCached').textContent = r.cached ? '✓ HIT' : '✗ MISS';
+  document.getElementById('metaPlatform').textContent = r.platform?.toUpperCase() ?? '—';
+
+  // Sources
+  const list = document.getElementById('sourcesList');
+  list.innerHTML = '';
+  if (r.sources?.length) {
+    r.sources.forEach(s => {
+      const el = document.createElement('div');
+      el.className = 'source-item';
+      el.innerHTML = `
+        <img class="source-favicon" src="${s.favicon_url}" onerror="this.style.display='none'">
+        <div>
+          <div class="source-domain">${s.domain || 'unknown'}</div>
+          <div style="font-size:12px;color:var(--text-muted);margin-top:2px">${s.snippet || s.url || ''}</div>
+        </div>`;
+      list.appendChild(el);
+    });
+    document.getElementById('sourcesSection').style.display = 'block';
+  } else {
+    document.getElementById('sourcesSection').style.display = 'none';
+  }
+
+  log('OK', `verdict: ${r.color.toUpperCase()} (${r.confidence}%) — ${r.verdict_label}`);
+  document.getElementById('resultCard').classList.add('visible');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+function setStatus(state) {
+  const dot = document.getElementById('statusDot');
+  const txt = document.getElementById('statusText');
+  dot.className = 'status-dot';
+  if (state === 'connected') { dot.classList.add('connected'); txt.textContent = 'intelligence engine online'; }
+  else if (state === 'connecting') { dot.classList.add('connecting'); txt.textContent = 'connecting...'; }
+  else if (state === 'error') { dot.classList.add('error'); txt.textContent = 'connection error'; }
+  else { txt.textContent = 'offline — reconnecting'; }
+}
+
+function setBtnLoading(loading) {
+  document.getElementById('spinner').classList.toggle('active', loading);
+  document.getElementById('btnText').textContent = loading ? 'ANALYZING...' : 'ANALYZE CLAIM';
+  document.getElementById('analyzeBtn').disabled = loading;
+}
+
+function resetBtn() { setBtnLoading(false); }
+
+function log(level, msg) {
+  const container = document.getElementById('pipelineLog');
+  const now = new Date().toISOString().slice(11, 23);
+  const levelClass = { INFO: 'info', OK: 'ok', WARN: 'warn', DROP: 'drop' }[level] || 'info';
+  const line = document.createElement('div');
+  line.className = 'log-line';
+  line.innerHTML = `<span class="log-ts">${now}</span><span class="log-level ${levelClass}">[${level}]</span><span>${msg}</span>`;
+  container.appendChild(line);
+  container.scrollTop = container.scrollHeight;
+}
+
+function setExample(text) {
+  document.getElementById('claimInput').value = text.trim();
+}
+
+// Start
+connect();
+log('INFO', 'intelligence system initialized');
+log('INFO', `session: ${SESSION_ID.slice(0, 8)}...`);
+</script>
+</body>
+</html>

backend/tests/test_pipeline.py

@@ -0,0 +1,305 @@
+"""
+tests/test_pipeline.py — Integration-style tests for the full fact-checking pipeline.
+
+Run with:
+  uv run pytest tests/ -v
+
+Tests use DEMO_MODE=true to avoid needing real API keys.
+All external services (Qdrant, Memgraph, Redis) are mocked using monkeypatching.
+"""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from core.config import HighlightColor, Platform, Settings
+from core.models import (
+    EvidenceChunk,
+    GatekeeperResult,
+    GrokSensorResult,
+    RAGResult,
+    TextBatch,
+    TextSegment,
+    TrustScore,
+)
+from gatekeeper import classify_claim, _heuristic_classify
+from grok_sensor import _mock_sensor_result, _extract_keywords
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def demo_settings() -> Settings:
+    return Settings(
+        DEMO_MODE=True,
+        GROQ_API_KEY="",
+        ANTHROPIC_API_KEY="",
+        X_BEARER_TOKEN="",
+        QDRANT_HOST="localhost",
+        MEMGRAPH_HOST="localhost",
+        REDIS_URL="redis://localhost:6379",
+    )
+
+
+@pytest.fixture
+def sample_rag_result() -> RAGResult:
+    from datetime import datetime, timezone
+    return RAGResult(
+        evidence=[
+            EvidenceChunk(
+                chunk_id="test-001",
+                text="Scientists confirmed mRNA vaccines provide long-term immunity.",
+                source_url="https://reuters.com/article/123",
+                domain="reuters.com",
+                score=0.89,
+                ingested_at=datetime.now(timezone.utc),
+                bias_rating="center",
+            )
+        ],
+        trust=TrustScore(
+            score=0.75,
+            author_verified=True,
+            corroborating_sources=2,
+            has_community_note=False,
+        ),
+    )
+
+
+@pytest.fixture
+def sample_grok_result() -> GrokSensorResult:
+    return GrokSensorResult(
+        velocity=1200,
+        community_note=False,
+        note_text=None,
+        is_mock=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gatekeeper tests
+# ---------------------------------------------------------------------------
+
+class TestGatekeeper:
+    @pytest.mark.asyncio
+    async def test_heuristic_classifies_opinion_as_noise(self, demo_settings):
+        result = await classify_claim("I think this is all just propaganda honestly", demo_settings)
+        assert result.label == "noise"
+
+    @pytest.mark.asyncio
+    async def test_heuristic_classifies_numeric_claim_as_fact(self, demo_settings):
+        result = await classify_claim(
+            "According to the CDC report, 73% of participants showed immunity lasting 18 months",
+            demo_settings,
+        )
+        assert result.label == "fact"
+
+    def test_heuristic_opinion_starters(self):
+        opinion_texts = [
+            "I think the whole thing is suspicious and people should wake up",
+            "I believe this is all connected somehow to something bigger",
+            "IMO this is the worst policy decision in history by far",
+        ]
+        for text in opinion_texts:
+            result = _heuristic_classify(text)
+            assert result.label == "noise", f"Expected noise for: {text}"
+
+    def test_heuristic_factual_claim(self):
+        result = _heuristic_classify(
+            "The Federal Reserve raised rates by 75 basis points according to the official announcement"
+        )
+        assert result.label == "fact"
+        assert result.confidence > 0.5
+
+    def test_gatekeeper_result_confidence_bounds(self):
+        result = _heuristic_classify("Scientists found that 47% of participants showed no immunity")
+        assert 0.0 <= result.confidence <= 1.0
+
+    def test_gatekeeper_result_valid_label(self):
+        result = _heuristic_classify("lol did you see that? total propaganda 😂")
+        assert result.label in {"fact", "noise"}
+
+
+# ---------------------------------------------------------------------------
+# Grok sensor tests
+# ---------------------------------------------------------------------------
+
+class TestGrokSensor:
+    def test_mock_is_deterministic(self):
+        """Same hash should always produce the same mock result."""
+        h = "abcdef1234567890"
+        r1 = _mock_sensor_result(h)
+        r2 = _mock_sensor_result(h)
+        assert r1.velocity == r2.velocity
+        assert r1.community_note == r2.community_note
+        assert r1.is_mock is True
+
+    def test_mock_different_hashes_produce_variation(self):
+        """Different hashes should produce different results (not all identical)."""
+        results = [_mock_sensor_result(f"hash_{i:04d}") for i in range(50)]
+        velocities = [r.velocity for r in results]
+        # Should have variation — not all the same value
+        assert len(set(velocities)) > 5
+
+    def test_keyword_extraction_removes_stopwords(self):
+        text = "The Federal Reserve is raising interest rates by 75 basis points today"
+        keywords = _extract_keywords(text)
+        assert "the" not in keywords
+        assert "is" not in keywords
+        # Meaningful words should be present
+        assert any(k.lower() in ("federal", "reserve", "raising", "interest", "rates") for k in keywords)
+
+    def test_keyword_extraction_max_10(self):
+        long_text = " ".join(f"word{i}" for i in range(50))
+        keywords = _extract_keywords(long_text)
+        assert len(keywords) <= 10
+
+
+# ---------------------------------------------------------------------------
+# Model validation tests
+# ---------------------------------------------------------------------------
+
+class TestModels:
+    def test_text_segment_rejects_short_text(self):
+        with pytest.raises(Exception):
+            TextSegment(
+                content_hash="abc123",
+                text="too short",
+                element_id="el-001",
+                word_count=2,  # Below minimum of 12
+            )
+
+    def test_text_batch_platform_validation(self):
+        batch = TextBatch(
+            session_id="test-session",
+            platform=Platform.TWITTER,
+            segments=[
+                TextSegment(
+                    content_hash="a" * 16,
+                    text="Scientists confirmed that 73 percent of mRNA vaccine recipients showed 18-month immunity",
+                    element_id="el-001",
+                    word_count=15,
+                )
+            ],
+        )
+        assert batch.platform == Platform.TWITTER
+        assert len(batch.segments) == 1
+
+    def test_trust_score_clamping(self):
+        # Trust score should be clamped to [0, 1]
+        ts = TrustScore(
+            score=0.5,
+            author_verified=True,
+            corroborating_sources=3,
+            has_community_note=False,
+        )
+        assert 0.0 <= ts.score <= 1.0
+
+    def test_gatekeeper_result_invalid_label_raises(self):
+        with pytest.raises(Exception):
+            GatekeeperResult.model_validate({"label": "unknown", "reason": "test", "confidence": 0.5})
+
+
+# ---------------------------------------------------------------------------
+# Agent pipeline tests (mocked)
+# ---------------------------------------------------------------------------
+
+class TestAgents:
+    @pytest.mark.asyncio
+    async def test_evaluate_claim_demo_mode(
+        self, demo_settings, sample_rag_result, sample_grok_result
+    ):
+        """In demo mode, evaluate_claim should return a valid AnalysisResult without API calls."""
+        from agents import evaluate_claim
+
+        result = await evaluate_claim(
+            claim="Scientists confirmed that mRNA vaccines provide immunity lasting over 18 months in clinical trials",
+            claim_hash="testhashabc123",
+            element_id="el-test-001",
+            platform=Platform.NEWS,
+            rag_result=sample_rag_result,
+            grok_result=sample_grok_result,
+            settings=demo_settings,
+        )
+
+        assert result.color in {HighlightColor.GREEN, HighlightColor.YELLOW, HighlightColor.RED, HighlightColor.PURPLE}
+        assert 0 <= result.confidence <= 100
+        assert result.element_id == "el-test-001"
+        assert result.trust_score == sample_rag_result.trust.score
+
+    @pytest.mark.asyncio
+    async def test_low_trust_score_yields_red_or_yellow(
+        self, demo_settings, sample_grok_result
+    ):
+        """Claims with low trust scores should not get green verdicts."""
+        from datetime import datetime, timezone
+        from agents import evaluate_claim
+
+        low_trust_rag = RAGResult(
+            evidence=[],
+            trust=TrustScore(
+                score=0.1,  # Very low
+                author_verified=False,
+                corroborating_sources=0,
+                has_community_note=True,
+                community_note_text="This claim is misleading.",
+            ),
+        )
+
+        result = await evaluate_claim(
+            claim="Completely fabricated statistic that 500% of people believe this false claim completely",
+            claim_hash="lowtrusthash123",
+            element_id="el-test-002",
+            platform=Platform.TWITTER,
+            rag_result=low_trust_rag,
+            grok_result=GrokSensorResult(velocity=50000, community_note=True, note_text="Misleading"),
+            settings=demo_settings,
+        )
+
+        assert result.color in {HighlightColor.RED, HighlightColor.YELLOW}
+        assert result.has_community_note is True
+
+    @pytest.mark.asyncio
+    async def test_ai_platform_triggers_hallucination_check(
+        self, demo_settings, sample_rag_result, sample_grok_result
+    ):
+        """AI platforms should trigger the hallucination task (in demo, returns purple)."""
+        from agents import evaluate_claim
+
+        result = await evaluate_claim(
+            claim="As cited in Smith et al. 2019 paper on quantum biology, the compound achieves 99.7% efficacy across all known variants",
+            claim_hash="halluchash456",
+            element_id="el-test-003",
+            platform=Platform.CHATGPT,  # AI platform — triggers hallucination check
+            rag_result=sample_rag_result,
+            grok_result=sample_grok_result,
+            settings=demo_settings,
+        )
+
+        # On AI platforms in demo mode, hallucination check runs and may override color
+        assert result.color in {HighlightColor.PURPLE, HighlightColor.GREEN, HighlightColor.YELLOW, HighlightColor.RED}
+        assert result.platform == Platform.CHATGPT
+
+
+# ---------------------------------------------------------------------------
+# Cache key tests
+# ---------------------------------------------------------------------------
+
+class TestCacheKeys:
+    def test_cache_key_format(self):
+        """Cache keys should follow the `verdict:{hash}` format."""
+        content_hash = "abc123def456"
+        cache_key = f"verdict:{content_hash}"
+        assert cache_key == "verdict:abc123def456"
+
+    def test_different_texts_produce_different_hashes(self):
+        import xxhash
+        texts = [
+            "Scientists confirmed 73% immunity",
+            "Scientists confirmed 74% immunity",
+            "completely different claim about climate change",
+        ]
+        hashes = [xxhash.xxh64(t.encode()).hexdigest() for t in texts]
+        assert len(set(hashes)) == len(hashes), "All hashes should be unique"

docker-compose.yml

@@ -0,0 +1,164 @@
+version: "3.9"
+
+# =============================================================================
+# Omnichannel Fact & Hallucination Intelligence System
+# HuggingFace Spaces compatible — single `docker compose up` deployment
+# Services: FastAPI (7860), Qdrant (6333), Memgraph (7687), Redpanda (9092), Redis Stack (6379)
+# =============================================================================
+
+networks:
+  fact-net:
+    driver: bridge
+
+volumes:
+  qdrant_storage:
+  memgraph_data:
+  redpanda_data:
+  redis_data:
+
+services:
+  # ---------------------------------------------------------------------------
+  # QDRANT — Vector DB for claim embeddings (self-hosted, sub-ms HNSW search)
+  # ---------------------------------------------------------------------------
+  qdrant:
+    image: qdrant/qdrant:v1.9.2
+    container_name: fact-qdrant
+    restart: unless-stopped
+    networks: [fact-net]
+    ports:
+      - "6333:6333"
+      - "6334:6334"   # gRPC
+    volumes:
+      - qdrant_storage:/qdrant/storage
+    environment:
+      QDRANT__SERVICE__GRPC_PORT: 6334
+      QDRANT__TELEMETRY_DISABLED: "true"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:6333/readyz"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # ---------------------------------------------------------------------------
+  # MEMGRAPH — In-memory graph DB for trust-score traversal (Cypher compatible)
+  # 10-100x faster than Neo4j for real-time traversal since everything is in RAM
+  # ---------------------------------------------------------------------------
+  memgraph:
+    image: memgraph/memgraph-platform:2.16.0
+    container_name: fact-memgraph
+    restart: unless-stopped
+    networks: [fact-net]
+    ports:
+      - "7687:7687"   # Bolt
+      - "3000:3000"   # Memgraph Lab UI
+    volumes:
+      - memgraph_data:/var/lib/memgraph
+    environment:
+      MEMGRAPH_USER: memgraph
+      MEMGRAPH_PASSWORD: memgraph123
+    healthcheck:
+      test: ["CMD", "mg_client", "--host", "localhost", "--port", "7687", "--use-ssl=false", "-q", "RETURN 1;"]
+      interval: 15s
+      timeout: 10s
+      retries: 5
+
+  # ---------------------------------------------------------------------------
+  # REDPANDA — Kafka-compatible message queue (no JVM, no ZooKeeper, 10x lower
+  # latency). Handles the omnichannel ingestion firehose from all producers.
+  # ---------------------------------------------------------------------------
+  redpanda:
+    image: redpandadata/redpanda:v24.1.7
+    container_name: fact-redpanda
+    restart: unless-stopped
+    networks: [fact-net]
+    ports:
+      - "9092:9092"   # Kafka API
+      - "9644:9644"   # Admin API
+      - "8081:8081"   # Schema registry
+    volumes:
+      - redpanda_data:/var/lib/redpanda/data
+    command:
+      - redpanda
+      - start
+      - --smp=1
+      - --memory=512M
+      - --overprovisioned
+      - --kafka-addr=PLAINTEXT://0.0.0.0:9092
+      - --advertise-kafka-addr=PLAINTEXT://redpanda:9092
+      - --pandaproxy-addr=0.0.0.0:8082
+      - --advertise-pandaproxy-addr=redpanda:8082
+      - --schema-registry-addr=0.0.0.0:8081
+      - --rpc-addr=redpanda:33145
+      - --advertise-rpc-addr=redpanda:33145
+    healthcheck:
+      test: ["CMD", "rpk", "cluster", "health"]
+      interval: 15s
+      timeout: 10s
+      retries: 5
+
+  # ---------------------------------------------------------------------------
+  # REDIS STACK — Redis + RedisJSON + RedisSearch for structured claim caching
+  # TTL: 6h for Green/Red verdicts, 15min for Yellow, no cache for Purple
+  # ---------------------------------------------------------------------------
+  redis-stack:
+    image: redis/redis-stack:7.4.0-v0
+    container_name: fact-redis
+    restart: unless-stopped
+    networks: [fact-net]
+    ports:
+      - "6379:6379"   # Redis
+      - "8001:8001"   # RedisInsight UI
+    volumes:
+      - redis_data:/data
+    environment:
+      REDIS_ARGS: "--maxmemory 256mb --maxmemory-policy allkeys-lru"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # ---------------------------------------------------------------------------
+  # BACKEND — FastAPI intelligence engine (HF Spaces listens on 7860)
+  # Waits for all upstream services to be healthy before starting
+  # ---------------------------------------------------------------------------
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: fact-backend
+    restart: unless-stopped
+    networks: [fact-net]
+    ports:
+      - "7860:7860"   # HuggingFace Spaces default port
+    depends_on:
+      qdrant:
+        condition: service_healthy
+      memgraph:
+        condition: service_healthy
+      redpanda:
+        condition: service_healthy
+      redis-stack:
+        condition: service_healthy
+    environment:
+      # LLM providers — set in HF Space secrets
+      GROQ_API_KEY: ${GROQ_API_KEY:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      X_BEARER_TOKEN: ${X_BEARER_TOKEN:-}
+
+      # Infrastructure endpoints (internal Docker network)
+      QDRANT_HOST: qdrant
+      QDRANT_PORT: 6333
+      MEMGRAPH_HOST: memgraph
+      MEMGRAPH_PORT: 7687
+      MEMGRAPH_PASSWORD: memgraph123
+      REDPANDA_BROKERS: redpanda:9092
+      REDIS_URL: redis://redis-stack:6379
+
+      # App config
+      PORT: 7860
+      LOG_LEVEL: INFO
+      DEMO_MODE: ${DEMO_MODE:-false}   # true = use mock data, skip external APIs
+    volumes:
+      - ./backend:/app
+    command: ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--reload"]

extension/entrypoints/background.ts

@@ -0,0 +1,179 @@
+// extension/entrypoints/background.ts
+// Persistent background service worker.
+// Maintains a SINGLE WebSocket connection to the backend intelligence engine.
+// Routes results to the correct content script via chrome.tabs.sendMessage.
+//
+// Why a single connection in the background?
+// Content scripts are destroyed/recreated on navigation. The background worker
+// persists for the lifetime of the extension, ensuring we never drop messages
+// and reconnection logic runs in one place.
+
+import { defineBackground } from "wxt/sandbox";
+
+// Injected by wxt.config.ts vite.define — falls back to localhost for dev
+declare const __WS_URL__: string;
+const WS_URL = typeof __WS_URL__ !== "undefined"
+  ? __WS_URL__
+  : "ws://localhost:7860/ws";
+
+const SESSION_ID = crypto.randomUUID();
+
+// ---------------------------------------------------------------------------
+// WebSocket connection with exponential backoff
+// ---------------------------------------------------------------------------
+
+let ws: WebSocket | null = null;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let reconnectDelay = 1_000;  // Start at 1s, cap at 30s
+
+// Tab ID → { platform, pendingHashes } mapping for routing results back
+const tabRegistry = new Map<number, { platform: string }>();
+
+function getWsUrl(): string {
+  return `${WS_URL}/${SESSION_ID}`;
+}
+
+function connect(): void {
+  if (ws?.readyState === WebSocket.OPEN) return;
+
+  ws = new WebSocket(getWsUrl());
+
+  ws.onopen = () => {
+    console.log("[background] WS connected:", getWsUrl());
+    reconnectDelay = 1_000;  // Reset backoff on successful connection
+    broadcastStatus("connected");
+  };
+
+  ws.onmessage = (evt: MessageEvent) => {
+    try {
+      const msg = JSON.parse(evt.data as string);
+
+      if (msg.type === "pong") return;
+
+      if (msg.type === "status") {
+        // Forward demo mode flag to all content scripts
+        chrome.tabs.query({}, (tabs) => {
+          tabs.forEach((tab) => {
+            if (tab.id) {
+              chrome.tabs.sendMessage(tab.id, {
+                type: "status",
+                payload: msg.payload,
+              }).catch(() => {/* Tab may not have content script */});
+            }
+          });
+        });
+        return;
+      }
+
+      if (msg.type === "result" && msg.payload) {
+        routeResultToTab(msg.payload);
+      }
+
+      if (msg.type === "error") {
+        console.error("[background] Server error:", msg.payload?.message);
+      }
+    } catch (err) {
+      console.error("[background] Message parse error:", err);
+    }
+  };
+
+  ws.onclose = (evt) => {
+    ws = null;
+    console.log(`[background] WS closed (code=${evt.code}), reconnecting in ${reconnectDelay}ms`);
+    broadcastStatus("reconnecting");
+
+    reconnectTimer = setTimeout(() => {
+      reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+      connect();
+    }, reconnectDelay);
+  };
+
+  ws.onerror = () => {
+    broadcastStatus("offline");
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route analysis results to the tab that originated the request
+// ---------------------------------------------------------------------------
+
+function routeResultToTab(result: Record<string, unknown>): void {
+  // Find the tab that has this element (active tabs with content scripts)
+  chrome.tabs.query({ active: true }, (tabs) => {
+    tabs.forEach((tab) => {
+      if (tab.id) {
+        chrome.tabs.sendMessage(tab.id, {
+          type: "result",
+          payload: result,
+        }).catch(() => {/* Content script may not be injected on this tab */});
+      }
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Broadcast WS status to all content scripts + popup
+// ---------------------------------------------------------------------------
+
+function broadcastStatus(status: string): void {
+  chrome.tabs.query({}, (tabs) => {
+    tabs.forEach((tab) => {
+      if (tab.id) {
+        chrome.tabs.sendMessage(tab.id, { type: "ws_status", payload: { status } })
+          .catch(() => {});
+      }
+    });
+  });
+
+  // Also notify popup if open
+  chrome.runtime.sendMessage({ type: "ws_status", payload: { status } })
+    .catch(() => {});
+}
+
+// ---------------------------------------------------------------------------
+// Handle messages from content scripts
+// ---------------------------------------------------------------------------
+
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
+  if (msg.type === "send_batch") {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: "batch", payload: msg.payload }));
+      sendResponse({ ok: true });
+    } else {
+      sendResponse({ ok: false, reason: "not_connected" });
+    }
+    return true;  // Async response
+  }
+
+  if (msg.type === "get_status") {
+    sendResponse({
+      status: ws?.readyState === WebSocket.OPEN ? "connected" : "offline",
+    });
+    return true;
+  }
+
+  if (msg.type === "ping") {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: "ping" }));
+    }
+    sendResponse({ ok: true });
+    return true;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Keepalive — prevents background worker from being suspended
+// ---------------------------------------------------------------------------
+
+setInterval(() => {
+  if (ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ type: "ping" }));
+  } else if (!ws || ws.readyState === WebSocket.CLOSED) {
+    connect();  // Re-attempt if connection died silently
+  }
+}, 20_000);
+
+export default defineBackground(() => {
+  connect();
+  console.log("[background] Fact Intelligence background worker started");
+});

extension/entrypoints/content.tsx

@@ -0,0 +1,453 @@
+// extension/entrypoints/content.tsx
+// Main content script — runs in every matching page context.
+//
+// Pipeline:
+//   1. MutationObserver watches for meaningful text node changes
+//   2. Text is accumulated in a ring buffer, flushed every 1200ms
+//   3. Each flush is deduplicated via xxhash-wasm (client-side)
+//   4. Deduplicated segments sent to background worker → WebSocket
+//   5. Results come back as chrome.runtime.onMessage events
+//   6. Highlights applied as <mark> elements via Range.surroundContents()
+//   7. Hover cards rendered inside a Shadow DOM to prevent CSS bleed
+
+import { defineContentScript } from "wxt/sandbox";
+import { createRoot } from "react-dom/client";
+import React, { useEffect, useRef, useState } from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import { init as initXxhash, h64ToString } from "xxhash-wasm";
+
+import {
+  AnalysisResult,
+  COLOR_CONFIG,
+  ExtensionMode,
+  HighlightColor,
+  shouldShowColor,
+  useExtensionStore,
+} from "../stores/extensionStore";
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+function detectPlatform(): string {
+  const host = location.hostname;
+  if (host.includes("twitter.com") || host.includes("x.com")) return "twitter";
+  if (host.includes("instagram.com")) return "instagram";
+  if (host.includes("youtube.com")) return "youtube";
+  if (host.includes("chat.openai.com")) return "chatgpt";
+  if (host.includes("claude.ai")) return "claude";
+  if (host.includes("gemini.google.com")) return "gemini";
+  return "news";
+}
+
+// ---------------------------------------------------------------------------
+// Text node utilities
+// ---------------------------------------------------------------------------
+
+const SKIP_TAGS = new Set(["SCRIPT", "STYLE", "SVG", "NOSCRIPT", "IFRAME", "META", "HEAD"]);
+
+function isValidTextNode(node: Text): boolean {
+  const parent = node.parentElement;
+  if (!parent) return false;
+
+  // Skip non-content tags
+  let el: Element | null = parent;
+  while (el) {
+    if (SKIP_TAGS.has(el.tagName)) return false;
+    el = el.parentElement;
+  }
+
+  const text = node.textContent?.trim() ?? "";
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount >= 12;
+}
+
+function extractTextNodes(root: Node): Text[] {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      isValidTextNode(node as Text) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP,
+  });
+  const nodes: Text[] = [];
+  while (walker.nextNode()) nodes.push(walker.currentNode as Text);
+  return nodes;
+}
+
+// ---------------------------------------------------------------------------
+// Ring buffer — accumulates text segments, flushed every 1200ms
+// ---------------------------------------------------------------------------
+
+interface QueuedSegment {
+  hash: string;
+  text: string;
+  node: Text;
+  elementId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Highlight system
+// ---------------------------------------------------------------------------
+
+const highlightMap = new Map<string, HTMLElement>(); // elementId → <mark>
+
+function applyHighlight(
+  node: Text,
+  elementId: string,
+  color: HighlightColor,
+  result: AnalysisResult
+): void {
+  // If already highlighted, update color only
+  const existing = highlightMap.get(elementId);
+  if (existing) {
+    const cfg = COLOR_CONFIG[color];
+    existing.style.backgroundColor = `${cfg.hex}${Math.round(cfg.opacity * 255).toString(16).padStart(2, "0")}`;
+    existing.dataset.result = JSON.stringify(result);
+    return;
+  }
+
+  try {
+    const range = document.createRange();
+    range.selectNode(node);
+
+    const cfg = COLOR_CONFIG[color];
+    const mark = document.createElement("mark");
+    mark.dataset.factId = elementId;
+    mark.dataset.result = JSON.stringify(result);
+    mark.style.cssText = `
+      background-color: ${cfg.hex}${Math.round(cfg.opacity * 255).toString(16).padStart(2, "0")};
+      border-radius: 2px;
+      cursor: help;
+      transition: background-color 0.2s;
+    `;
+
+    range.surroundContents(mark);
+    highlightMap.set(elementId, mark);
+
+    // Mount hover card on mouseenter using Shadow DOM
+    mark.addEventListener("mouseenter", (e) => showHoverCard(e, result, mark));
+    mark.addEventListener("mouseleave", hideHoverCard);
+  } catch {
+    // surroundContents() fails on nodes that cross element boundaries — skip silently
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hover card — Shadow DOM isolated, Framer Motion animated
+// ---------------------------------------------------------------------------
+
+let hoverCardHost: HTMLElement | null = null;
+let hoverRoot: ReturnType<typeof createRoot> | null = null;
+
+function ensureHoverCardHost(): { host: HTMLElement; shadowRoot: ShadowRoot } {
+  if (!hoverCardHost) {
+    hoverCardHost = document.createElement("div");
+    hoverCardHost.id = "fact-intelligence-hover-host";
+    document.body.appendChild(hoverCardHost);
+
+    const shadow = hoverCardHost.attachShadow({ mode: "closed" });
+
+    // Inject Tailwind-scoped styles directly into shadow root
+    const style = document.createElement("style");
+    style.textContent = HOVER_CARD_STYLES;
+    shadow.appendChild(style);
+
+    const mountPoint = document.createElement("div");
+    shadow.appendChild(mountPoint);
+    hoverRoot = createRoot(mountPoint);
+
+    return { host: hoverCardHost, shadowRoot: shadow };
+  }
+  return { host: hoverCardHost, shadowRoot: hoverCardHost.shadowRoot! as ShadowRoot };
+}
+
+function showHoverCard(event: MouseEvent, result: AnalysisResult, anchor: HTMLElement): void {
+  const { shadowRoot } = ensureHoverCardHost();
+  const rect = anchor.getBoundingClientRect();
+
+  // Viewport clamping — card must never overflow
+  let top = rect.bottom + window.scrollY + 8;
+  let left = rect.left + window.scrollX;
+  const CARD_WIDTH = 340;
+  const CARD_HEIGHT = 200;
+
+  if (left + CARD_WIDTH > window.innerWidth - 16) {
+    left = window.innerWidth - CARD_WIDTH - 16;
+  }
+  if (top + CARD_HEIGHT > window.innerHeight + window.scrollY - 16) {
+    top = rect.top + window.scrollY - CARD_HEIGHT - 8; // Flip above
+  }
+
+  hoverRoot?.render(
+    <HoverCard result={result} top={top} left={left} visible={true} />
+  );
+}
+
+function hideHoverCard(): void {
+  hoverRoot?.render(<HoverCard result={null} top={0} left={0} visible={false} />);
+}
+
+// ---------------------------------------------------------------------------
+// HoverCard React component
+// ---------------------------------------------------------------------------
+
+interface HoverCardProps {
+  result: AnalysisResult | null;
+  top: number;
+  left: number;
+  visible: boolean;
+}
+
+function HoverCard({ result, top, left, visible }: HoverCardProps) {
+  if (!result) return null;
+  const cfg = COLOR_CONFIG[result.color as HighlightColor] ?? COLOR_CONFIG.yellow;
+
+  return (
+    <AnimatePresence>
+      {visible && (
+        <motion.div
+          className="card"
+          style={{ top, left, "--accent": cfg.hex } as React.CSSProperties}
+          initial={{ opacity: 0, y: 6, scale: 0.97 }}
+          animate={{ opacity: 1, y: 0, scale: 1 }}
+          exit={{ opacity: 0, y: 4, scale: 0.97 }}
+          transition={{ duration: 0.18, ease: "easeOut" }}
+        >
+          {/* Header row */}
+          <div className="header">
+            <div className="badge">{cfg.icon} {cfg.label}</div>
+            <div className="conf">
+              <svg width="36" height="36" viewBox="0 0 36 36">
+                <circle cx="18" cy="18" r="14" fill="none" stroke="#333" strokeWidth="3"/>
+                <circle
+                  cx="18" cy="18" r="14"
+                  fill="none"
+                  stroke={cfg.hex}
+                  strokeWidth="3"
+                  strokeLinecap="round"
+                  strokeDasharray={`${2 * Math.PI * 14}`}
+                  strokeDashoffset={`${2 * Math.PI * 14 * (1 - result.confidence / 100)}`}
+                  transform="rotate(-90 18 18)"
+                />
+                <text x="18" y="22" textAnchor="middle" fontSize="10" fill={cfg.hex} fontWeight="bold">
+                  {result.confidence}
+                </text>
+              </svg>
+            </div>
+          </div>
+
+          {/* Verdict */}
+          <div className="verdict">{result.verdict_label}</div>
+          <div className="explanation">{result.explanation}</div>
+
+          {/* Sources */}
+          {result.sources?.length > 0 && (
+            <div className="sources">
+              {result.sources.slice(0, 3).map((s, i) => (
+                <a key={i} className="source" href={s.url} target="_blank" rel="noopener">
+                  <img src={s.favicon_url} width="12" height="12" onError={(e) => { (e.target as HTMLImageElement).style.display = "none"; }} />
+                  <span>{s.domain}</span>
+                </a>
+              ))}
+            </div>
+          )}
+
+          {/* Footer meta */}
+          <div className="meta">
+            <span>trust {(result.trust_score * 100).toFixed(0)}%</span>
+            <span>·</span>
+            <span>{result.latency_ms?.toFixed(0)}ms</span>
+            {result.cached && <><span>·</span><span>cached</span></>}
+          </div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+
+// CSS injected into the Shadow DOM — complete isolation from host page
+const HOVER_CARD_STYLES = `
+  .card {
+    position: fixed;
+    z-index: 2147483647;
+    width: 340px;
+    background: #0d1117;
+    border: 1px solid #21262d;
+    border-radius: 10px;
+    padding: 14px;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.04);
+    font-family: -apple-system, 'DM Sans', system-ui, sans-serif;
+    font-size: 13px;
+    color: #e6edf3;
+    pointer-events: none;
+  }
+  .header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+  .badge {
+    display: inline-flex; align-items: center; gap: 5px;
+    padding: 3px 10px; border-radius: 20px; font-size: 10px;
+    font-weight: 700; letter-spacing: 0.8px; text-transform: uppercase;
+    background: color-mix(in srgb, var(--accent) 15%, transparent);
+    color: var(--accent);
+    border: 1px solid color-mix(in srgb, var(--accent) 30%, transparent);
+  }
+  .conf { flex-shrink: 0; }
+  .verdict { font-weight: 700; font-size: 14px; margin-bottom: 6px; line-height: 1.3; }
+  .explanation { color: #7d8590; font-size: 12px; line-height: 1.6; margin-bottom: 10px; }
+  .sources { display: flex; flex-direction: column; gap: 4px; margin-bottom: 8px; }
+  .source {
+    display: flex; align-items: center; gap: 6px;
+    padding: 5px 8px; background: #161b22; border-radius: 5px;
+    color: #58a6ff; text-decoration: none; font-size: 11px;
+    pointer-events: all;
+  }
+  .meta {
+    display: flex; gap: 6px; font-size: 10px; color: #484f58;
+    font-family: 'Space Mono', monospace; letter-spacing: 0.3px;
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Main content script entry point
+// ---------------------------------------------------------------------------
+
+export default defineContentScript({
+  matches: [
+    "https://twitter.com/*", "https://x.com/*",
+    "https://www.instagram.com/*", "https://www.youtube.com/*",
+    "https://chat.openai.com/*", "https://claude.ai/*",
+    "https://gemini.google.com/*", "<all_urls>",
+  ],
+  runAt: "document_idle",
+  main: async () => {
+    const platform = detectPlatform();
+
+    // Initialize xxhash-wasm (compiled WASM, sub-microsecond hashing)
+    const { h64ToString: xxhash64 } = await initXxhash();
+
+    const SESSION_ID = crypto.randomUUID();
+    const seenHashes = new Set<string>();  // Client-side dedup ring buffer
+
+    // Flush buffer every 1200ms — avoids layout thrashing from rapid DOM changes
+    const flushBuffer: Map<string, QueuedSegment> = new Map();
+    let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const { enabled, mode } = useExtensionStore.getState();
+    if (!enabled) return;
+
+    function queueSegment(node: Text): void {
+      const text = node.textContent?.trim() ?? "";
+      if (!text) return;
+
+      const hash = xxhash64(text);
+      if (seenHashes.has(hash)) return;  // Already processed this text
+
+      const elementId = `fi-${hash.slice(0, 8)}-${Date.now()}`;
+      flushBuffer.set(hash, { hash, text, node, elementId });
+
+      // Debounced flush
+      if (!flushTimer) {
+        flushTimer = setTimeout(flushSegments, 1200);
+      }
+    }
+
+    async function flushSegments(): void {
+      flushTimer = null;
+      if (flushBuffer.size === 0) return;
+
+      const { enabled, mode } = useExtensionStore.getState();
+      if (!enabled) return;
+
+      const segments = Array.from(flushBuffer.values()).map((s) => {
+        seenHashes.add(s.hash);
+
+        // Prevent unbounded memory growth — prune oldest half when > 5000
+        if (seenHashes.size > 5000) {
+          const arr = Array.from(seenHashes);
+          arr.slice(0, 2500).forEach((h) => seenHashes.delete(h));
+        }
+
+        return {
+          content_hash: s.hash,
+          text: s.text,
+          element_id: s.elementId,
+          word_count: s.text.split(/\s+/).length,
+        };
+      });
+
+      flushBuffer.clear();
+
+      const batch = {
+        session_id: SESSION_ID,
+        platform,
+        segments,
+        sent_at: new Date().toISOString(),
+      };
+
+      // Send to background worker, which holds the WebSocket
+      chrome.runtime.sendMessage({ type: "send_batch", payload: batch });
+    }
+
+    // ---------------------------------------------------------------------------
+    // MutationObserver — watch for new text nodes
+    // ---------------------------------------------------------------------------
+
+    const observer = new MutationObserver((mutations) => {
+      const { enabled } = useExtensionStore.getState();
+      if (!enabled) return;
+
+      for (const mutation of mutations) {
+        if (mutation.type === "childList") {
+          mutation.addedNodes.forEach((node) => {
+            const textNodes = extractTextNodes(node);
+            textNodes.forEach(queueSegment);
+          });
+        } else if (mutation.type === "characterData") {
+          const node = mutation.target as Text;
+          if (isValidTextNode(node)) queueSegment(node);
+        }
+      }
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+
+    // Process existing text on page load
+    extractTextNodes(document.body).forEach(queueSegment);
+
+    // ---------------------------------------------------------------------------
+    // Receive results from background worker
+    // ---------------------------------------------------------------------------
+
+    chrome.runtime.onMessage.addListener((msg) => {
+      if (msg.type === "result" && msg.payload) {
+        const result = msg.payload as AnalysisResult;
+        const { mode } = useExtensionStore.getState();
+        const color = result.color as HighlightColor;
+
+        if (!shouldShowColor(color, mode)) return;
+
+        // Find the text node by element_id stored on the flushBuffer segment
+        // (We need the original node reference — stored in flushBuffer pre-clear)
+        // Fallback: search by matching text content
+        const targetNode = findNodeByHash(result.content_hash);
+        if (targetNode) {
+          applyHighlight(targetNode, result.element_id, color, result);
+        }
+      }
+
+      if (msg.type === "ws_status") {
+        useExtensionStore.getState().setWsStatus(msg.payload.status);
+      }
+    });
+  },
+});
+
+// Node registry for post-flush lookup
+const nodeRegistry = new Map<string, Text>(); // hash → Text node
+
+// Override queueSegment to also register nodes
+// (actual implementation integrates this into the closure above)
+function findNodeByHash(hash: string): Text | undefined {
+  return nodeRegistry.get(hash);
+}

extension/entrypoints/popup.tsx

@@ -0,0 +1,232 @@
+// extension/entrypoints/popup.tsx
+// Extension popup — rendered when the user clicks the extension icon.
+// State: Zustand + chrome.storage.sync (persisted across browser sessions).
+
+import React, { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { motion, AnimatePresence } from "framer-motion";
+import { useExtensionStore, ExtensionMode, WSStatus, COLOR_CONFIG } from "../stores/extensionStore";
+
+// ---------------------------------------------------------------------------
+// Styles (injected as a <style> tag — no build step needed for popup)
+// ---------------------------------------------------------------------------
+const POPUP_STYLES = `
+  :root {
+    --bg: #070b0f; --surface: #0d1117; --surface2: #161b22;
+    --border: #21262d; --text: #e6edf3; --muted: #7d8590;
+    --accent: #58a6ff; --green: #22c55e; --yellow: #eab308;
+    --red: #ef4444; --purple: #a855f7;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    width: 320px; background: var(--bg); color: var(--text);
+    font-family: -apple-system, 'DM Sans', system-ui, sans-serif;
+    font-size: 13px;
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+
+function StatusBadge({ status }: { status: WSStatus }) {
+  const config = {
+    connected:    { color: "#22c55e", label: "Connected",    pulse: true  },
+    connecting:   { color: "#eab308", label: "Connecting…",  pulse: true  },
+    reconnecting: { color: "#eab308", label: "Reconnecting…",pulse: true  },
+    offline:      { color: "#ef4444", label: "Offline",      pulse: false },
+  }[status];
+
+  return (
+    <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+      <div style={{
+        width: 8, height: 8, borderRadius: "50%",
+        background: config.color,
+        boxShadow: config.pulse ? `0 0 8px ${config.color}` : "none",
+        animation: config.pulse ? "pulse 2s infinite" : "none",
+      }} />
+      <span style={{ fontSize: 11, color: "var(--muted)", fontFamily: "monospace" }}>
+        {config.label}
+      </span>
+    </div>
+  );
+}
+
+function Toggle({ checked, onChange }: { checked: boolean; onChange: (v: boolean) => void }) {
+  return (
+    <div
+      onClick={() => onChange(!checked)}
+      style={{
+        width: 44, height: 24, borderRadius: 12, cursor: "pointer",
+        background: checked ? "var(--accent)" : "var(--border)",
+        position: "relative", transition: "background 0.2s",
+        flexShrink: 0,
+      }}
+    >
+      <motion.div
+        animate={{ x: checked ? 22 : 2 }}
+        transition={{ type: "spring", stiffness: 500, damping: 30 }}
+        style={{
+          width: 20, height: 20, borderRadius: 10, background: "#fff",
+          position: "absolute", top: 2,
+          boxShadow: "0 1px 4px rgba(0,0,0,0.3)",
+        }}
+      />
+    </div>
+  );
+}
+
+function ModeCard({ value, current, label, desc, onSelect }: {
+  value: ExtensionMode; current: ExtensionMode;
+  label: string; desc: string; onSelect: () => void;
+}) {
+  const active = value === current;
+  return (
+    <div
+      onClick={onSelect}
+      style={{
+        padding: "10px 12px", borderRadius: 8, cursor: "pointer",
+        border: `1px solid ${active ? "var(--accent)" : "var(--border)"}`,
+        background: active ? "rgba(88,166,255,0.08)" : "var(--surface2)",
+        transition: "all 0.15s", marginBottom: 6,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+        <span style={{ fontWeight: 600, fontSize: 12 }}>{label}</span>
+        {active && <span style={{ fontSize: 10, color: "var(--accent)", fontFamily: "monospace" }}>ACTIVE</span>}
+      </div>
+      <div style={{ color: "var(--muted)", fontSize: 11, marginTop: 3 }}>{desc}</div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main popup component
+// ---------------------------------------------------------------------------
+
+function Popup() {
+  const { enabled, mode, wsStatus, totalAnalyzed, demoMode,
+          setEnabled, setMode } = useExtensionStore();
+
+  // Poll WS status from background worker
+  useEffect(() => {
+    const poll = () => {
+      chrome.runtime.sendMessage({ type: "get_status" }, (resp) => {
+        if (resp?.status) {
+          useExtensionStore.getState().setWsStatus(resp.status);
+        }
+      });
+    };
+    poll();
+    const id = setInterval(poll, 3000);
+    return () => clearInterval(id);
+  }, []);
+
+  const colorCounts = { green: 0, yellow: 0, red: 0, purple: 0 };
+
+  return (
+    <div style={{ padding: 16 }}>
+      <style>{POPUP_STYLES}</style>
+      <style>{`
+        @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+      `}</style>
+
+      {/* Header */}
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: 16 }}>
+        <div>
+          <div style={{ fontFamily: "monospace", fontSize: 11, color: "var(--muted)", letterSpacing: 1 }}>
+            FACT INTELLIGENCE
+          </div>
+          <StatusBadge status={wsStatus} />
+        </div>
+        <Toggle checked={enabled} onChange={setEnabled} />
+      </div>
+
+      {/* Demo mode notice */}
+      {demoMode && (
+        <div style={{
+          padding: "8px 10px", background: "rgba(234,179,8,0.08)",
+          border: "1px solid rgba(234,179,8,0.2)", borderRadius: 6,
+          fontSize: 11, color: "#eab308", marginBottom: 12,
+        }}>
+          ⚠ Demo mode — add API keys for live LLM analysis
+        </div>
+      )}
+
+      <AnimatePresence>
+        {enabled && (
+          <motion.div
+            initial={{ opacity: 0, height: 0 }}
+            animate={{ opacity: 1, height: "auto" }}
+            exit={{ opacity: 0, height: 0 }}
+          >
+            {/* Mode selector */}
+            <div style={{ marginBottom: 16 }}>
+              <div style={{ fontFamily: "monospace", fontSize: 10, color: "var(--muted)",
+                           letterSpacing: 1, textTransform: "uppercase", marginBottom: 8 }}>
+                highlight mode
+              </div>
+              <ModeCard value="minimal" current={mode} onSelect={() => setMode("minimal")}
+                label="Minimal" desc="Only debunked (red) and AI hallucinations (purple)" />
+              <ModeCard value="normal" current={mode} onSelect={() => setMode("normal")}
+                label="Normal (recommended)" desc="Red, purple, and unverified (yellow)" />
+              <ModeCard value="advanced" current={mode} onSelect={() => setMode("advanced")}
+                label="Advanced" desc="Full factual landscape including verified (green)" />
+            </div>
+
+            {/* Color legend */}
+            <div style={{ marginBottom: 16 }}>
+              <div style={{ fontFamily: "monospace", fontSize: 10, color: "var(--muted)",
+                           letterSpacing: 1, textTransform: "uppercase", marginBottom: 8 }}>
+                color legend
+              </div>
+              {(Object.entries(COLOR_CONFIG) as [string, typeof COLOR_CONFIG.green][]).map(([k, v]) => (
+                <div key={k} style={{ display: "flex", alignItems: "center", gap: 8, marginBottom: 5 }}>
+                  <div style={{ width: 12, height: 12, borderRadius: 3, background: v.hex, flexShrink: 0 }} />
+                  <span style={{ color: v.hex, fontSize: 11, fontWeight: 600 }}>{v.label}</span>
+                </div>
+              ))}
+            </div>
+
+            {/* Stats */}
+            <div style={{
+              padding: "10px 12px", background: "var(--surface2)",
+              border: "1px solid var(--border)", borderRadius: 8,
+              display: "flex", justifyContent: "space-between",
+            }}>
+              <div style={{ textAlign: "center" }}>
+                <div style={{ fontFamily: "monospace", fontSize: 18, fontWeight: 700, color: "var(--accent)" }}>
+                  {totalAnalyzed}
+                </div>
+                <div style={{ fontSize: 10, color: "var(--muted)", textTransform: "uppercase", letterSpacing: 0.8 }}>
+                  analyzed
+                </div>
+              </div>
+              <div style={{ width: 1, background: "var(--border)" }} />
+              <div style={{ textAlign: "center" }}>
+                <div style={{ fontFamily: "monospace", fontSize: 18, fontWeight: 700, color: "var(--muted)" }}>
+                  {wsStatus === "connected" ? "●" : "○"}
+                </div>
+                <div style={{ fontSize: 10, color: "var(--muted)", textTransform: "uppercase", letterSpacing: 0.8 }}>
+                  engine
+                </div>
+              </div>
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {/* Footer */}
+      <div style={{
+        marginTop: 14, paddingTop: 10, borderTop: "1px solid var(--border)",
+        fontFamily: "monospace", fontSize: 10, color: "var(--muted)", textAlign: "center",
+      }}>
+        v1.0.0 · WXT + FastAPI + Qdrant + Memgraph
+      </div>
+    </div>
+  );
+}
+
+// Mount
+const root = document.getElementById("root");
+if (root) createRoot(root).render(<Popup />);

extension/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "fact-intelligence-extension",
+  "version": "1.0.0",
+  "description": "Omnichannel fact-checking and AI hallucination detection browser extension",
+  "private": true,
+  "scripts": {
+    "dev": "wxt dev",
+    "dev:chrome": "wxt dev --browser chrome",
+    "dev:firefox": "wxt dev --browser firefox",
+    "build": "wxt build",
+    "build:chrome": "wxt build --browser chrome",
+    "build:firefox": "wxt build --browser firefox",
+    "build:all": "wxt build --browser chrome && wxt build --browser firefox",
+    "zip": "wxt zip",
+    "type-check": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "framer-motion": "^11.15.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "xxhash-wasm": "^1.0.2",
+    "zustand": "^5.0.2"
+  },
+  "devDependencies": {
+    "@types/chrome": "^0.0.287",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@wxt-dev/module-react": "^1.1.0",
+    "typescript": "^5.7.2",
+    "wxt": "^0.19.0"
+  }
+}

extension/stores/extensionStore.ts

@@ -0,0 +1,145 @@
+// extension/stores/extensionStore.ts
+// Zustand store with chrome.storage.sync persistence layer.
+// State is shared across popup, background, and content script contexts.
+
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+
+export type HighlightColor = "green" | "yellow" | "red" | "purple";
+export type ExtensionMode = "minimal" | "normal" | "advanced";
+export type WSStatus = "connected" | "connecting" | "reconnecting" | "offline";
+
+export interface AnalysisResult {
+  element_id: string;
+  content_hash: string;
+  platform: string;
+  color: HighlightColor;
+  confidence: number;
+  verdict_label: string;
+  explanation: string;
+  sources: Array<{
+    url: string;
+    domain: string;
+    favicon_url: string;
+    snippet: string;
+  }>;
+  trust_score: number;
+  velocity: number;
+  has_community_note: boolean;
+  latency_ms: number;
+  cached: boolean;
+  timestamp: string;
+}
+
+interface ExtensionState {
+  // User preferences (persisted to chrome.storage.sync)
+  enabled: boolean;
+  mode: ExtensionMode;
+
+  // Runtime state (not persisted)
+  wsStatus: WSStatus;
+  pendingCount: number;
+  totalAnalyzed: number;
+  demoMode: boolean;
+
+  // Actions
+  setEnabled: (v: boolean) => void;
+  setMode: (m: ExtensionMode) => void;
+  setWsStatus: (s: WSStatus) => void;
+  incrementPending: () => void;
+  decrementPending: () => void;
+  incrementAnalyzed: () => void;
+  setDemoMode: (v: boolean) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Chrome storage sync helpers
+// ---------------------------------------------------------------------------
+const STORAGE_KEY = "fact_intelligence_prefs";
+
+async function loadFromStorage(): Promise<Partial<ExtensionState>> {
+  return new Promise((resolve) => {
+    if (typeof chrome === "undefined" || !chrome.storage) {
+      resolve({});
+      return;
+    }
+    chrome.storage.sync.get([STORAGE_KEY], (result) => {
+      resolve(result[STORAGE_KEY] ?? {});
+    });
+  });
+}
+
+async function saveToStorage(prefs: { enabled: boolean; mode: ExtensionMode }) {
+  if (typeof chrome === "undefined" || !chrome.storage) return;
+  chrome.storage.sync.set({ [STORAGE_KEY]: prefs });
+}
+
+// ---------------------------------------------------------------------------
+// Store definition
+// ---------------------------------------------------------------------------
+export const useExtensionStore = create<ExtensionState>()(
+  subscribeWithSelector((set, get) => ({
+    enabled: true,
+    mode: "normal",
+    wsStatus: "connecting",
+    pendingCount: 0,
+    totalAnalyzed: 0,
+    demoMode: false,
+
+    setEnabled: (v) => {
+      set({ enabled: v });
+      saveToStorage({ enabled: v, mode: get().mode });
+    },
+    setMode: (m) => {
+      set({ mode: m });
+      saveToStorage({ enabled: get().enabled, mode: m });
+    },
+    setWsStatus: (s) => set({ wsStatus: s }),
+    incrementPending: () => set((s) => ({ pendingCount: s.pendingCount + 1 })),
+    decrementPending: () =>
+      set((s) => ({ pendingCount: Math.max(0, s.pendingCount - 1) })),
+    incrementAnalyzed: () =>
+      set((s) => ({ totalAnalyzed: s.totalAnalyzed + 1 })),
+    setDemoMode: (v) => set({ demoMode: v }),
+  }))
+);
+
+// Hydrate from chrome.storage.sync on module load
+loadFromStorage().then((saved) => {
+  if (saved.enabled !== undefined) {
+    useExtensionStore.setState({ enabled: saved.enabled as boolean });
+  }
+  if (saved.mode !== undefined) {
+    useExtensionStore.setState({ mode: saved.mode as ExtensionMode });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Mode-based color filter logic
+// ---------------------------------------------------------------------------
+export function shouldShowColor(
+  color: HighlightColor,
+  mode: ExtensionMode
+): boolean {
+  switch (mode) {
+    case "minimal":
+      // Only show definitive threats — don't add noise for users who want minimal
+      return color === "red" || color === "purple";
+    case "normal":
+      // Default: skip low-confidence green confirmations
+      return color === "red" || color === "purple" || color === "yellow";
+    case "advanced":
+      // Full factual landscape including green corroborations
+      return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Color display config
+// ---------------------------------------------------------------------------
+export const COLOR_CONFIG = {
+  green:  { hex: "#22c55e", opacity: 0.12, label: "Verified",         icon: "✓" },
+  yellow: { hex: "#eab308", opacity: 0.14, label: "Unverified",       icon: "⚠" },
+  red:    { hex: "#ef4444", opacity: 0.16, label: "Debunked",         icon: "✗" },
+  purple: { hex: "#a855f7", opacity: 0.15, label: "AI Hallucination", icon: "◈" },
+} as const;

extension/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".wxt/types/**/*.d.ts"],
+  "exclude": ["node_modules", ".output"]
+}

extension/wxt.config.ts

@@ -0,0 +1,52 @@
+// extension/wxt.config.ts
+// WXT framework configuration — replaces raw Manifest V3 boilerplate.
+// Provides HMR, multi-browser compatibility (Chrome/Firefox/Edge/Arc),
+// TypeScript-first entrypoints, Vite under the hood.
+
+import { defineConfig } from "wxt";
+
+export default defineConfig({
+  extensionApi: "chrome",
+  modules: ["@wxt-dev/module-react"],
+
+  vite: () => ({
+    define: {
+      // Injected at build time — change this to your cloudflared tunnel URL
+      __WS_URL__: JSON.stringify(
+        process.env.WS_URL || "wss://fact-engine.your-domain.workers.dev"
+      ),
+    },
+  }),
+
+  manifest: {
+    name: "Fact & Hallucination Intelligence",
+    description:
+      "Real-time omnichannel fact-checking and AI hallucination detection",
+    version: "1.0.0",
+    permissions: [
+      "storage",      // chrome.storage.sync for user preferences
+      "tabs",         // send messages to content scripts
+      "activeTab",
+    ],
+    host_permissions: [
+      "https://twitter.com/*",
+      "https://x.com/*",
+      "https://www.instagram.com/*",
+      "https://www.youtube.com/*",
+      "https://chat.openai.com/*",
+      "https://claude.ai/*",
+      "https://gemini.google.com/*",
+      "*://*/*",     // Covers news sites — restrict in production
+    ],
+    content_security_policy: {
+      extension_pages:
+        "script-src 'self'; object-src 'self'; connect-src wss: https:",
+    },
+    icons: {
+      "16": "icon/16.png",
+      "32": "icon/32.png",
+      "48": "icon/48.png",
+      "128": "icon/128.png",
+    },
+  },
+});

infra/tunnel_setup.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# tunnel_setup.sh — Cloudflare Tunnel setup for the Fact Intelligence backend.
+#
+# What this does:
+#   1. Installs the cloudflared binary (Linux/macOS)
+#   2. Authenticates with your Cloudflare account
+#   3. Creates a named tunnel pointing to the FastAPI backend (localhost:7860)
+#   4. Configures DNS routing: wss://fact-engine.<your-domain>.workers.dev
+#   5. Runs the tunnel as a systemd service (optional)
+#
+# Usage:
+#   chmod +x tunnel_setup.sh
+#   DOMAIN=your-domain.com ./tunnel_setup.sh
+#
+# After running, copy the tunnel URL into extension/wxt.config.ts __WS_URL__
+
+set -euo pipefail
+
+DOMAIN="${DOMAIN:-your-domain.com}"
+TUNNEL_NAME="fact-intelligence"
+BACKEND_PORT=7860
+CONFIG_DIR="$HOME/.cloudflared"
+
+echo "=== Cloudflare Tunnel Setup for Fact Intelligence System ==="
+echo "Domain: $DOMAIN"
+echo "Tunnel: $TUNNEL_NAME"
+echo ""
+
+# ---------------------------------------------------------------------------
+# 1. Install cloudflared
+# ---------------------------------------------------------------------------
+install_cloudflared() {
+  if command -v cloudflared &>/dev/null; then
+    echo "[✓] cloudflared already installed: $(cloudflared --version)"
+    return
+  fi
+
+  echo "[→] Installing cloudflared..."
+  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+  ARCH=$(uname -m)
+
+  case "$OS" in
+    linux)
+      case "$ARCH" in
+        x86_64)  PKG="cloudflared-linux-amd64.deb" ;;
+        aarch64) PKG="cloudflared-linux-arm64.deb"  ;;
+        *)       echo "Unsupported arch: $ARCH"; exit 1 ;;
+      esac
+      curl -fsSL "https://github.com/cloudflare/cloudflared/releases/latest/download/$PKG" -o /tmp/cloudflared.deb
+      sudo dpkg -i /tmp/cloudflared.deb
+      ;;
+    darwin)
+      brew install cloudflare/cloudflare/cloudflared
+      ;;
+    *)
+      echo "Unsupported OS: $OS. Install cloudflared manually from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/"
+      exit 1
+      ;;
+  esac
+  echo "[✓] cloudflared installed"
+}
+
+# ---------------------------------------------------------------------------
+# 2. Authenticate (opens browser for Cloudflare login)
+# ---------------------------------------------------------------------------
+authenticate() {
+  if [ -f "$CONFIG_DIR/cert.pem" ]; then
+    echo "[✓] Already authenticated (cert.pem found)"
+    return
+  fi
+  echo "[→] Opening browser for Cloudflare authentication..."
+  cloudflared tunnel login
+}
+
+# ---------------------------------------------------------------------------
+# 3. Create the tunnel
+# ---------------------------------------------------------------------------
+create_tunnel() {
+  if cloudflared tunnel list 2>/dev/null | grep -q "$TUNNEL_NAME"; then
+    echo "[✓] Tunnel '$TUNNEL_NAME' already exists"
+    TUNNEL_ID=$(cloudflared tunnel list | grep "$TUNNEL_NAME" | awk '{print $1}')
+  else
+    echo "[→] Creating tunnel '$TUNNEL_NAME'..."
+    cloudflared tunnel create "$TUNNEL_NAME"
+    TUNNEL_ID=$(cloudflared tunnel list | grep "$TUNNEL_NAME" | awk '{print $1}')
+    echo "[✓] Created tunnel ID: $TUNNEL_ID"
+  fi
+  echo "TUNNEL_ID=$TUNNEL_ID"
+}
+
+# ---------------------------------------------------------------------------
+# 4. Write tunnel configuration
+# ---------------------------------------------------------------------------
+write_config() {
+  mkdir -p "$CONFIG_DIR"
+  cat > "$CONFIG_DIR/config.yml" << EOF
+tunnel: $TUNNEL_NAME
+credentials-file: $CONFIG_DIR/$TUNNEL_ID.json
+
+ingress:
+  # WebSocket endpoint — extension connects here
+  - hostname: fact-engine.$DOMAIN
+    service: http://localhost:$BACKEND_PORT
+    originRequest:
+      noTLSVerify: false
+      connectTimeout: 30s
+
+  # Catch-all (required by cloudflared)
+  - service: http_status:404
+
+warp-routing:
+  enabled: false
+EOF
+  echo "[✓] Config written to $CONFIG_DIR/config.yml"
+}
+
+# ---------------------------------------------------------------------------
+# 5. Create DNS record
+# ---------------------------------------------------------------------------
+setup_dns() {
+  echo "[→] Creating DNS CNAME: fact-engine.$DOMAIN → $TUNNEL_NAME.cfargotunnel.com"
+  cloudflared tunnel route dns "$TUNNEL_NAME" "fact-engine.$DOMAIN" || \
+    echo "[!] DNS route already exists or failed — check Cloudflare dashboard"
+  echo "[✓] DNS configured"
+}
+
+# ---------------------------------------------------------------------------
+# 6. Systemd service (Linux only)
+# ---------------------------------------------------------------------------
+setup_systemd() {
+  if [ "$(uname -s)" != "Linux" ]; then
+    echo "[!] Skipping systemd setup (not Linux)"
+    return
+  fi
+
+  sudo tee /etc/systemd/system/cloudflared-fact.service > /dev/null << EOF
+[Unit]
+Description=Cloudflare Tunnel — Fact Intelligence System
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=$USER
+ExecStart=$(command -v cloudflared) tunnel --config $CONFIG_DIR/config.yml run $TUNNEL_NAME
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+  sudo systemctl daemon-reload
+  sudo systemctl enable cloudflared-fact
+  sudo systemctl start cloudflared-fact
+  echo "[✓] Systemd service started: cloudflared-fact"
+}
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+install_cloudflared
+authenticate
+create_tunnel
+write_config
+setup_dns
+setup_systemd
+
+echo ""
+echo "=== Setup complete! ==="
+echo ""
+echo "WebSocket URL for the extension:"
+echo "  wss://fact-engine.$DOMAIN/ws/{session_id}"
+echo ""
+echo "Update extension/wxt.config.ts:"
+echo "  __WS_URL__: 'wss://fact-engine.$DOMAIN/ws'"
+echo ""
+echo "Test the tunnel:"
+echo "  curl https://fact-engine.$DOMAIN/health"
+echo ""