| --- |
| title: Omnichannel Fact & Hallucination Intelligence System |
| emoji: 🔍 |
| colorFrom: blue |
| colorTo: purple |
| sdk: docker |
| pinned: false |
| license: mit |
| app_port: 7860 |
| --- |
| |
| # 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. |
|
|
