Initial commit: InfoClassifier project

.env.example

@@ -0,0 +1,34 @@
+# Copy this file to .env and fill in your keys.
+# Never commit .env to version control.
+
+# Search backends (at least one required for data collection)
+SERPAPI_KEY=d6e47f7df7bd5cadb62db480f00f4c8031cf1b7910915631fefa4c154c75211e
+NEWSAPI_KEY=
+BRAVE_SEARCH_KEY=
+GOOGLE_FACTCHECK_KEY=
+
+# Redis (used for scenario + session caching)
+REDIS_URL=redis://localhost:6379
+CACHE_TTL_SECONDS=86400
+SESSION_TTL_SECONDS=3600
+
+# LLM for inference.py (OpenAI-compatible)
+HF_TOKEN=
+OPENAI_API_KEY=          # alias for HF_TOKEN
+MODEL_NAME=gpt-4o
+API_BASE_URL=https://api.openai.com/v1
+
+# Environment server
+ENV_SERVER_URL=http://localhost:8000
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=info
+
+# Data collector
+MAX_SOURCES_PER_CLAIM=8
+REQUEST_TIMEOUT=10
+
+# Config files (override if you move them)
+RELIABILITY_CONFIG=domain_reliability.yaml
+REWARD_CONFIG=reward_config.yaml
+EXPLANATION_CONFIG=explanation_templates.yaml

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# HuggingFace model cache
+.cache/
+
+# Environment variables
+.env
+
+# macOS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/

Dockerfile

@@ -0,0 +1,90 @@
+# =============================================================================
+# Dockerfile  v1.2.0
+# Multi-stage build — slim production image.
+#
+# Build:  docker build -t info-integrity-env .
+# Run:    docker run --env-file .env -p 7860:7860 info-integrity-env
+#
+# Evaluation path (no external services needed):
+#   docker run --env-file .env info-integrity-env \
+#     python inference.py --benchmark --out /tmp/results.json
+#
+# Required .env keys for the API server:
+#   HF_TOKEN                       (for inference.py)
+#   MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+#   API_BASE_URL=https://router.huggingface.co/v1
+#
+# Optional (only needed for live data collection via /collect):
+#   SERPAPI_KEY / NEWSAPI_KEY / BRAVE_SEARCH_KEY / GOOGLE_FACTCHECK_KEY
+#   REDIS_URL=redis://redis:6379
+# =============================================================================
+
+# ---- Stage 1: builder ----
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+ && pip install --no-cache-dir -r requirements.txt
+
+# ---- Stage 2: runtime ----
+FROM python:3.11-slim AS runtime
+
+WORKDIR /app
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application source
+COPY models.py            ./models.py
+COPY environment.py       ./environment.py
+COPY reward.py            ./reward.py
+COPY explainability.py    ./explainability.py
+COPY data_collector.py    ./data_collector.py
+COPY app.py             ./app.py
+COPY server.py          ./server.py
+COPY inference.py         ./inference.py
+COPY reward_config.yaml   ./reward_config.yaml
+COPY openenv.yaml         ./openenv.yaml
+COPY README.md            ./README.md
+
+# Copy optional config files if they exist
+COPY domain_reliability.yaml* ./
+
+# Copy tasks package (graders + registry + deterministic scenario datasets)
+COPY tasks/               ./tasks/
+
+# Non-root user for security
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Environment defaults (override via --env-file or -e flags)
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    HOST=0.0.0.0 \
+    PORT=7860 \
+    LOG_LEVEL=info \
+    REDIS_URL=redis://localhost:6379 \
+    SESSION_TTL_SECONDS=3600 \
+    CACHE_TTL_SECONDS=86400 \
+    MAX_SOURCES_PER_CLAIM=8 \
+    REQUEST_TIMEOUT=10 \
+    BENCHMARK_SEED=42 \
+    MAX_STEPS=20 \
+    GRADIO_ANALYTICS_ENABLED=false
+
+EXPOSE 7860
+
+# Use Python's built-in urllib — no curl dependency needed in runtime
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health', timeout=8)"
+
+# Default: start the API server
+# Override for benchmark: docker run ... python inference.py --benchmark
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,359 @@
+---
+title: InformationIntegrityEnv
+emoji: 🔍
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: 6.11.0
+app_file: app.py
+pinned: false
+license: mit
+tags:
+  - openenv
+  - content-moderation
+  - rl-environment
+  - agent-benchmark
+---
+
+# InformationIntegrityEnv
+
+A **deterministic, benchmarkable OpenEnv environment** for evaluating LLM agents on reasoning-based content moderation.
+
+Agents must verify claims, weigh conflicting evidence, and make explainable moderation decisions (`allow` / `flag` / `remove`). Three difficulty tiers — easy, medium, hard — provide 15 fully static scenarios that run completely offline.
+
+---
+
+## Architecture
+
+```
+tasks/
+  easy/scenarios.json     ← 5 static scenarios (clear-cut misinformation)
+  medium/scenarios.json   ← 5 static scenarios (misleading / mixed evidence)
+  hard/scenarios.json     ← 5 static scenarios (conflicting evidence, nuanced)
+  graders.py              ← EasyGrader / MediumGrader / HardGrader
+  registry.py             ← TASKS["easy"] / TASKS["medium"] / TASKS["hard"]
+        │
+        ▼
+InformationIntegrityEnv         (environment.py)
+  reset(difficulty, scenario_id) → Observation
+  step(action)                   → (Observation, Reward, done, info)
+  state()                        → full debug state
+        │
+  ┌─────┴──────┐
+  │            │
+inference.py   server.py
+(benchmark     (FastAPI
+ agent loop)    REST API)
+```
+
+No external API calls occur during evaluation. `DataCollector` is only used to build/refresh datasets.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Set API keys (for the LLM agent — not needed for just the server)
+
+```bash
+export HF_TOKEN=sk-...          # or OPENAI_API_KEY
+export MODEL_NAME=gpt-4o
+export API_BASE_URL=https://api.openai.com/v1
+```
+
+### 3. Run the full benchmark
+
+```bash
+python inference.py --benchmark --out results.json
+```
+
+This loops over all 15 scenarios (5 per difficulty) and prints:
+
+```
+[START] episode=E01 difficulty=easy claims=1 sources=5
+[STEP]  step=1 action=check_source reward=+0.200 total=+0.200 done=False ...
+[STEP]  step=2 action=verify_claim  reward=+0.200 total=+0.400 done=False ...
+[STEP]  step=3 action=decide        reward=+1.000 total=+1.400 done=True  ...
+[END]   episode=E01 steps=3 decision=remove total_reward=+1.4000 grader_score=0.8750
+
+...
+
+difficulty=easy   avg_score=0.7800  avg_reward=1.2000  n=5
+difficulty=medium avg_score=0.6300  avg_reward=0.9000  n=5
+difficulty=hard   avg_score=0.5200  avg_reward=0.6500  n=5
+Difficulty tiers well separated: easy > medium > hard ✓
+```
+
+### 4. Single episode (local, no server)
+
+```bash
+# Random scenario from medium dataset
+python inference.py --local --difficulty medium
+
+# Specific scenario by index
+python inference.py --local --difficulty hard --scenario-id 2
+
+# Specific scenario by id
+python inference.py --local --difficulty easy --scenario-id easy_001
+
+# From a custom JSON file (DataCollector output)
+python inference.py --local --scenario my_scenario.json
+```
+
+### 5. Start the API server
+
+```bash
+python server.py
+# or
+uvicorn server:app --reload
+```
+
+---
+
+## Action Space
+
+| Action | Required fields | Description |
+|--------|----------------|-------------|
+| `verify_claim` | `claim_id` | Investigate a claim; returns true / false / partially_true / unknown |
+| `check_source` | `source_id` | Read a source; returns title, text, stance, reliability |
+| `decide` | `decision` | Final call: `allow` / `flag` / `remove` — ends episode |
+
+All actions accept an optional `reasoning` string (logged, not graded).
+
+**Minimum evidence required before deciding** (or premature penalty applies):
+- ≥ 1 claim verified
+- ≥ 2 sources checked
+
+---
+
+## Observation Space
+
+```json
+{
+  "content": "The post text under review",
+  "claims": [
+    {"id": "claim_001", "text": "...", "verification_status": "unverified", "confidence": 0.0}
+  ],
+  "available_sources": [
+    {"id": "src_001", "title": "...", "text": "...", "url": "...",
+     "stance": "contradicting", "reliability": 0.97, "source_type": "official"}
+  ],
+  "interaction_history": [],
+  "status_flags": {
+    "decision_made": false,
+    "sufficient_evidence": false,
+    "premature_decision": false,
+    "redundant_actions": 0,
+    "max_steps_reached": false
+  },
+  "step_count": 0,
+  "task_difficulty": "medium",
+  "episode_id": "uuid"
+}
+```
+
+---
+
+## Reward Function
+
+| Component | Value | Trigger |
+|-----------|-------|---------|
+| Verify claim | +0.20 | Per unique claim verified |
+| Check source | +0.20 | Per unique source checked |
+| Multi-source bonus | +0.20 | When ≥ 3 unique sources checked |
+| Correct decision | +1.00 | Exact ground truth match |
+| Partial decision | +0.50 | One tier off (flag↔remove, flag↔allow) |
+| Premature decision | −0.50 | Deciding before sufficient evidence |
+| Redundant action | −0.10 | Re-checking same claim/source |
+| Inefficiency | −0.05 | Per step beyond efficient threshold |
+| Over-aggression | −0.30 | `remove` when ground truth is `allow`/`flag` |
+
+Total clipped to `[-2.0, +2.0]`. All values configurable in `reward_config.yaml`.
+
+---
+
+## Grader Scoring
+
+Each episode is scored `[0.0, 1.0]` across four dimensions:
+
+| Dimension | Easy | Medium | Hard |
+|-----------|------|--------|------|
+| Decision correctness | 50% | 35% | 30% |
+| Evidence breadth | 25% | 35% | 30% |
+| Reasoning depth | 15% | 20% | 30% |
+| Efficiency | 10% | 10% | 10% |
+
+---
+
+## Task Datasets
+
+### Easy (5 scenarios)
+Clear-cut false claims contradicted by multiple authoritative sources (WHO, CDC, NASA, FDA).
+Ground truth: 3× remove, 1× flag, 1× allow.
+
+| ID | Topic | Ground Truth |
+|----|-------|-------------|
+| easy_001 | Bleach cures COVID | remove |
+| easy_002 | NASA fabricated climate data | remove |
+| easy_003 | mRNA vaccines alter DNA | remove |
+| easy_004 | Sydney is Australia's capital | flag |
+| easy_005 | Webb telescope early universe | allow |
+
+### Medium (5 scenarios)
+Partially true or misleadingly framed content. Mixed evidence requires weighing.
+Ground truth: 4× flag, 1× allow.
+
+| ID | Topic | Ground Truth |
+|----|-------|-------------|
+| medium_001 | Sugar more addictive than cocaine | flag |
+| medium_002 | Real unemployment is 20%+ | flag |
+| medium_003 | AI will eliminate 85M jobs | flag |
+| medium_004 | Pharma knew OxyContin was addictive | allow |
+| medium_005 | Facebook hid teen mental health data | flag |
+
+### Hard (5 scenarios)
+Conflicting credible evidence, genuinely contested claims, contested policy debates.
+Ground truth: 5× flag.
+
+| ID | Topic | Ground Truth |
+|----|-------|-------------|
+| hard_001 | NATO provoked Ukraine invasion | flag |
+| hard_002 | Lockdowns killed more than COVID | flag |
+| hard_003 | SEC crackdown is banking conspiracy | flag |
+| hard_004 | AI poses extinction-level risk | flag |
+| hard_005 | British colonialism net beneficial | flag |
+
+---
+
+## API Reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Liveness probe |
+| GET | `/tasks` | List all available scenario datasets |
+| POST | `/reset` | Start a new episode |
+| POST | `/step` | Submit one action |
+| GET | `/state/{session_id}` | Full internal state (debug/audit) |
+| GET | `/scenario/{session_id}` | Scenario metadata (no ground truth) |
+| DELETE | `/session/{session_id}` | End session and free memory |
+| POST | `/collect` | Build a live scenario via DataCollector (dataset creation only) |
+
+### Reset — evaluation path (no DataCollector needed)
+
+```bash
+# Random scenario from easy dataset
+curl -X POST http://localhost:8000/reset \
+  -H "Content-Type: application/json" \
+  -d '{"difficulty": "easy"}'
+
+# Specific scenario by index
+curl -X POST http://localhost:8000/reset \
+  -d '{"difficulty": "medium", "scenario_id": 2}'
+
+# Specific scenario by id
+curl -X POST http://localhost:8000/reset \
+  -d '{"difficulty": "hard", "scenario_id": "hard_001"}'
+```
+
+### Full episode example
+
+```bash
+SESSION=$(curl -s -X POST http://localhost:8000/reset \
+  -H "Content-Type: application/json" \
+  -d '{"difficulty": "easy"}' | jq -r .session_id)
+
+# Check a source
+curl -X POST http://localhost:8000/step \
+  -d "{\"session_id\": \"$SESSION\", \"action\": {\"type\": \"check_source\", \"source_id\": \"src_001\"}}"
+
+# Verify a claim
+curl -X POST http://localhost:8000/step \
+  -d "{\"session_id\": \"$SESSION\", \"action\": {\"type\": \"verify_claim\", \"claim_id\": \"claim_001\"}}"
+
+# Decide
+curl -X POST http://localhost:8000/step \
+  -d "{\"session_id\": \"$SESSION\", \"action\": {\"type\": \"decide\", \"decision\": \"remove\"}}"
+```
+
+---
+
+## Docker
+
+### Server (default)
+
+```bash
+docker build -t info-integrity-env .
+docker run --env-file .env -p 8000:8000 info-integrity-env
+```
+
+### Benchmark (offline — no external services needed)
+
+```bash
+docker run --env-file .env info-integrity-env \
+  python inference.py --benchmark --out /tmp/results.json
+```
+
+### Full stack with Redis (for live data collection)
+
+```bash
+docker compose up --build
+```
+
+---
+
+## Baseline Results
+
+| Difficulty | Avg Grader Score | Avg Reward | Decision Accuracy |
+|-----------|-----------------|------------|-----------------|
+| Easy | ~0.78 | ~1.20 | ~85% |
+| Medium | ~0.63 | ~0.90 | ~70% |
+| Hard | ~0.52 | ~0.65 | ~55% |
+
+*Results vary by LLM. Scores above from `gpt-4o` with temperature=0.*
+
+---
+
+## Extending the Environment
+
+| File | What to change |
+|------|---------------|
+| `tasks/{difficulty}/scenarios.json` | Add or edit scenarios (run `openenv validate` after) |
+| `reward_config.yaml` | Tune reward/penalty magnitudes |
+| `tasks/graders.py` | Register custom graders: `GraderFactory.register("hard_v2", MyGrader)` |
+| `data_collector.py` | Add new search backends via `SearchBackend` ABC |
+| `domain_reliability.yaml` | Add trusted domains with custom reliability scores |
+
+---
+
+## Project Structure
+
+```
+├── models.py                    Pydantic models (Observation, Action, Reward, Scenario, ...)
+├── environment.py               InformationIntegrityEnv (OpenEnv core)
+├── reward.py                    Configurable dense reward function
+├── explainability.py            Structured reasoning + template-based explanation
+├── data_collector.py            Multi-backend data collection (dataset creation only)
+├── inference.py                 Benchmark agent + single-episode runner
+├── server.py                    FastAPI server (HF Space / Docker)
+├── tasks/
+│   ├── __init__.py
+│   ├── graders.py               Easy / Medium / Hard deterministic graders
+│   ├── registry.py              TASKS registry — lazy-loads scenario datasets
+│   ├── easy/
+│   │   └── scenarios.json       5 easy scenarios
+│   ├── medium/
+│   │   └── scenarios.json       5 medium scenarios
+│   └── hard/
+│       └── scenarios.json       5 hard scenarios
+├── openenv.yaml                 OpenEnv v1.1.0 specification
+├── reward_config.yaml           Reward magnitudes (runtime-configurable)
+├── domain_reliability.yaml      Domain trust scores for DataCollector
+├── Dockerfile                   Production container
+├── docker-compose.yml           Local dev stack (server + Redis)
+└── requirements.txt
+```

app.py

@@ -0,0 +1,41 @@
+"""
+app.py
+======
+HuggingFace Spaces entry point (Gradio SDK).
+
+Mounts the FastAPI OpenEnv server and exposes a minimal Gradio UI
+so the Space is recognised as a Gradio app while all OpenEnv HTTP
+endpoints (/reset, /step, /state, /health) remain accessible.
+"""
+
+import uvicorn
+import gradio as gr
+from server import app as fastapi_app
+
+# ---------------------------------------------------------------------------
+# Minimal Gradio demo (satisfies HF Spaces Gradio SDK requirement)
+# ---------------------------------------------------------------------------
+
+def run_health_check():
+    return "InformationIntegrityEnv is running. Use /reset, /step, /health endpoints."
+
+demo = gr.Interface(
+    fn=run_health_check,
+    inputs=[],
+    outputs=gr.Textbox(label="Status"),
+    title="InformationIntegrityEnv",
+    description=(
+        "OpenEnv-compatible deterministic benchmark for reasoning-based content moderation.\n\n"
+        "**API Endpoints:**\n"
+        "- `POST /reset` — start episode (`{\"difficulty\": \"easy|medium|hard\"}`)\n"
+        "- `POST /step` — submit action\n"
+        "- `GET  /health` — liveness check\n"
+        "- `GET  /tasks` — list available scenarios"
+    ),
+)
+
+# Mount Gradio onto the FastAPI app so both are served on the same port
+app = gr.mount_gradio_app(fastapi_app, demo, path="/ui")
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

data_collector.py

@@ -0,0 +1,1229 @@
+"""
+data_collector.py
+=================
+Production data-collection pipeline for InformationIntegrity OpenEnv.
+
+Takes any claim string(s), fetches real evidence from multiple search/news
+backends, scores source reliability, classifies stance, and caches results
+in Redis.  The output is a Scenario JSON ready for the environment.
+
+Backends (all optional — falls back gracefully):
+  1. SerpAPI          SERPAPI_KEY
+  2. NewsAPI          NEWSAPI_KEY
+  3. Brave Search     BRAVE_SEARCH_KEY
+  4. Google Fact Check GOOGLE_FACTCHECK_KEY
+  5. DuckDuckGo HTML  (no key, rate-limited fallback)
+
+Environment variables:
+  SERPAPI_KEY
+  NEWSAPI_KEY
+  BRAVE_SEARCH_KEY
+  GOOGLE_FACTCHECK_KEY
+  REDIS_URL              (default: redis://localhost:6379)
+  CACHE_TTL_SECONDS      (default: 86400 — 24h)
+  RELIABILITY_CONFIG     (default: domain_reliability.yaml)
+  MAX_SOURCES_PER_CLAIM  (default: 8)
+  REQUEST_TIMEOUT        (default: 10s)
+
+Usage:
+    python data_collector.py --claims "Claim one" "Claim two" \
+                             --content "The original post text" \
+                             --difficulty medium \
+                             --out scenario.json
+
+    from data_collector import DataCollector, CollectionRequest
+    collector = DataCollector()
+    scenario  = collector.collect(CollectionRequest(
+        content="Post text",
+        claims=["Claim A"],
+        difficulty="medium",
+    ))
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import re
+import time
+import urllib.parse
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+import fnmatch
+import requests
+import yaml
+
+# Load .env BEFORE any os.getenv() calls so API keys are available
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv not installed; rely on shell environment
+
+try:
+    from retrieval import QueryRewriter as _QueryRewriter
+    _QUERY_REWRITER = _QueryRewriter()
+except Exception:
+    _QUERY_REWRITER = None  # type: ignore
+
+# Import the enhanced stance classifier with fallback to original
+try:
+    from enhanced_stance_classifier import EnhancedStanceClassifier as _StanceClassifier, build_enhanced_stance_classifier
+    _USE_ENHANCED_STANCE = True
+    logger_tmp = logging.getLogger("data_collector")
+    logger_tmp.info("Using enhanced stance classifier with improved context understanding")
+except Exception as _e:
+    logger_tmp = logging.getLogger("data_collector")
+    logger_tmp.warning("Enhanced stance_classifier unavailable (%s) — falling back to original", _e)
+    try:
+        from stance_classifier import StanceClassifier as _StanceClassifier, build_stance_classifier
+        _USE_ENHANCED_STANCE = False
+        _USE_NEW_STANCE = True
+    except Exception as _e2:
+        logger_tmp.warning("Original stance_classifier also unavailable (%s) — using legacy keywords", _e2)
+        _USE_ENHANCED_STANCE = False
+        _USE_NEW_STANCE = False
+
+try:
+    import redis
+    _REDIS_AVAILABLE = True
+except ImportError:
+    _REDIS_AVAILABLE = False
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+)
+logger = logging.getLogger("data_collector")
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+RELIABILITY_CONFIG_PATH = os.getenv("RELIABILITY_CONFIG", "domain_reliability.yaml")
+REDIS_URL               = os.getenv("REDIS_URL", "redis://localhost:6379")
+CACHE_TTL               = int(os.getenv("CACHE_TTL_SECONDS", 86400))
+MAX_SOURCES             = int(os.getenv("MAX_SOURCES_PER_CLAIM", 8))
+REQUEST_TIMEOUT         = int(os.getenv("REQUEST_TIMEOUT", 10))
+
+
+# ---------------------------------------------------------------------------
+# Domain Reliability Scorer
+# ---------------------------------------------------------------------------
+
+class DomainReliabilityScorer:
+    """
+    Loads domain_reliability.yaml and scores any URL.
+    Fully enterprise-configurable without touching Python code.
+    """
+
+    def __init__(self, config_path: str = RELIABILITY_CONFIG_PATH) -> None:
+        self._config = self._load(config_path)
+        self._exact: Dict[str, tuple[float, str]] = {}   # domain → (score, type)
+        self._patterns: List[tuple[str, float, str]] = [] # (glob, score, type)
+        self._build_index()
+
+    def _load(self, path: str) -> dict:
+        if not os.path.exists(path):
+            logger.warning("Reliability config not found at %s — using defaults", path)
+            return {}
+        with open(path, "r", encoding="utf-8") as fh:
+            return yaml.safe_load(fh) or {}
+
+    def _build_index(self) -> None:
+        skip = {"version", "defaults", "stance_thresholds", "evidence_thresholds"}
+        for section_name, section in self._config.items():
+            if section_name in skip or not isinstance(section, dict):
+                continue
+            score = float(section.get("score", 0.35))
+            stype = str(section.get("source_type", "unknown"))
+            for domain in section.get("domains", []):
+                self._exact[domain.lower().lstrip("www.")] = (score, stype)
+            for pat in section.get("patterns", []):
+                self._patterns.append((pat.lower(), score, stype))
+
+    def score(self, url: str) -> tuple[float, str]:
+        """Return (reliability_score, source_type) for a URL."""
+        try:
+            host = urlparse(url).hostname or ""
+        except Exception:
+            host = ""
+        host = host.lower().lstrip("www.")
+
+        # Exact match (including subdomains stripped to base)
+        for candidate in self._candidates(host):
+            if candidate in self._exact:
+                return self._exact[candidate]
+
+        # Glob patterns (e.g. *.blogspot.com)
+        for pat, score, stype in self._patterns:
+            if fnmatch.fnmatch(host, pat):
+                return score, stype
+
+        defaults = self._config.get("defaults", {})
+        return (
+            float(defaults.get("unknown_domain_score", 0.35)),
+            str(defaults.get("unknown_source_type", "unknown")),
+        )
+
+    @staticmethod
+    def _candidates(host: str) -> List[str]:
+        """Generate host + progressively stripped parent domains."""
+        parts = host.split(".")
+        candidates = []
+        for i in range(len(parts)):
+            candidates.append(".".join(parts[i:]))
+        return candidates
+
+    @property
+    def stance_config(self) -> dict:
+        return self._config.get("stance_thresholds", {})
+
+    @property
+    def evidence_thresholds(self) -> dict:
+        return self._config.get("evidence_thresholds", {})
+
+
+# ---------------------------------------------------------------------------
+# Stance Classifier
+# ---------------------------------------------------------------------------
+
+class StanceClassifier:
+    """
+    Heuristic stance classification using keyword lists from the YAML config.
+    No ML dependency — deterministic and inspectable.
+    """
+
+    def __init__(self, scorer: DomainReliabilityScorer) -> None:
+        cfg = scorer.stance_config
+        self._contra_kw: List[str] = [k.lower() for k in cfg.get("contradicting_keywords", [])]
+        self._supp_kw: List[str]   = [k.lower() for k in cfg.get("supporting_keywords", [])]
+        self._contra_min: int      = int(cfg.get("contradicting_keyword_min", 2))
+        self._supp_min: int        = int(cfg.get("supporting_keyword_min", 2))
+
+    def classify(self, text: str, claim: str) -> str:
+        """Return 'supporting' | 'contradicting' | 'neutral'."""
+        lowered = text.lower()
+        contra_hits = sum(1 for kw in self._contra_kw if kw in lowered)
+        supp_hits   = sum(1 for kw in self._supp_kw   if kw in lowered)
+
+        if contra_hits >= self._contra_min and contra_hits > supp_hits:
+            return "contradicting"
+        if supp_hits >= self._supp_min and supp_hits >= contra_hits:
+            return "supporting"
+        return "neutral"
+
+
+# ---------------------------------------------------------------------------
+# Data models for collection pipeline
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RawResult:
+    title: str
+    snippet: str
+    url: str
+    source: str       # which backend returned this
+
+
+@dataclass
+class CollectionRequest:
+    content: str
+    claims: List[str]
+    difficulty: str = "medium"
+    scenario_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    tags: List[str] = field(default_factory=list)
+    topic: str = ""
+    force_refresh: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Search backend interface + implementations
+# ---------------------------------------------------------------------------
+
+class SearchBackend(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        ...
+
+    def available(self) -> bool:
+        return True
+
+
+class SerpAPIBackend(SearchBackend):
+    name = "serpapi"
+
+    def __init__(self) -> None:
+        self._key = os.getenv("SERPAPI_KEY", "")
+
+    def available(self) -> bool:
+        return bool(self._key)
+
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        # Detect query intent to choose the right SerpAPI parameters
+        is_factcheck  = re.search(r'\bfact.?check\b|debunked|hoax|false|misleading', query, re.I)
+        is_news       = re.search(r'\bofficial\b|\bgovernment\b|\bannouncement\b', query, re.I)
+
+        params: dict = {
+            "q":        query,
+            "api_key":  self._key,
+            "num":      num_results,
+            "hl":       "en",
+            "gl":       "us",       # default country; overridden below if entity found
+            "safe":     "off",
+        }
+
+        # For very recent claims (date entities present) restrict to last month
+        if re.search(r'\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\b|\b\d{4}\b',
+                     query, re.I):
+            params["tbs"] = "qdr:m"   # last month
+
+        # Fact-check / debunking queries → force news tab
+        if is_factcheck or is_news:
+            params["tbm"] = "nws"
+
+        # Adjust country context from entity
+        country_gl = {
+            "india": "in", "pakistan": "pk", "uk": "uk", "australia": "au",
+            "canada": "ca", "germany": "de", "france": "fr", "japan": "jp",
+            "china": "cn", "brazil": "br", "nigeria": "ng",
+        }
+        low_q = query.lower()
+        for country, gl in country_gl.items():
+            if country in low_q:
+                params["gl"] = gl
+                break
+
+        resp = requests.get(
+            "https://serpapi.com/search",
+            params=params,
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        results: List[RawResult] = []
+
+        # Answer box — featured snippet is very high signal
+        if ab := data.get("answer_box"):
+            snippet = ab.get("answer") or ab.get("snippet") or ab.get("result", "")
+            link    = ab.get("link", "")
+            if snippet and link:
+                results.append(RawResult(
+                    title   = ab.get("title", "Featured Answer"),
+                    snippet = str(snippet)[:600],
+                    url     = link,
+                    source  = f"{self.name}:answer_box",
+                ))
+
+        # Top stories (news carousel)
+        for story in data.get("top_stories", [])[:4]:
+            link = story.get("link", "")
+            if link:
+                results.append(RawResult(
+                    title   = story.get("title", ""),
+                    snippet = story.get("snippet", story.get("title", "")),
+                    url     = link,
+                    source  = f"{self.name}:news",
+                ))
+
+        # Organic results
+        for item in data.get("organic_results", [])[:num_results]:
+            link = item.get("link", "")
+            if link:
+                results.append(RawResult(
+                    title   = item.get("title", ""),
+                    snippet = item.get("snippet", ""),
+                    url     = link,
+                    source  = self.name,
+                ))
+
+        return results
+
+
+class NewsAPIBackend(SearchBackend):
+    name = "newsapi"
+
+    def __init__(self) -> None:
+        self._key = os.getenv("NEWSAPI_KEY", "")
+
+    def available(self) -> bool:
+        return bool(self._key)
+
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        params = {
+            "q": query,
+            "apiKey": self._key,
+            "language": "en",
+            "sortBy": "relevancy",
+            "pageSize": num_results,
+        }
+        resp = requests.get(
+            "https://newsapi.org/v2/everything",
+            params=params,
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        results = []
+        for article in data.get("articles", [])[:num_results]:
+            content = article.get("content") or ""
+            # NewsAPI truncates content with "[+N chars]" — strip that artifact
+            content = re.sub(r"\s*\[\+\d+ chars\]$", "", content).strip()
+            snippet = article.get("description") or content or ""
+            results.append(RawResult(
+                title=article.get("title", ""),
+                snippet=snippet[:500],
+                url=article.get("url", ""),
+                source=self.name,
+            ))
+        return results
+
+
+class BraveSearchBackend(SearchBackend):
+    name = "brave"
+
+    def __init__(self) -> None:
+        self._key = os.getenv("BRAVE_SEARCH_KEY", "")
+
+    def available(self) -> bool:
+        return bool(self._key)
+
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        headers = {
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip",
+            "X-Subscription-Token": self._key,
+        }
+        params = {"q": query, "count": num_results, "text_decorations": False}
+        resp = requests.get(
+            "https://api.search.brave.com/res/v1/web/search",
+            headers=headers,
+            params=params,
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        results = []
+        for item in data.get("web", {}).get("results", [])[:num_results]:
+            results.append(RawResult(
+                title=item.get("title", ""),
+                snippet=item.get("description", ""),
+                url=item.get("url", ""),
+                source=self.name,
+            ))
+        return results
+
+
+class GoogleFactCheckBackend(SearchBackend):
+    """
+    Google Fact Check Tools API.
+    Returns structured fact-check claims with verdicts from IFCN signatories.
+    """
+    name = "google_factcheck"
+
+    def __init__(self) -> None:
+        self._key = os.getenv("GOOGLE_FACTCHECK_KEY", "")
+
+    def available(self) -> bool:
+        return bool(self._key)
+
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        params = {
+            "query": query,
+            "key": self._key,
+            "languageCode": "en",
+            "pageSize": num_results,
+        }
+        resp = requests.get(
+            "https://factchecktools.googleapis.com/v1alpha1/claims:search",
+            params=params,
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        results = []
+        for item in data.get("claims", [])[:num_results]:
+            reviews = item.get("claimReview", [])
+            for review in reviews[:1]:
+                publisher = review.get("publisher", {}).get("name", "")
+                rating    = review.get("textualRating", "")
+                title     = f"{publisher}: {rating}"
+                snippet   = (
+                    f"Claim: {item.get('text', '')} | "
+                    f"Rating: {rating} | "
+                    f"Review: {review.get('title', '')}"
+                )
+                url = review.get("url", "")
+                results.append(RawResult(
+                    title=title,
+                    snippet=snippet,
+                    url=url,
+                    source=self.name,
+                ))
+        return results
+
+
+class DuckDuckGoFallbackBackend(SearchBackend):
+    """
+    No-key fallback using DuckDuckGo.
+
+    Rate-limit strategy
+    -------------------
+    DDG aggressively rate-limits when the same IP fires multiple queries
+    in quick succession.  To work around this:
+
+    1. Only 1 query is ever sent per search() call (controlled by the
+       n_queries=1 limit set in _fetch_all_backends).
+    2. Exponential back-off: 5s → 15s → 45s between retries.
+    3. On the first RateLimitException, promote directly to the HTML
+       fallback (no waiting) — the HTML endpoint has a separate rate limit.
+    4. A class-level cooldown flag prevents hammering DDG when it's known
+       to be rate-limiting; the flag resets after _COOLDOWN_SECS seconds.
+    """
+    name = "duckduckgo"
+    _MAX_RETRIES   = 2
+    _BASE_DELAY    = 5.0    # seconds — first retry wait
+    _BACKOFF_MULT  = 3.0    # each retry waits BASE * MULT^attempt
+    _COOLDOWN_SECS = 60.0   # after a rate-limit, skip DDG for this many seconds
+
+    # Class-level cooldown state (shared across all calls in the process)
+    _cooldown_until: float = 0.0
+
+    def available(self) -> bool:
+        return True
+
+    def search(self, query: str, num_results: int = 8) -> List[RawResult]:
+        import time as _time
+
+        # Respect session-level cooldown
+        if _time.time() < DuckDuckGoFallbackBackend._cooldown_until:
+            remaining = DuckDuckGoFallbackBackend._cooldown_until - _time.time()
+            logger.debug("DDG in cooldown for %.0fs — skipping to HTML fallback", remaining)
+            return self._html_fallback(query, num_results)
+
+        for attempt in range(self._MAX_RETRIES):
+            try:
+                from duckduckgo_search import DDGS
+                from duckduckgo_search.exceptions import RatelimitException
+                results = []
+                with DDGS() as ddgs:
+                    for r in ddgs.text(query, max_results=num_results):
+                        results.append(RawResult(
+                            title   = r.get("title", ""),
+                            snippet = r.get("body", ""),
+                            url     = r.get("href", ""),
+                            source  = self.name,
+                        ))
+                if results:
+                    return results
+                logger.warning("DuckDuckGo returned 0 results (attempt %d)", attempt + 1)
+                time.sleep(self._BASE_DELAY * (self._BACKOFF_MULT ** attempt))
+
+            except ImportError:
+                return self._html_fallback(query, num_results)
+
+            except Exception as exc:
+                exc_str = str(exc)
+                is_ratelimit = (
+                    "202" in exc_str
+                    or "Ratelimit" in exc_str
+                    or "ratelimit" in exc_str.lower()
+                    or "rate" in exc_str.lower()
+                )
+                if is_ratelimit:
+                    # Set cooldown and immediately try HTML — no point waiting
+                    DuckDuckGoFallbackBackend._cooldown_until = (
+                        time.time() + self._COOLDOWN_SECS
+                    )
+                    logger.warning(
+                        "DDG rate-limited — switching to HTML fallback "
+                        "(cooldown %ds)", self._COOLDOWN_SECS
+                    )
+                    return self._html_fallback(query, num_results)
+
+                logger.warning("DuckDuckGo attempt %d failed: %s", attempt + 1, exc)
+                time.sleep(self._BASE_DELAY * (self._BACKOFF_MULT ** attempt))
+
+        # All DDGS attempts exhausted — try HTML
+        return self._html_fallback(query, num_results)
+
+    def _html_fallback(self, query: str, num_results: int) -> List[RawResult]:
+        """Scrape DuckDuckGo HTML endpoint — separate rate limit from the API."""
+        import random
+        _USER_AGENTS = [
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
+            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+        ]
+        encoded = urllib.parse.quote_plus(query)
+        url     = f"https://html.duckduckgo.com/html/?q={encoded}"
+        headers = {
+            "User-Agent":      random.choice(_USER_AGENTS),
+            "Accept-Language": "en-US,en;q=0.9",
+            "Accept":          "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        }
+        try:
+            resp = requests.get(url, headers=headers, timeout=REQUEST_TIMEOUT)
+            resp.raise_for_status()
+            clean_tag = re.compile(r"<[^>]+>")
+            titles    = re.findall(r'class="result__title">.*?<a[^>]+>(.*?)</a>', resp.text, re.S)
+            snippets  = re.findall(r'class="result__snippet">(.*?)</a>', resp.text, re.S)
+            urls_raw  = re.findall(r'class="result__url">(.*?)</span>', resp.text, re.S)
+            results   = []
+            for t, s, u in zip(titles, snippets, urls_raw):
+                u = u.strip()
+                results.append(RawResult(
+                    title   = clean_tag.sub("", t).strip()[:200],
+                    snippet = clean_tag.sub("", s).strip()[:500],
+                    url     = ("https://" + u) if not u.startswith("http") else u,
+                    source  = self.name,
+                ))
+                if len(results) >= num_results:
+                    break
+            return results
+        except Exception as exc:
+            logger.error("DuckDuckGo HTML fallback failed: %s", exc)
+            return []
+
+
+class WikipediaBackend(SearchBackend):
+    """
+    Wikipedia REST API — zero rate-limits, no key, always returns results.
+    Used as the guaranteed last-resort fallback when all other backends fail.
+    """
+    name = "wikipedia"
+
+    def available(self) -> bool:
+        return True
+
+    def search(self, query: str, num_results: int = 5) -> List[RawResult]:
+        results = []
+        # 1. Search for matching article titles
+        try:
+            search_resp = requests.get(
+                "https://en.wikipedia.org/w/api.php",
+                params={
+                    "action": "query", "list": "search",
+                    "srsearch": query, "srlimit": num_results,
+                    "format": "json", "utf8": 1,
+                },
+                timeout=REQUEST_TIMEOUT,
+                headers={"User-Agent": "InformationIntegrityEnv/1.0 (research)"},
+            )
+            search_resp.raise_for_status()
+            hits = search_resp.json().get("query", {}).get("search", [])
+        except Exception as exc:
+            logger.warning("Wikipedia search failed: %s", exc)
+            return []
+
+        # 2. Fetch intro paragraph for each hit
+        for hit in hits[:num_results]:
+            title = hit.get("title", "")
+            snippet = re.sub(r"<[^>]+>", "", hit.get("snippet", "")).strip()
+            try:
+                summ_resp = requests.get(
+                    f"https://en.wikipedia.org/api/rest_v1/page/summary/{urllib.parse.quote(title)}",
+                    timeout=REQUEST_TIMEOUT,
+                    headers={"User-Agent": "InformationIntegrityEnv/1.0 (research)"},
+                )
+                if summ_resp.ok:
+                    data    = summ_resp.json()
+                    snippet = data.get("extract", snippet)[:600]
+                    url     = data.get("content_urls", {}).get("desktop", {}).get("page",
+                              f"https://en.wikipedia.org/wiki/{urllib.parse.quote(title)}")
+                else:
+                    url = f"https://en.wikipedia.org/wiki/{urllib.parse.quote(title)}"
+            except Exception:
+                url = f"https://en.wikipedia.org/wiki/{urllib.parse.quote(title)}"
+
+            results.append(RawResult(
+                title   = f"Wikipedia: {title}",
+                snippet = snippet,
+                url     = url,
+                source  = self.name,
+            ))
+
+        return results
+
+
+# ---------------------------------------------------------------------------
+# Full Content Fetcher
+# ---------------------------------------------------------------------------
+
+class FullContentFetcher:
+    """
+    Fetches and extracts the main article body from a URL.
+    Uses newspaper3k when available (best extraction quality), then falls back
+    to a BeautifulSoup heuristic that strips boilerplate and joins <p> tags.
+    Only called for sources whose reliability score >= FULL_CONTENT_MIN_RELIABILITY.
+    Returns None on any failure so callers can fall back to the snippet.
+    """
+
+    MIN_RELIABILITY: float = float(os.getenv("FULL_CONTENT_MIN_RELIABILITY", "0.6"))
+    MAX_CHARS: int = int(os.getenv("FULL_CONTENT_MAX_CHARS", "4000"))
+    FETCH_TIMEOUT: int = int(os.getenv("FULL_CONTENT_TIMEOUT", "12"))
+
+    _USER_AGENTS = [
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+    ]
+
+    # Simple cache to avoid re-fetching the same URL within a single run
+    _cache: Dict[str, Optional[str]] = {}
+
+    def fetch(self, url: str) -> Optional[str]:
+        """Return extracted article text (up to MAX_CHARS) or None on failure."""
+        if url in self._cache:
+            return self._cache[url]
+
+        text = self._fetch_newspaper(url) or self._fetch_bs4(url)
+        if text:
+            text = text[:self.MAX_CHARS]
+        self._cache[url] = text
+        return text
+
+    def _fetch_newspaper(self, url: str) -> Optional[str]:
+        """Extract article using newspaper3k (best quality)."""
+        try:
+            from newspaper import Article  # type: ignore
+            article = Article(url, request_timeout=self.FETCH_TIMEOUT)
+            article.download()
+            article.parse()
+            body = (article.text or "").strip()
+            return body if len(body) > 100 else None
+        except Exception:
+            return None
+
+    def _fetch_bs4(self, url: str) -> Optional[str]:
+        """Extract main content using BeautifulSoup as fallback."""
+        import random
+        try:
+            from bs4 import BeautifulSoup  # type: ignore
+        except ImportError:
+            return None
+
+        try:
+            headers = {
+                "User-Agent": random.choice(self._USER_AGENTS),
+                "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                "Accept-Language": "en-US,en;q=0.9",
+            }
+            resp = requests.get(url, headers=headers, timeout=self.FETCH_TIMEOUT, allow_redirects=True)
+            if not resp.ok or "text/html" not in resp.headers.get("Content-Type", ""):
+                return None
+
+            soup = BeautifulSoup(resp.text, "html.parser")
+
+            # Remove boilerplate elements
+            for tag in soup(["script", "style", "nav", "header", "footer",
+                              "aside", "form", "noscript", "iframe", "figure"]):
+                tag.decompose()
+
+            # Heuristic: find the container with the most <p> text
+            candidates = soup.find_all(["article", "main", "div", "section"])
+            best_block = None
+            best_len = 0
+            for block in candidates:
+                text = " ".join(p.get_text(" ", strip=True) for p in block.find_all("p"))
+                if len(text) > best_len:
+                    best_len = len(text)
+                    best_block = text
+
+            if best_block and best_len > 150:
+                # Normalise whitespace
+                return re.sub(r"\s{2,}", " ", best_block).strip()
+
+            # Last resort: just get all paragraph text
+            all_p = " ".join(p.get_text(" ", strip=True) for p in soup.find_all("p"))
+            cleaned = re.sub(r"\s{2,}", " ", all_p).strip()
+            return cleaned if len(cleaned) > 150 else None
+
+        except Exception as exc:
+            logger.debug("BS4 content fetch failed for %s: %s", url[:60], exc)
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Redis Cache
+# ---------------------------------------------------------------------------
+
+class ScenarioCache:
+    """
+    Redis-backed cache for collected scenarios.
+    Key = sha256(claim_fingerprint).
+    Falls back to an in-process dict if Redis is unavailable.
+    """
+
+    def __init__(self, redis_url: str = REDIS_URL, ttl: int = CACHE_TTL) -> None:
+        self._ttl = ttl
+        self._mem: Dict[str, Any] = {}
+        self._redis: Optional[Any] = None
+        if _REDIS_AVAILABLE:
+            try:
+                self._redis = redis.from_url(redis_url, decode_responses=True)
+                self._redis.ping()
+                logger.info("Redis cache connected at %s", redis_url)
+            except Exception as exc:
+                logger.warning("Redis unavailable (%s) — falling back to in-process cache", exc)
+                self._redis = None
+
+    @staticmethod
+    def _key(request: CollectionRequest) -> str:
+        fingerprint = json.dumps({
+            "claims": sorted(request.claims),
+            "difficulty": request.difficulty,
+        }, sort_keys=True)
+        return "scenario:" + hashlib.sha256(fingerprint.encode()).hexdigest()
+
+    def get(self, request: CollectionRequest) -> Optional[dict]:
+        k = self._key(request)
+        if self._redis:
+            raw = self._redis.get(k)
+            if raw:
+                return json.loads(raw)
+        return self._mem.get(k)
+
+    def set(self, request: CollectionRequest, scenario: dict) -> None:
+        k = self._key(request)
+        if self._redis:
+            self._redis.setex(k, self._ttl, json.dumps(scenario))
+        self._mem[k] = scenario
+
+    def invalidate(self, request: CollectionRequest) -> None:
+        k = self._key(request)
+        if self._redis:
+            self._redis.delete(k)
+        self._mem.pop(k, None)
+
+
+# ---------------------------------------------------------------------------
+# Main DataCollector
+# ---------------------------------------------------------------------------
+
+class DataCollector:
+    """
+    Orchestrates multi-backend search, reliability scoring, stance
+    classification, deduplication, and caching into a Scenario dict.
+    """
+
+    def __init__(
+        self,
+        backends: Optional[List[SearchBackend]] = None,
+        cache: Optional[ScenarioCache] = None,
+        scorer: Optional[DomainReliabilityScorer] = None,
+    ) -> None:
+        self._scorer    = scorer or DomainReliabilityScorer()
+        self._cache     = cache or ScenarioCache()
+        self._backends  = backends or self._default_backends()
+
+        # Use enhanced stance classifier with fallbacks
+        if _USE_ENHANCED_STANCE:
+            self._stancer = build_enhanced_stance_classifier(self._scorer)
+        elif _USE_NEW_STANCE:
+            self._stancer = build_stance_classifier(self._scorer)
+        else:
+            self._stancer = StanceClassifier(self._scorer)  # type: ignore
+
+    @staticmethod
+    def _default_backends() -> List[SearchBackend]:
+        # Disable DuckDuckGo due to rate limiting and reliability issues
+        candidates = [
+            SerpAPIBackend(),
+            NewsAPIBackend(),
+            BraveSearchBackend(),
+            GoogleFactCheckBackend(),
+            # DuckDuckGoFallbackBackend(),  # Disabled - causes rate limiting issues
+            WikipediaBackend(),          # guaranteed fallback — no rate-limits
+        ]
+        available = [b for b in candidates if b.available()]
+        if not available:
+            logger.warning("No search backends available — results will be empty")
+        logger.info(
+            "Active search backends: %s",
+            [b.name for b in available],
+        )
+        return available
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def collect(self, request: CollectionRequest) -> dict:
+        """
+        Main entry point.  Returns a Scenario-compatible dict.
+        Checks Redis cache first; fetches from APIs on cache miss.
+        """
+        if not request.force_refresh:
+            cached = self._cache.get(request)
+            if cached:
+                logger.info("Cache hit for scenario %s", request.scenario_id)
+                return cached
+
+        scenario = self._build_scenario(request)
+        self._cache.set(request, scenario)
+        logger.info(
+            "Collected scenario %s — %d claims, %d sources",
+            scenario["id"],
+            len(scenario["claims"]),
+            len(scenario["sources"]),
+        )
+        return scenario
+
+    def collect_batch(self, requests: List[CollectionRequest]) -> List[dict]:
+        return [self.collect(r) for r in requests]
+
+    # ------------------------------------------------------------------
+    # Internal pipeline
+    # ------------------------------------------------------------------
+
+    def _build_scenario(self, req: CollectionRequest) -> dict:
+        all_sources = []
+        seen_urls: set[str] = set()
+        fetcher = FullContentFetcher()
+
+        for claim in req.claims:
+            raw_results = self._fetch_all_backends(claim)
+            for raw in raw_results:
+                norm_url = self._normalise_url(raw.url)
+                if not norm_url or norm_url in seen_urls:
+                    continue
+                seen_urls.add(norm_url)
+
+                score, stype = self._scorer.score(norm_url)
+
+                # For high-reliability sources, fetch the full article body so
+                # stance classification has rich context rather than a 500-char snippet.
+                full_text: Optional[str] = None
+                if score >= FullContentFetcher.MIN_RELIABILITY:
+                    full_text = fetcher.fetch(norm_url)
+                    if full_text:
+                        logger.info(
+                            "Full content fetched for %s (%d chars, rel=%.2f)",
+                            norm_url[:70], len(full_text), score,
+                        )
+
+                # The text used for classification is full article when available,
+                # otherwise fall back to the snippet returned by the backend.
+                text_for_classification = full_text or raw.snippet
+
+                # Use enhanced classifier when available (returns detailed tuple),
+                # fall back to legacy interface (returns string only)
+                try:
+                    if (_USE_ENHANCED_STANCE or _USE_NEW_STANCE) and hasattr(self._stancer, "classify_detailed"):
+                        stance, _conf, _layer = self._stancer.classify_detailed(
+                            title=raw.title,
+                            text=text_for_classification,
+                            claim=claim,
+                            source_reliability=score,
+                        )
+                        logger.debug(
+                            "Stance '%s' via %s (conf=%.2f): %s",
+                            stance, _layer, _conf, raw.title[:60],
+                        )
+                    else:
+                        stance = self._stancer.classify(text_for_classification + " " + raw.title, claim)
+                        logger.debug("Stance '%s' via legacy: %s", stance, raw.title[:60])
+                except Exception as stance_exc:
+                    logger.warning(
+                        "Stance classification failed for '%s': %s - defaulting to neutral",
+                        raw.title[:60], stance_exc
+                    )
+                    stance = "neutral"
+                src_id = f"src_{len(all_sources) + 1:03d}"
+
+                all_sources.append({
+                    "id":                  src_id,
+                    "title":               raw.title[:200],
+                    "text":                (full_text or raw.snippet)[:800],
+                    "url":                 norm_url,
+                    "stance":              stance,
+                    "reliability":         round(score, 3),
+                    "source_type":         stype,
+                    "verification_weight": round(score, 3),
+                    "fetched_by":          raw.source,
+                    "has_full_content":    full_text is not None,
+                })
+
+                if len(all_sources) >= MAX_SOURCES * len(req.claims):
+                    break
+
+        claims_payload = [
+            {
+                "id":                      f"claim_{i+1:03d}",
+                "text":                    c,
+                "ground_truth_status":     self._infer_ground_truth_status(c, all_sources),
+                "ground_truth_confidence": self._infer_confidence(all_sources),
+            }
+            for i, c in enumerate(req.claims)
+        ]
+
+        ground_truth = self._infer_decision(claims_payload, all_sources)
+
+        return {
+            "id":               req.scenario_id,
+            "difficulty":       req.difficulty,
+            "topic":            req.topic or self._guess_topic(req.content),
+            "tags":             req.tags,
+            "content":          req.content,
+            "claims":           claims_payload,
+            "sources":          all_sources,
+            "ground_truth":     ground_truth,
+            "explanation_hint": self._build_explanation_hint(
+                req.claims, all_sources, ground_truth
+            ),
+            "_meta": {
+                "collected_at":    time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "backends_used":   list({s["fetched_by"] for s in all_sources}),
+                "total_sources":   len(all_sources),
+            },
+        }
+
+    def _fetch_all_backends(self, query: str) -> List[RawResult]:
+        """Try backends in priority order; aggregate unique results."""
+        results: List[RawResult] = []
+        seen_urls: set[str] = set()
+
+        # Use QueryRewriter for semantically rich query variants
+        if _QUERY_REWRITER is not None:
+            enriched_queries = _QUERY_REWRITER.expand(query)
+        else:
+            keywords = query.strip().rstrip("?.")
+            enriched_queries = [
+                keywords,
+                f'fact check "{keywords}"',
+                f'"{keywords}" evidence',
+                f'is it true that {keywords}',
+            ]
+
+        for backend in self._backends:
+            # SerpAPI gets all query variants (primary backend, paid, high rate-limit)
+            # Other backends get 2 queries for better coverage
+            if backend.name == "serpapi":
+                n_queries = len(enriched_queries)
+            else:
+                n_queries = 2
+            try:
+                for q in enriched_queries[:n_queries]:
+                    for r in backend.search(q, num_results=MAX_SOURCES):
+                        if r.url and r.url not in seen_urls and (r.snippet or r.title):
+                            seen_urls.add(r.url)
+                            results.append(r)
+            except Exception as exc:
+                logger.warning("Backend %s failed for query '%s': %s", backend.name, query, exc)
+
+        # ── Keyword gate: drop results with <2 overlapping claim keywords ──────
+        gated = [r for r in results if self._keyword_overlap(query, r) >= self._min_overlap(query)]
+        # Safety net: if gate drops everything, keep original results (no empty pool)
+        if not gated and results:
+            logger.debug("Keyword gate dropped all results for '%s…' — keeping unfiltered", query[:60])
+            return results[:MAX_SOURCES * 3]
+
+        return gated[:MAX_SOURCES * 3]
+
+    @staticmethod
+    def _keyword_overlap(claim: str, raw: RawResult) -> int:
+        """Count shared non-trivial keywords between the claim and a result."""
+        _stop = {
+            "the","a","an","is","are","was","were","in","on","at","to","from",
+            "of","and","or","but","that","this","it","be","will","has","have",
+            "its","by","for","not","with","also","into","than","more","about",
+        }
+        claim_kws  = {w for w in re.findall(r'\b[a-z]{3,}\b', claim.lower())  if w not in _stop}
+        result_kws = {w for w in re.findall(r'\b[a-z]{3,}\b',
+                      (raw.title + " " + raw.snippet).lower()) if w not in _stop}
+        return len(claim_kws & result_kws)
+
+    @staticmethod
+    def _min_overlap(claim: str) -> int:
+        """
+        Adaptive minimum overlap threshold based on claim length.
+        Short claims (≤4 meaningful words) → require 1 match.
+        Longer claims → require 2 matches (avoids generic Wikipedia hits).
+        """
+        _stop = {"the","a","an","is","are","was","were","in","on","at","to",
+                 "from","of","and","or","but","that","this","it","be","will"}
+        n_kws = len({w for w in re.findall(r'\b[a-z]{3,}\b', claim.lower()) if w not in _stop})
+        return 1 if n_kws <= 4 else 2
+
+    @staticmethod
+    def _normalise_url(url: str) -> str:
+        url = url.strip()
+        if not url.startswith(("http://", "https://")):
+            url = "https://" + url
+        try:
+            parsed = urlparse(url)
+            return parsed.geturl()
+        except Exception:
+            return url
+
+    def _infer_ground_truth_status(self, claim: str, sources: List[dict]) -> str:
+        """
+        Heuristic: look at stance distribution weighted by reliability.
+        Returns 'true' | 'false' | 'partially_true' | 'unknown'
+        """
+        contra_score = sum(
+            s["reliability"] for s in sources if s["stance"] == "contradicting"
+        )
+        support_score = sum(
+            s["reliability"] for s in sources if s["stance"] == "supporting"
+        )
+        total = contra_score + support_score
+        if total == 0:
+            return "unknown"
+        ratio = support_score / total
+        if ratio < 0.2:
+            return "false"
+        if ratio > 0.7:
+            return "true"
+        return "partially_true"
+
+    def _infer_confidence(self, sources: List[dict]) -> float:
+        if not sources:
+            return 0.0
+        max_rel = max(s["reliability"] for s in sources)
+        return round(min(max_rel, 1.0), 3)
+
+    def _infer_decision(self, claims: List[dict], sources: List[dict]) -> str:
+        """
+        Derive a moderation recommendation from weighted evidence.
+          remove          → weighted false evidence dominant, high reliability
+          flag            → mixed or uncertain evidence
+          allow           → predominantly true, high-reliability support
+        """
+        false_weight = sum(
+            s["reliability"]
+            for s in sources
+            if s["stance"] == "contradicting"
+        )
+        support_weight = sum(
+            s["reliability"]
+            for s in sources
+            if s["stance"] == "supporting"
+        )
+        neutral_weight = sum(
+            s["reliability"]
+            for s in sources
+            if s["stance"] == "neutral"
+        )
+        total = false_weight + support_weight + neutral_weight or 1.0
+
+        false_pct   = false_weight / total
+        support_pct = support_weight / total
+
+        # Strong contradicting signal → remove
+        if false_pct > 0.55 and false_weight > 1.5:
+            return "remove"
+        # Weak or mixed signal → flag
+        if false_pct > 0.30 or (abs(false_pct - support_pct) < 0.20):
+            return "flag"
+        # Predominantly supported and reliable → allow
+        if support_pct > 0.55 and support_weight > 1.0:
+            return "allow"
+        return "flag"
+
+    @staticmethod
+    def _guess_topic(content: str) -> str:
+        TOPICS = [
+            ("health",      ["vaccine", "covid", "cancer", "virus", "drug", "health", "disease"]),
+            ("politics",    ["election", "president", "government", "vote", "congress", "parliament"]),
+            ("technology",  ["5g", "ai", "chip", "microchip", "algorithm", "robot", "data"]),
+            ("climate",     ["climate", "warming", "carbon", "emission", "fossil", "renewable"]),
+            ("economics",   ["inflation", "gdp", "unemployment", "economy", "recession", "market"]),
+            ("science",     ["study", "research", "scientist", "experiment", "proof", "evidence"]),
+        ]
+        low = content.lower()
+        for topic, keywords in TOPICS:
+            if any(kw in low for kw in keywords):
+                return topic
+        return "general"
+
+    @staticmethod
+    def _build_explanation_hint(claims: List[str], sources: List[dict], decision: str) -> str:
+        contra = [s for s in sources if s["stance"] == "contradicting"]
+        supp   = [s for s in sources if s["stance"] == "supporting"]
+        lines  = [
+            f"Decision: {decision}.",
+            f"Claims examined: {len(claims)}.",
+            f"Contradicting sources: {len(contra)}, Supporting sources: {len(supp)}.",
+        ]
+        if contra:
+            top = max(contra, key=lambda s: s["reliability"])
+            lines.append(f"Strongest contradicting: {top['title'][:80]} (reliability {top['reliability']}).")
+        if supp:
+            top = max(supp, key=lambda s: s["reliability"])
+            lines.append(f"Strongest supporting: {top['title'][:80]} (reliability {top['reliability']}).")
+        return " ".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _cli() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Collect real-world evidence for a set of claims."
+    )
+    parser.add_argument(
+        "--claims", nargs="+", required=True,
+        help="One or more claim strings to investigate"
+    )
+    parser.add_argument(
+        "--content", default="",
+        help="The original piece of content containing the claims"
+    )
+    parser.add_argument(
+        "--difficulty", default="medium",
+        choices=["easy", "medium", "hard"],
+    )
+    parser.add_argument(
+        "--topic", default="",
+        help="Optional topic label"
+    )
+    parser.add_argument(
+        "--tags", nargs="*", default=[],
+        help="Optional tags"
+    )
+    parser.add_argument(
+        "--out", default="scenario.json",
+        help="Output file path"
+    )
+    parser.add_argument(
+        "--force-refresh", action="store_true",
+        help="Ignore Redis cache and re-fetch"
+    )
+    args = parser.parse_args()
+
+    collector = DataCollector()
+    request   = CollectionRequest(
+        content=args.content or " ".join(args.claims),
+        claims=args.claims,
+        difficulty=args.difficulty,
+        topic=args.topic,
+        tags=args.tags,
+        force_refresh=args.force_refresh,
+    )
+    scenario = collector.collect(request)
+
+    with open(args.out, "w", encoding="utf-8") as fh:
+        json.dump(scenario, fh, indent=2, ensure_ascii=False)
+
+    logger.info("Scenario written to %s", args.out)
+    print(json.dumps(scenario, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    _cli()

decision_engine.py

@@ -0,0 +1,454 @@
+"""
+decision_engine.py
+==================
+High-level moderation decision engine.
+
+Takes a summarised claim_result dict (produced after stance classification and
+source retrieval) and returns a final moderation decision with recalibrated
+confidence and a human-readable reason.
+
+This layer sits *above* reasoning.py:
+  DataCollector → StanceClassifier → reasoning.py → decision_engine.py → UI
+
+Why a separate layer?
+  reasoning.py works on raw ScoredSource objects (per-source contributions).
+  This module works on already-aggregated claim summaries, which is the shape
+  that the UI, API, and tests produce.  The two layers complement each other —
+  reasoning.py computes the evidence score; this module applies the final
+  decision policy (thresholds, pattern boosts, confidence blending).
+
+Usage
+-----
+    from decision_engine import make_moderation_decision
+
+    result = make_moderation_decision({
+        "claim":                   "Humans only use 10% of their brain",
+        "status":                  "FALSE",
+        "confidence":              0.35,
+        "supporting_sources":      0,
+        "contradicting_sources":   3,
+        "neutral_sources":         1,
+        "avg_source_reliability":  0.72,
+    })
+    # → {"decision": "AUTO_REMOVE", "final_confidence": 0.88, "reason": "..."}
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Configurable thresholds
+# All values can be overridden per-call via the `config` parameter.
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class DecisionConfig:
+    # ── AUTO_REMOVE thresholds ────────────────────────────────────────────────
+    # Minimum contradicting sources required for AUTO_REMOVE when status=FALSE
+    auto_remove_min_contra:       int   = 2
+    # OR: single-source override when that one source is very reliable
+    auto_remove_single_src_rel:   float = 0.85
+    # Settled-science / known-misinformation pattern always triggers AUTO_REMOVE
+    # with just 1 contradicting source
+    auto_remove_pattern_min_contra: int = 1
+
+    # ── ALLOW thresholds ──────────────────────────────────────────────────────
+    allow_min_support:            int   = 2       # min supporting sources for ALLOW
+    allow_single_src_rel:         float = 0.90    # single very-reliable source is enough
+
+    # ── Confidence blend weights (must sum to 1.0) ────────────────────────────
+    weight_stance:      float = 0.50   # from status + incoming confidence
+    weight_evidence:    float = 0.30   # from source counts
+    weight_reliability: float = 0.20   # from avg_source_reliability
+
+    # ── Evidence strength formula ─────────────────────────────────────────────
+    # evidence_strength = contra / (contra + support + 1) for FALSE claims
+    # evidence_strength = support / (support + contra + 1) for TRUE claims
+    # The +1 in denominator prevents division-by-zero and dampens single-source certainty.
+
+    # ── Pattern boost ─────────────────────────────────────────────────────────
+    pattern_boost: float = 0.15    # added to final_confidence when a known pattern matches
+
+    # ── Confidence floor/ceiling ──────────────────────────────────────────────
+    min_confidence: float = 0.10
+    max_confidence: float = 0.99
+
+
+# Default singleton — callers can pass a custom config to override
+_DEFAULT_CONFIG = DecisionConfig()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Known misinformation patterns
+# ─────────────────────────────────────────────────────────────────────────────
+# Each entry: (label, regex)
+# When a claim text matches, the pattern_boost is applied AND the
+# auto_remove threshold is lowered to auto_remove_pattern_min_contra.
+
+_KNOWN_MISINFO: list[tuple[str, re.Pattern]] = [
+    # Neuroscience myth
+    ("10pct_brain", re.compile(
+        r"\b(10\s*%|ten\s+percent).{0,30}brain\b|\bbrain.{0,30}(10\s*%|ten\s+percent)\b",
+        re.IGNORECASE,
+    )),
+    # Flat earth
+    ("flat_earth", re.compile(
+        r"\b(earth\s+is\s+flat|flat\s+earth|earth\s+isn.t?\s+(round|spherical|globe))\b",
+        re.IGNORECASE,
+    )),
+    # Bleach / MMS as cure
+    ("bleach_cure", re.compile(
+        r"\b(drink(ing)?\s+bleach|bleach\s+cure[sd]?|mms\s+cure[sd]?|"
+        r"chlorine\s+dioxide\s+cure|inject(ing)?\s+disinfectant)\b",
+        re.IGNORECASE,
+    )),
+    # Vaccine-autism link
+    ("vaccines_autism", re.compile(
+        r"\bvaccines?\s+(cause[sd]?|linked?\s+to|lead[s]?\s+to)\s+autism\b",
+        re.IGNORECASE,
+    )),
+    # 5G / COVID
+    ("5g_covid", re.compile(
+        r"\b5g\s+(causes?|spreads?|created?|transmits?)\s+(covid|coronavirus|virus)\b",
+        re.IGNORECASE,
+    )),
+    # Climate hoax
+    ("climate_hoax", re.compile(
+        r"\bclimate\s+change\s+is\s+(a\s+)?(hoax|fake|not\s+real|fabricated)\b",
+        re.IGNORECASE,
+    )),
+    # Moon landing
+    ("moon_landing", re.compile(
+        r"\b(moon\s+landing\s+(was\s+)?(fake|faked|hoax|staged)|never\s+landed\s+on.{0,10}moon)\b",
+        re.IGNORECASE,
+    )),
+    # HIV denial
+    ("hiv_denial", re.compile(
+        r"\b(hiv\s+(doesn.t?\s+cause|doesn.t?\s+exist|is\s+fake)|aids\s+is\s+(a\s+)?(hoax|fake))\b",
+        re.IGNORECASE,
+    )),
+    # Evolution denial
+    ("evolution_denial", re.compile(
+        r"\b(evolution\s+is\s+(false|fake|a\s+lie|wrong|disproven)|humans?\s+didn.t?\s+evolve)\b",
+        re.IGNORECASE,
+    )),
+]
+
+
+def _match_known_misinfo(claim: str) -> Optional[str]:
+    """
+    Returns the pattern label if the claim matches a known misinformation
+    pattern, otherwise None.
+    """
+    for label, pattern in _KNOWN_MISINFO:
+        if pattern.search(claim):
+            return label
+    return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Confidence calculation
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _compute_confidence(
+    status: str,
+    incoming_confidence: float,
+    supporting: int,
+    contradicting: int,
+    avg_reliability: float,
+    pattern_label: Optional[str],
+    cfg: DecisionConfig,
+) -> float:
+    """
+    Blend three independent signals into a single calibrated confidence score.
+
+    Component 1 — Stance confidence (weight=0.50)
+      Directly from the upstream classifier.  Clamped to [0, 1].
+
+    Component 2 — Evidence strength (weight=0.30)
+      For FALSE claims: contra / (contra + support + 1)
+      For TRUE  claims: support / (support + contra + 1)
+      For UNKNOWN:      0.0 (no directional evidence)
+      The +1 dampens over-confidence from a single source.
+
+    Component 3 — Source reliability (weight=0.20)
+      avg_source_reliability passed through directly.
+
+    Pattern boost (additive, after blend)
+      +cfg.pattern_boost when a known misinformation pattern is matched.
+    """
+    # Component 1
+    stance_conf = max(0.0, min(1.0, incoming_confidence))
+
+    # Component 2
+    total_directional = supporting + contradicting
+    if status == "FALSE" and contradicting > 0:
+        evidence_strength = contradicting / (total_directional + 1)
+    elif status == "TRUE" and supporting > 0:
+        evidence_strength = supporting / (total_directional + 1)
+    else:
+        evidence_strength = 0.0
+
+    # Component 3
+    reliability = max(0.0, min(1.0, avg_reliability))
+
+    # Weighted blend
+    blended = (
+        cfg.weight_stance      * stance_conf +
+        cfg.weight_evidence    * evidence_strength +
+        cfg.weight_reliability * reliability
+    )
+
+    # Pattern boost
+    if pattern_label is not None:
+        blended += cfg.pattern_boost
+
+    return round(max(cfg.min_confidence, min(cfg.max_confidence, blended)), 4)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Core decision logic
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _decide(
+    status: str,
+    contradicting: int,
+    supporting: int,
+    avg_reliability: float,
+    pattern_label: Optional[str],
+    cfg: DecisionConfig,
+) -> tuple[str, str]:
+    """
+    Returns (decision, reason_fragment).
+
+    Decision priority:
+      1. AUTO_REMOVE  — status is FALSE + sufficient contradicting evidence
+      2. ALLOW        — status is TRUE  + sufficient supporting evidence
+      3. FLAG_FOR_REVIEW — everything else
+    """
+
+    # ── Path 1: AUTO_REMOVE ───────────────────────────────────────────────────
+    if status == "FALSE":
+
+        # Known misinformation pattern: lower bar to 1 source
+        if pattern_label is not None and contradicting >= cfg.auto_remove_pattern_min_contra:
+            return (
+                "AUTO_REMOVE",
+                f"Matches known misinformation pattern '{pattern_label}' "
+                f"with {contradicting} contradicting source(s).",
+            )
+
+        # Standard: ≥2 contradicting sources
+        if contradicting >= cfg.auto_remove_min_contra:
+            return (
+                "AUTO_REMOVE",
+                f"{contradicting} contradicting source(s) confirm this claim is false.",
+            )
+
+        # Single very-reliable contradicting source
+        if contradicting >= 1 and avg_reliability >= cfg.auto_remove_single_src_rel:
+            return (
+                "AUTO_REMOVE",
+                f"Single highly reliable source (reliability={avg_reliability:.2f}) "
+                f"contradicts this claim.",
+            )
+
+    # ── Path 2: ALLOW ─────────────────────────────────────────────────────────
+    if status == "TRUE":
+
+        if supporting >= cfg.allow_min_support:
+            return (
+                "ALLOW",
+                f"{supporting} supporting source(s) confirm this claim is true.",
+            )
+
+        if supporting >= 1 and avg_reliability >= cfg.allow_single_src_rel:
+            return (
+                "ALLOW",
+                f"Single authoritative source (reliability={avg_reliability:.2f}) "
+                f"confirms this claim.",
+            )
+
+    # ── Path 3: FLAG_FOR_REVIEW ───────────────────────────────────────────────
+    if status == "UNKNOWN":
+        reason = "Claim status is UNKNOWN — insufficient evidence to decide."
+    elif status == "FALSE" and contradicting == 0:
+        reason = "Claim is marked FALSE but no contradicting sources were retrieved."
+    elif status == "FALSE" and contradicting < cfg.auto_remove_min_contra:
+        reason = (
+            f"Claim is FALSE but only {contradicting} contradicting source(s) found "
+            f"(need ≥{cfg.auto_remove_min_contra} for auto-removal)."
+        )
+    elif status == "TRUE" and supporting < cfg.allow_min_support:
+        reason = (
+            f"Claim is TRUE but only {supporting} supporting source(s) found "
+            f"(need ≥{cfg.allow_min_support} for auto-allow)."
+        )
+    else:
+        reason = "Evidence is insufficient or ambiguous."
+
+    return "FLAG_FOR_REVIEW", reason
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Public API
+# ─────────────────────────────────────────────────────────────────────────────
+
+def make_moderation_decision(
+    claim_result: dict,
+    config: Optional[DecisionConfig] = None,
+) -> dict:
+    """
+    Make a final moderation decision for a single claim.
+
+    Parameters
+    ----------
+    claim_result : dict
+        {
+            "claim":                   str,
+            "status":                  "TRUE" | "FALSE" | "UNKNOWN",
+            "confidence":              float,   # from upstream classifier (0–1)
+            "supporting_sources":      int,
+            "contradicting_sources":   int,
+            "neutral_sources":         int,
+            "avg_source_reliability":  float,   # 0–1
+        }
+
+    config : DecisionConfig | None
+        Override default thresholds.  Pass None to use defaults.
+
+    Returns
+    -------
+    dict
+        {
+            "decision":         "AUTO_REMOVE" | "ALLOW" | "FLAG_FOR_REVIEW",
+            "final_confidence": float,   # 0.10–0.99
+            "reason":           str,
+            "pattern_matched":  str | None,   # known misinformation label if triggered
+        }
+    """
+    cfg = config or _DEFAULT_CONFIG
+
+    # ── Extract fields with safe defaults ─────────────────────────────────────
+    claim         = str(claim_result.get("claim", ""))
+    status        = str(claim_result.get("status", "UNKNOWN")).upper()
+    confidence    = float(claim_result.get("confidence", 0.0))
+    supporting    = int(claim_result.get("supporting_sources", 0))
+    contradicting = int(claim_result.get("contradicting_sources", 0))
+    avg_rel       = float(claim_result.get("avg_source_reliability", 0.5))
+
+    # Normalise status to our three canonical values
+    if status not in ("TRUE", "FALSE", "UNKNOWN"):
+        status = "UNKNOWN"
+
+    # ── Known misinformation pattern check ────────────────────────────────────
+    pattern_label = _match_known_misinfo(claim)
+
+    # ── Decision ──────────────────────────────────────────────────────────────
+    decision, reason_fragment = _decide(
+        status, contradicting, supporting, avg_rel, pattern_label, cfg
+    )
+
+    # ── Confidence recalibration ──────────────────────────────────────────────
+    final_confidence = _compute_confidence(
+        status, confidence, supporting, contradicting,
+        avg_rel, pattern_label, cfg,
+    )
+
+    # ── Build human-readable reason ───────────────────────────────────────────
+    reason = _build_reason(
+        claim, decision, status, final_confidence,
+        supporting, contradicting, avg_rel,
+        pattern_label, reason_fragment,
+    )
+
+    return {
+        "decision":         decision,
+        "final_confidence": final_confidence,
+        "reason":           reason,
+        "pattern_matched":  pattern_label,
+    }
+
+
+def _build_reason(
+    claim: str,
+    decision: str,
+    status: str,
+    confidence: float,
+    supporting: int,
+    contradicting: int,
+    avg_rel: float,
+    pattern_label: Optional[str],
+    core_reason: str,
+) -> str:
+    """Compose a full human-readable explanation."""
+    lines = []
+
+    # Decision headline
+    headline = {
+        "AUTO_REMOVE":     "Content removed: claim is false and clearly contradicted.",
+        "ALLOW":           "Content allowed: claim is supported by evidence.",
+        "FLAG_FOR_REVIEW": "Content flagged: insufficient or ambiguous evidence.",
+    }.get(decision, "Decision made.")
+    lines.append(headline)
+
+    # Core reason from decision logic
+    lines.append(core_reason)
+
+    # Evidence summary
+    lines.append(
+        f"Evidence: {supporting} supporting, {contradicting} contradicting "
+        f"(avg source reliability: {avg_rel:.0%})."
+    )
+
+    # Confidence
+    lines.append(f"Final confidence: {confidence:.0%}.")
+
+    return "  ".join(lines)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Batch helper
+# ─────────────────────────────────────────────────────────────────────────────
+
+def make_moderation_decisions(
+    claim_results: list[dict],
+    config: Optional[DecisionConfig] = None,
+) -> dict:
+    """
+    Run make_moderation_decision over multiple claims and derive a single
+    aggregate content-level decision.
+
+    Aggregate logic (matches real-world platforms):
+      ANY AUTO_REMOVE → content = AUTO_REMOVE
+      ANY FLAG_FOR_REVIEW (and no remove) → content = FLAG_FOR_REVIEW
+      ALL ALLOW → content = ALLOW
+
+    Returns
+    -------
+    {
+        "content_decision": "AUTO_REMOVE" | "ALLOW" | "FLAG_FOR_REVIEW",
+        "per_claim": [ {claim_result + decision fields}, ... ],
+    }
+    """
+    per_claim = []
+    for cr in claim_results:
+        result = make_moderation_decision(cr, config)
+        per_claim.append({**cr, **result})
+
+    decisions = [r["decision"] for r in per_claim]
+    if "AUTO_REMOVE" in decisions:
+        content_decision = "AUTO_REMOVE"
+    elif "FLAG_FOR_REVIEW" in decisions:
+        content_decision = "FLAG_FOR_REVIEW"
+    else:
+        content_decision = "ALLOW"
+
+    return {
+        "content_decision": content_decision,
+        "per_claim":        per_claim,
+    }

docker-compose.yml

@@ -0,0 +1,31 @@
+# docker-compose.yml — local development stack
+# Usage: docker compose up --build
+version: "3.9"
+
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  env-server:
+    build: .
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      redis:
+        condition: service_healthy
+    volumes:
+      # Mount datasets for persistence across restarts
+      - ./datasets:/app/datasets

domain_reliability.yaml

@@ -0,0 +1,357 @@
+# =============================================================================
+# domain_reliability.yaml
+#
+# Enterprise-editable domain reliability config.
+# Scores range 0.0 (completely unreliable) to 1.0 (fully authoritative).
+#
+# Rules applied in order; first matching pattern wins.
+# Add your enterprise's internal trusted domains under `custom_trusted`.
+#
+# source_type values:
+#   official   → government, intergovernmental, standards bodies
+#   academic   → peer-reviewed journals, universities
+#   news       → professional journalism outlets
+#   factcheck  → dedicated fact-checking organisations
+#   ngo        → non-profit research / advocacy (varies)
+#   blog       → personal or commercial blogs
+#   social     → social media platforms
+#   unknown    → cannot determine
+# =============================================================================
+
+version: "1.0"
+
+# ---------------------------------------------------------------------------
+# 1. OFFICIAL / GOVERNMENT / INTERGOVERNMENTAL
+# ---------------------------------------------------------------------------
+official:
+  score: 0.97
+  source_type: official
+  domains:
+    - who.int
+    - cdc.gov
+    - nih.gov
+    - fda.gov
+    - nhs.uk
+    - ecdc.europa.eu
+    - paho.org
+    - un.org
+    - unicef.org
+    - worldbank.org
+    - imf.org
+    - oecd.org
+    - europa.eu
+    - gov.uk
+    - canada.ca
+    - australia.gov.au
+    - rki.de
+    - france.fr
+    - nasa.gov
+    - noaa.gov
+    - epa.gov
+    - energy.gov
+    - ftc.gov
+    - sec.gov
+    - federalreserve.gov
+    - bls.gov
+    - census.gov
+
+# ---------------------------------------------------------------------------
+# 2. ACADEMIC / PEER-REVIEWED
+# ---------------------------------------------------------------------------
+academic:
+  score: 0.93
+  source_type: academic
+  domains:
+    - nature.com
+    - science.org
+    - cell.com
+    - thelancet.com
+    - nejm.org
+    - bmj.com
+    - jamanetwork.com
+    - acs.org
+    - ieee.org
+    - acm.org
+    - pubmed.ncbi.nlm.nih.gov
+    - scholar.google.com
+    - arxiv.org
+    - biorxiv.org
+    - medrxiv.org
+    - plos.org
+    - frontiersin.org
+    - springer.com
+    - wiley.com
+    - elsevier.com
+    - oxfordjournals.org
+    - cambridge.org
+    - mit.edu
+    - stanford.edu
+    - harvard.edu
+    - ox.ac.uk
+    - cam.ac.uk
+    - ucl.ac.uk
+
+# ---------------------------------------------------------------------------
+# 3. DEDICATED FACT-CHECKERS (IFCN signatories)
+# ---------------------------------------------------------------------------
+factcheck:
+  score: 0.90
+  source_type: factcheck
+  domains:
+    - snopes.com
+    - factcheck.org
+    - politifact.com
+    - fullfact.org
+    - reuters.com/fact-check
+    - apnews.com
+    - afp.com
+    - misbar.com
+    - boomlive.in
+    - factly.in
+    - africacheck.org
+    - chequeado.com
+    - correctiv.org
+    - dpa.com
+    - leadstories.com
+    - verafiles.org
+
+# ---------------------------------------------------------------------------
+# 4. ESTABLISHED NEWS ORGANISATIONS
+# ---------------------------------------------------------------------------
+news_tier1:
+  score: 0.82
+  source_type: news
+  domains:
+    - bbc.com
+    - bbc.co.uk
+    - reuters.com
+    - apnews.com
+    - theguardian.com
+    - nytimes.com
+    - wsj.com
+    - washingtonpost.com
+    - economist.com
+    - ft.com
+    - bloomberg.com
+    - time.com
+    - npr.org
+    - pbs.org
+    - theatlantic.com
+    - science.sciencemag.org
+    - scientificamerican.com
+    - newscientist.com
+    - wired.com
+    - techcrunch.com
+    - arstechnica.com
+    - technologyreview.mit.edu
+    - spiegel.de
+    - lemonde.fr
+    - corriere.it
+    - elpais.com
+    - sueddeutsche.de
+
+news_tier2:
+  score: 0.68
+  source_type: news
+  domains:
+    - huffpost.com
+    - vice.com
+    - vox.com
+    - slate.com
+    - salon.com
+    - thehill.com
+    - politico.com
+    - axios.com
+    - buzzfeednews.com
+    - businessinsider.com
+    - newsweek.com
+    - usatoday.com
+    - nbcnews.com
+    - cbsnews.com
+    - abcnews.go.com
+    - foxnews.com
+    - msnbc.com
+    - cnn.com
+    - dailymail.co.uk
+    - mirror.co.uk
+    - independent.co.uk
+    - telegraph.co.uk
+
+# ---------------------------------------------------------------------------
+# 5. NGOs / THINK TANKS (variable bias, moderate reliability)
+# ---------------------------------------------------------------------------
+ngo:
+  score: 0.60
+  source_type: ngo
+  domains:
+    - amnesty.org
+    - hrw.org
+    - msf.org
+    - oxfam.org
+    - brookings.edu
+    - cfr.org
+    - rand.org
+    - pewresearch.org
+    - ipsos.com
+    - gallup.com
+    - kff.org
+    - urban.org
+    - chathamhouse.org
+
+# ---------------------------------------------------------------------------
+# 6. SOCIAL MEDIA PLATFORMS (user-generated; low inherent reliability)
+# ---------------------------------------------------------------------------
+social:
+  score: 0.15
+  source_type: social
+  domains:
+    - twitter.com
+    - x.com
+    - facebook.com
+    - instagram.com
+    - tiktok.com
+    - reddit.com
+    - youtube.com
+    - telegram.org
+    - t.me
+    - threads.net
+    - linkedin.com
+    - pinterest.com
+    - tumblr.com
+
+# ---------------------------------------------------------------------------
+# 7. KNOWN MISINFORMATION / LOW-CREDIBILITY DOMAINS
+# ---------------------------------------------------------------------------
+low_credibility:
+  score: 0.08
+  source_type: blog
+  domains:
+    - naturalnews.com
+    - infowars.com
+    - breitbart.com
+    - thegatewayp.com
+    - beforeitsnews.com
+    - zerohedge.com
+    - activistpost.com
+    - globalresearch.ca
+    - off-guardian.org
+    - thetruthseeker.co.uk
+    - conspiracytheories.net
+
+# ---------------------------------------------------------------------------
+# 8. GENERIC BLOG / CMS PATTERNS (matched by TLD pattern, not exact domain)
+# ---------------------------------------------------------------------------
+blog_patterns:
+  score: 0.18
+  source_type: blog
+  patterns:
+    - "*.blogspot.com"
+    - "*.wordpress.com"
+    - "*.medium.com"
+    - "*.substack.com"
+    - "*.ghost.io"
+    - "*.wixsite.com"
+    - "*.weebly.com"
+
+# ---------------------------------------------------------------------------
+# 9. ENTERPRISE CUSTOM — add your internal trusted domains here
+# ---------------------------------------------------------------------------
+custom_trusted:
+  score: 0.95
+  source_type: official
+  domains: []
+  # Example:
+  # - trust-center.mycompany.com
+  # - internal-wiki.corp.example.com
+
+# ---------------------------------------------------------------------------
+# DEFAULTS (applied when no pattern matches)
+# ---------------------------------------------------------------------------
+defaults:
+  unknown_domain_score: 0.35
+  unknown_source_type: unknown
+
+# ---------------------------------------------------------------------------
+# STANCE CLASSIFICATION THRESHOLDS
+# ---------------------------------------------------------------------------
+# NOTE: These keyword lists are now used by Layer 2 of stance_classifier.py.
+# Layer 1 (semantic heuristics) and Layer 3 (Claude LLM) take priority.
+# These lists serve as the fallback when both other layers are unavailable.
+stance_thresholds:
+  # Threshold=1: any single strong-signal keyword is decisive
+  contradicting_keyword_min: 1
+  supporting_keyword_min: 1
+
+  # Strong contradicting signals (one hit = contradicting)
+  contradicting_keywords:
+    - "false"
+    - "debunked"
+    - "disproven"
+    - "misinformation"
+    - "misleading"
+    - "no evidence"
+    - "lacks evidence"
+    - "unfounded"
+    - "refuted"
+    - "myth"
+    - "conspiracy theory"
+    - "fact-check"
+    - "factcheck"
+    - "incorrect"
+    - "not true"
+    - "inaccurate"
+    - "unproven"
+    - "pseudoscience"
+    - "hoax"
+    - "wrong"
+    - "fake"
+    - "fabricated"
+    - "baseless"
+    - "discredited"
+    - "debunks"
+    - "false claim"
+    - "does not cause"
+    - "no link"
+    - "unrelated"
+    - "no connection"
+    - "scientists say false"
+    - "experts say false"
+    - "is not true"
+    - "is not real"
+
+  # Strong supporting signals (one hit = supporting)
+  supporting_keywords:
+    - "confirms"
+    - "confirmed"
+    - "verified"
+    - "validated"
+    - "proven"
+    - "evidence shows"
+    - "data shows"
+    - "research shows"
+    - "study finds"
+    - "scientists confirm"
+    - "officially announced"
+    - "official statement"
+    - "press release"
+    - "gazette notification"
+    - "government confirms"
+    - "approved"
+    - "endorsed"
+    - "supported by evidence"
+    - "according to official"
+    - "ministry confirms"
+    - "is true"
+    - "is real"
+    - "has been confirmed"
+    - "study confirms"
+    - "research confirms"
+    - "data confirms"
+
+# ---------------------------------------------------------------------------
+# EVIDENCE SUFFICIENCY (used by environment to set status_flags)
+# ---------------------------------------------------------------------------
+evidence_thresholds:
+  min_sources_for_decision: 2
+  min_claims_verified_fraction: 0.5   # at least 50% of claims must be verified
+  min_reliable_source_score: 0.6      # at least one source must exceed this

enhanced_stance_classifier.py

@@ -0,0 +1,798 @@
+"""
+enhanced_stance_classifier.py
+=============================
+Advanced stance classification system with improved context understanding,
+multi-template NLI, and confidence-based decision making.
+
+Key improvements over the original stance_classifier.py:
+1. Enhanced text preprocessing with intelligent chunking
+2. Multiple NLI templates for different claim types
+3. Better context extraction and relevance scoring
+4. Confidence-based aggregation with fallback strategies
+5. Domain-specific semantic rules for common misinformation topics
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import time
+from typing import Dict, List, Optional, Tuple, Any
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger("enhanced_stance_classifier")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Enhanced Text Processing
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TextProcessor:
+    """Advanced text preprocessing with intelligent chunking and cleaning."""
+    
+    def __init__(self):
+        self.sentence_endings = re.compile(r'[.!?]+\s+')
+        self.noise_patterns = [
+            re.compile(r'\[.*?\]'),  # Remove bracketed content
+            re.compile(r'\(.*?\)'),  # Remove parenthetical content (optional)
+            re.compile(r'https?://\S+'),  # Remove URLs
+            re.compile(r'@\w+'),  # Remove mentions
+            re.compile(r'#\w+'),  # Remove hashtags
+            re.compile(r'\s+'),  # Normalize whitespace
+        ]
+    
+    def clean_text(self, text: str) -> str:
+        """Clean and normalize text for better processing."""
+        if not text:
+            return ""
+        
+        # Remove noise patterns
+        cleaned = text
+        for pattern in self.noise_patterns[:-1]:  # Don't apply whitespace normalization yet
+            cleaned = pattern.sub(' ', cleaned)
+        
+        # Normalize whitespace (last pattern)
+        cleaned = self.noise_patterns[-1].sub(' ', cleaned).strip()
+        
+        return cleaned
+    
+    def intelligent_chunk(self, text: str, max_length: int = 512, overlap: int = 50) -> List[str]:
+        """
+        Split text into chunks at sentence boundaries while preserving context.
+        
+        Args:
+            text: Input text to chunk
+            max_length: Maximum characters per chunk
+            overlap: Characters to overlap between chunks for context
+        
+        Returns:
+            List of text chunks with preserved sentence boundaries
+        """
+        if len(text) <= max_length:
+            return [text]
+        
+        sentences = self.sentence_endings.split(text)
+        chunks = []
+        current_chunk = ""
+        
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if not sentence:
+                continue
+                
+            # If adding this sentence would exceed max_length, start a new chunk
+            if len(current_chunk) + len(sentence) > max_length and current_chunk:
+                chunks.append(current_chunk.strip())
+                
+                # Start new chunk with overlap from previous chunk
+                if overlap > 0 and len(current_chunk) > overlap:
+                    current_chunk = current_chunk[-overlap:] + " " + sentence
+                else:
+                    current_chunk = sentence
+            else:
+                current_chunk += " " + sentence if current_chunk else sentence
+        
+        # Add the last chunk
+        if current_chunk.strip():
+            chunks.append(current_chunk.strip())
+        
+        return chunks if chunks else [text[:max_length]]
+    
+    def extract_key_entities(self, text: str) -> List[str]:
+        """Extract key entities and phrases from text."""
+        # Simple entity extraction - can be enhanced with NER models
+        entities = []
+        
+        # Extract capitalized phrases (potential proper nouns)
+        capitalized = re.findall(r'\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b', text)
+        entities.extend(capitalized)
+        
+        # Extract quoted phrases
+        quoted = re.findall(r'"([^"]+)"', text)
+        entities.extend(quoted)
+        
+        # Extract numbers with units
+        numbers = re.findall(r'\b\d+(?:\.\d+)?\s*(?:%|percent|million|billion|thousand)\b', text, re.I)
+        entities.extend(numbers)
+        
+        return list(set(entities))
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Enhanced Semantic Rules
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ClaimType(Enum):
+    HEALTH = "health"
+    POLITICS = "politics"
+    SCIENCE = "science"
+    TECHNOLOGY = "technology"
+    CLIMATE = "climate"
+    ECONOMICS = "economics"
+    GENERAL = "general"
+
+@dataclass
+class SemanticRule:
+    claim_pattern: str
+    source_pattern: str
+    stance: str  # "supporting" or "contradicting"
+    confidence: float
+    claim_types: List[ClaimType]
+
+class EnhancedSemanticLayer:
+    """
+    Advanced semantic heuristics with domain-specific rules and better pattern matching.
+    """
+    
+    def __init__(self):
+        self.rules = self._build_enhanced_rules()
+        self.text_processor = TextProcessor()
+    
+    def _build_enhanced_rules(self) -> List[SemanticRule]:
+        """Build comprehensive semantic rules for different domains."""
+        rules = []
+        
+        # Health/Medical misinformation rules
+        health_rules = [
+            SemanticRule(
+                claim_pattern=r"\bvaccine.{0,30}(cause|causes|causing).{0,30}(autism|death|cancer|infertility|dna)",
+                source_pattern=r"\b(no\s+evidence|debunked|safe|clinical\s+trial|fda\s+approved|peer\s+reviewed)\b",
+                stance="contradicting",
+                confidence=0.9,
+                claim_types=[ClaimType.HEALTH]
+            ),
+            SemanticRule(
+                claim_pattern=r"\bcovid.{0,20}(hoax|fake|planned|bioweapon)",
+                source_pattern=r"\b(who|cdc|health\s+officials|scientific\s+consensus|peer\s+reviewed)\b",
+                stance="contradicting",
+                confidence=0.85,
+                claim_types=[ClaimType.HEALTH]
+            ),
+            SemanticRule(
+                claim_pattern=r"\b(cure|treatment|remedy).{0,30}(cancer|covid|aids|diabetes)",
+                source_pattern=r"\b(no\s+evidence|unproven|not\s+approved|clinical\s+trial|fda)\b",
+                stance="contradicting",
+                confidence=0.8,
+                claim_types=[ClaimType.HEALTH]
+            ),
+        ]
+        
+        # Technology misinformation rules
+        tech_rules = [
+            SemanticRule(
+                claim_pattern=r"\b5g.{0,30}(cause|spread|transmit).{0,30}(covid|cancer|virus|radiation)",
+                source_pattern=r"\b(no\s+link|no\s+evidence|debunked|scientifically\s+impossible|who\s+says)\b",
+                stance="contradicting",
+                confidence=0.9,
+                claim_types=[ClaimType.TECHNOLOGY]
+            ),
+            SemanticRule(
+                claim_pattern=r"\bmicrochip.{0,30}(vaccine|implant|track|control)",
+                source_pattern=r"\b(conspiracy|debunked|no\s+evidence|fact\s+check|impossible)\b",
+                stance="contradicting",
+                confidence=0.85,
+                claim_types=[ClaimType.TECHNOLOGY]
+            ),
+        ]
+        
+        # Climate misinformation rules
+        climate_rules = [
+            SemanticRule(
+                claim_pattern=r"\bclimate\s+change.{0,20}(hoax|fake|not\s+real|natural)",
+                source_pattern=r"\b(scientific\s+consensus|97\s*%|ipcc|nasa|noaa|peer\s+reviewed)\b",
+                stance="contradicting",
+                confidence=0.9,
+                claim_types=[ClaimType.CLIMATE]
+            ),
+            SemanticRule(
+                claim_pattern=r"\bglobal\s+warming.{0,20}(stopped|pause|cooling)",
+                source_pattern=r"\b(temperature\s+records|warmest\s+year|data\s+shows|scientists\s+confirm)\b",
+                stance="contradicting",
+                confidence=0.8,
+                claim_types=[ClaimType.CLIMATE]
+            ),
+        ]
+        
+        # Political misinformation rules
+        political_rules = [
+            SemanticRule(
+                claim_pattern=r"\belection.{0,30}(stolen|rigged|fraud|fake)",
+                source_pattern=r"\b(courts?\s+reject|no\s+evidence|audit\s+confirms|official\s+results)\b",
+                stance="contradicting",
+                confidence=0.85,
+                claim_types=[ClaimType.POLITICS]
+            ),
+            SemanticRule(
+                claim_pattern=r"\bgovernment.{0,30}(announce|confirm|official)",
+                source_pattern=r"\b(official\s+statement|government\s+website|press\s+release|ministry)\b",
+                stance="supporting",
+                confidence=0.8,
+                claim_types=[ClaimType.POLITICS]
+            ),
+        ]
+        
+        rules.extend(health_rules + tech_rules + climate_rules + political_rules)
+        return rules
+    
+    def classify_claim_type(self, claim: str) -> ClaimType:
+        """Classify the type of claim to apply appropriate rules."""
+        claim_lower = claim.lower()
+        
+        health_keywords = ["vaccine", "covid", "virus", "cancer", "health", "medical", "drug", "treatment"]
+        tech_keywords = ["5g", "microchip", "ai", "technology", "internet", "phone", "radiation"]
+        climate_keywords = ["climate", "warming", "carbon", "emission", "fossil", "renewable", "temperature"]
+        political_keywords = ["election", "government", "president", "vote", "congress", "parliament", "policy"]
+        science_keywords = ["study", "research", "scientist", "experiment", "evidence", "data", "peer review"]
+        economics_keywords = ["economy", "inflation", "gdp", "unemployment", "market", "recession", "financial"]
+        
+        keyword_sets = [
+            (health_keywords, ClaimType.HEALTH),
+            (tech_keywords, ClaimType.TECHNOLOGY),
+            (climate_keywords, ClaimType.CLIMATE),
+            (political_keywords, ClaimType.POLITICS),
+            (science_keywords, ClaimType.SCIENCE),
+            (economics_keywords, ClaimType.ECONOMICS),
+        ]
+        
+        max_matches = 0
+        best_type = ClaimType.GENERAL
+        
+        for keywords, claim_type in keyword_sets:
+            matches = sum(1 for kw in keywords if kw in claim_lower)
+            if matches > max_matches:
+                max_matches = matches
+                best_type = claim_type
+        
+        return best_type
+    
+    def classify(self, claim: str, source_text: str) -> Optional[Tuple[str, float]]:
+        """
+        Enhanced semantic classification with domain-specific rules.
+        
+        Returns:
+            (stance, confidence) or None if no rule matches
+        """
+        claim_type = self.classify_claim_type(claim)
+        claim_lower = claim.lower()
+        source_lower = source_text.lower()
+        
+        # Apply rules relevant to the claim type
+        for rule in self.rules:
+            if claim_type in rule.claim_types or ClaimType.GENERAL in rule.claim_types:
+                if re.search(rule.claim_pattern, claim_lower) and re.search(rule.source_pattern, source_lower):
+                    logger.debug(
+                        "Enhanced semantic rule matched: %s -> %s (conf=%.2f)",
+                        rule.claim_pattern[:40], rule.stance, rule.confidence
+                    )
+                    return rule.stance, rule.confidence
+        
+        return None
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Multi-Template NLI Layer
+# ─────────────────────────────────────────────────────────────────────────────
+
+class NLITemplateManager:
+    """Manages multiple NLI templates for different claim types and contexts."""
+    
+    def __init__(self):
+        self.templates = self._build_templates()
+    
+    def _build_templates(self) -> Dict[ClaimType, List[str]]:
+        """Build claim-type specific NLI templates."""
+        return {
+            ClaimType.HEALTH: [
+                "This text confirms that {}",
+                "This text disproves that {}",
+                "According to this source, {} is true",
+                "According to this source, {} is false",
+                "Medical evidence shows that {}",
+                "Medical evidence contradicts that {}",
+            ],
+            ClaimType.SCIENCE: [
+                "Scientific research confirms that {}",
+                "Scientific research contradicts that {}",
+                "Studies show that {}",
+                "Studies disprove that {}",
+                "Evidence supports that {}",
+                "Evidence refutes that {}",
+            ],
+            ClaimType.POLITICS: [
+                "Official sources confirm that {}",
+                "Official sources deny that {}",
+                "Government records show that {}",
+                "Government records contradict that {}",
+                "Political analysis supports that {}",
+                "Political analysis disputes that {}",
+            ],
+            ClaimType.TECHNOLOGY: [
+                "Technical analysis confirms that {}",
+                "Technical analysis disproves that {}",
+                "Technology experts agree that {}",
+                "Technology experts dispute that {}",
+                "Research demonstrates that {}",
+                "Research contradicts that {}",
+            ],
+            ClaimType.CLIMATE: [
+                "Climate data confirms that {}",
+                "Climate data contradicts that {}",
+                "Environmental research shows that {}",
+                "Environmental research disproves that {}",
+                "Scientific consensus supports that {}",
+                "Scientific consensus rejects that {}",
+            ],
+            ClaimType.GENERAL: [
+                "This text supports the claim that {}",
+                "This text contradicts the claim that {}",
+                "Evidence shows that {}",
+                "Evidence disproves that {}",
+                "This information confirms that {}",
+                "This information refutes that {}",
+            ]
+        }
+    
+    def get_templates(self, claim_type: ClaimType) -> List[str]:
+        """Get appropriate templates for a claim type."""
+        return self.templates.get(claim_type, self.templates[ClaimType.GENERAL])
+
+class EnhancedNLILayer:
+    """
+    Enhanced NLI layer with multiple templates, better preprocessing, and confidence calibration.
+    """
+    
+    def __init__(self):
+        self.template_manager = NLITemplateManager()
+        self.text_processor = TextProcessor()
+        self._cache: Dict[str, Tuple[str, float]] = {}
+        self._enabled = os.getenv("STANCE_NLI_ENABLED", "true").lower() != "false"
+    
+    def available(self) -> bool:
+        return self._enabled
+    
+    def classify(self, claim: str, title: str, text: str, claim_type: ClaimType = ClaimType.GENERAL) -> Optional[Tuple[str, float]]:
+        """
+        Enhanced NLI classification with multiple templates and better preprocessing.
+        
+        Returns:
+            (stance, confidence) or None if classification fails
+        """
+        if not self._enabled:
+            return None
+        
+        # Create cache key — use more text to discriminate full articles
+        cache_key = hashlib.md5(
+            f"{claim[:120]}||{title[:80]}||{text[:600]}||{claim_type.value}".encode()
+        ).hexdigest()
+
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        # Clean and chunk the text — use larger chunks to handle full articles
+        combined_text = self.text_processor.clean_text(f"{title} {text}")
+        text_chunks = self.text_processor.intelligent_chunk(combined_text, max_length=1000)
+        
+        # Get appropriate templates for this claim type
+        templates = self.template_manager.get_templates(claim_type)
+        
+        # Try multiple approaches and aggregate results
+        results = []
+        
+        for chunk in text_chunks[:5]:  # Process up to 5 chunks to cover full articles
+            for template_pair in [templates[i:i+2] for i in range(0, len(templates), 2)]:
+                if len(template_pair) == 2:
+                    support_template, contradict_template = template_pair
+                    result = self._classify_with_templates(claim, chunk, support_template, contradict_template)
+                    if result:
+                        results.append(result)
+        
+        if not results:
+            return None
+        
+        # Aggregate results with confidence weighting
+        final_stance, final_confidence = self._aggregate_results(results)
+        
+        # Cache the result
+        self._cache[cache_key] = (final_stance, final_confidence)
+        
+        logger.debug(
+            "Enhanced NLI: '%s...' -> %s (conf=%.2f) from %d results",
+            claim[:40], final_stance, final_confidence, len(results)
+        )
+        
+        return final_stance, final_confidence
+    
+    def _classify_with_templates(self, claim: str, text: str, support_template: str, contradict_template: str) -> Optional[Tuple[str, float]]:
+        """Classify using a pair of support/contradict templates."""
+        try:
+            # Try HF API first, then local transformers
+            result = self._hf_api_classify(claim, text, support_template, contradict_template)
+            if result:
+                return result
+            
+            result = self._local_classify(claim, text, support_template, contradict_template)
+            return result
+            
+        except Exception as exc:
+            logger.debug("Template classification failed: %s", exc)
+            return None
+    
+    def _hf_api_classify(self, claim: str, text: str, support_template: str, contradict_template: str) -> Optional[Tuple[str, float]]:
+        """Use HuggingFace API for classification."""
+        try:
+            import requests
+        except ImportError:
+            return None
+        
+        hf_token = os.getenv("HF_TOKEN", "")
+        if not hf_token or hf_token.startswith("your_"):
+            return None
+        
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {hf_token}",
+        }
+        
+        # Use zero-shot classification with custom templates
+        payload = {
+            "inputs": text,
+            "parameters": {
+                "candidate_labels": [
+                    support_template.format(claim),
+                    contradict_template.format(claim),
+                    "This text is unrelated to the claim"
+                ],
+                "multi_label": False,
+            },
+        }
+        
+        try:
+            resp = requests.post(
+                "https://api-inference.huggingface.co/models/facebook/bart-large-mnli",
+                headers=headers,
+                json=payload,
+                timeout=15
+            )
+            
+            if resp.status_code in (503, 502):
+                return None
+            
+            if not resp.ok:
+                return None
+            
+            data = resp.json()
+            return self._parse_hf_response(data)
+            
+        except Exception:
+            return None
+    
+    def _local_classify(self, claim: str, text: str, support_template: str, contradict_template: str) -> Optional[Tuple[str, float]]:
+        """Use local transformers for classification."""
+        try:
+            from transformers import pipeline
+            
+            # Initialize pipeline if not already done
+            if not hasattr(self, '_local_pipeline'):
+                self._local_pipeline = pipeline(
+                    "zero-shot-classification",
+                    model="facebook/bart-large-mnli",
+                    device=-1  # CPU
+                )
+            
+            result = self._local_pipeline(
+                text,
+                candidate_labels=[
+                    support_template.format(claim),
+                    contradict_template.format(claim),
+                    "unrelated"
+                ]
+            )
+            
+            labels = result["labels"]
+            scores = result["scores"]
+            
+            if "unrelated" in labels[0].lower():
+                return "neutral", float(scores[0])
+            elif support_template.format("").strip() in labels[0]:
+                return "supporting", float(scores[0])
+            else:
+                return "contradicting", float(scores[0])
+                
+        except Exception:
+            return None
+    
+    def _parse_hf_response(self, data: dict) -> Optional[Tuple[str, float]]:
+        """Parse HuggingFace API response."""
+        if not data or not isinstance(data, dict):
+            return None
+        
+        labels = data.get("labels", [])
+        scores = data.get("scores", [])
+        
+        if not labels or not scores:
+            return None
+        
+        top_label = labels[0].lower()
+        top_score = float(scores[0])
+        
+        if "unrelated" in top_label:
+            return "neutral", top_score
+        elif any(word in top_label for word in ["confirms", "supports", "true", "shows"]):
+            return "supporting", top_score
+        else:
+            return "contradicting", top_score
+    
+    def _aggregate_results(self, results: List[Tuple[str, float]]) -> Tuple[str, float]:
+        """Aggregate multiple NLI results with confidence weighting."""
+        if not results:
+            return "neutral", 0.2
+        
+        # Weight results by confidence
+        stance_scores = {"supporting": 0.0, "contradicting": 0.0, "neutral": 0.0}
+        total_weight = 0.0
+        
+        for stance, confidence in results:
+            stance_scores[stance] += confidence
+            total_weight += confidence
+        
+        if total_weight == 0:
+            return "neutral", 0.2
+        
+        # Normalize scores
+        for stance in stance_scores:
+            stance_scores[stance] /= total_weight
+        
+        # Find the highest scoring stance
+        best_stance = max(stance_scores, key=stance_scores.get)
+        best_score = stance_scores[best_stance]
+        
+        # Adjust confidence based on margin and number of results
+        margin = best_score - max(score for stance, score in stance_scores.items() if stance != best_stance)
+        confidence = min(0.95, best_score + margin * 0.1 + len(results) * 0.05)
+        
+        return best_stance, confidence
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Enhanced Keyword Layer
+# ─────────────────────────────────────────────────────────────────────────────
+
+class EnhancedKeywordLayer:
+    """Enhanced keyword matching with context awareness and better thresholds."""
+    
+    def __init__(self):
+        self.strong_contra = {
+            "false", "debunked", "disproven", "misinformation", "misleading",
+            "no evidence", "lacks evidence", "unfounded", "refuted", "myth",
+            "conspiracy theory", "fact-check", "factcheck", "incorrect",
+            "not true", "inaccurate", "unproven", "pseudoscience", "hoax",
+            "wrong", "fake", "fabricated", "baseless", "discredited",
+            "impossible", "scientifically impossible", "medically impossible"
+        }
+        
+        self.weak_contra = {
+            "disputed", "controversial", "unverified", "claims", "alleged",
+            "questioned", "skeptics", "critics", "challenged", "contradicts",
+            "refutes", "rejects", "warns against", "cautioned", "doubtful",
+            "uncertain", "unclear", "mixed evidence", "conflicting"
+        }
+        
+        self.strong_support = {
+            "confirms", "confirmed", "verified", "validated", "proven",
+            "evidence shows", "data shows", "research shows", "study finds",
+            "scientists confirm", "officially announced", "official statement",
+            "press release", "gazette notification", "government confirms",
+            "approved", "endorsed", "supported by evidence", "peer reviewed",
+            "clinical trial", "fda approved", "who approved", "scientifically proven"
+        }
+        
+        self.weak_support = {
+            "suggests", "indicates", "shows", "demonstrates", "according to",
+            "reports", "states", "announced", "published", "found that",
+            "appears", "seems", "likely", "probably", "research indicates",
+            "studies suggest", "data indicates", "preliminary results"
+        }
+        
+        self.context_modifiers = {
+            "negation": ["not", "no", "never", "none", "neither", "without"],
+            "uncertainty": ["may", "might", "could", "possibly", "perhaps", "maybe"],
+            "emphasis": ["definitely", "certainly", "absolutely", "clearly", "obviously"]
+        }
+    
+    def classify(self, text: str, claim: str = "") -> Tuple[str, float]:
+        """
+        Enhanced keyword classification with context awareness.
+        
+        Returns:
+            (stance, confidence)
+        """
+        text_lower = text.lower()
+        
+        # Count keyword matches
+        strong_contra_count = sum(1 for kw in self.strong_contra if kw in text_lower)
+        weak_contra_count = sum(1 for kw in self.weak_contra if kw in text_lower)
+        strong_support_count = sum(1 for kw in self.strong_support if kw in text_lower)
+        weak_support_count = sum(1 for kw in self.weak_support if kw in text_lower)
+        
+        # Check for context modifiers
+        negation_count = sum(1 for kw in self.context_modifiers["negation"] if kw in text_lower)
+        uncertainty_count = sum(1 for kw in self.context_modifiers["uncertainty"] if kw in text_lower)
+        emphasis_count = sum(1 for kw in self.context_modifiers["emphasis"] if kw in text_lower)
+        
+        # Calculate weighted scores
+        contra_score = strong_contra_count * 3 + weak_contra_count * 1
+        support_score = strong_support_count * 3 + weak_support_count * 1
+        
+        # Apply context modifiers
+        if negation_count > 0:
+            # Negation can flip the meaning
+            if contra_score > support_score:
+                contra_score *= 0.5  # Reduce contradiction confidence
+            elif support_score > contra_score:
+                support_score *= 0.5  # Reduce support confidence
+        
+        # Uncertainty reduces confidence
+        uncertainty_penalty = min(0.3, uncertainty_count * 0.1)
+        
+        # Emphasis increases confidence
+        emphasis_bonus = min(0.2, emphasis_count * 0.05)
+        
+        # Determine stance and confidence
+        if strong_contra_count >= 1 and contra_score > support_score:
+            base_confidence = min(0.9, 0.6 + strong_contra_count * 0.1)
+            confidence = base_confidence - uncertainty_penalty + emphasis_bonus
+            return "contradicting", max(0.3, confidence)
+        
+        if strong_support_count >= 1 and support_score > contra_score:
+            base_confidence = min(0.9, 0.6 + strong_support_count * 0.1)
+            confidence = base_confidence - uncertainty_penalty + emphasis_bonus
+            return "supporting", max(0.3, confidence)
+        
+        if contra_score >= 2 and contra_score > support_score:
+            confidence = 0.5 - uncertainty_penalty + emphasis_bonus
+            return "contradicting", max(0.2, confidence)
+        
+        if support_score >= 2 and support_score > contra_score:
+            confidence = 0.5 - uncertainty_penalty + emphasis_bonus
+            return "supporting", max(0.2, confidence)
+        
+        # Default to neutral with low confidence
+        return "neutral", 0.2
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main Enhanced Stance Classifier
+# ─────────────────────────────────────────────────────────────────────────────
+
+class EnhancedStanceClassifier:
+    """
+    Advanced stance classifier combining enhanced semantic rules, improved NLI,
+    and better keyword matching with confidence-based decision making.
+    """
+    
+    def __init__(self):
+        self.semantic_layer = EnhancedSemanticLayer()
+        self.keyword_layer = EnhancedKeywordLayer()
+        self.nli_layer = EnhancedNLILayer()
+        self.text_processor = TextProcessor()
+        
+        # Confidence thresholds for each layer
+        self.semantic_threshold = 0.7
+        self.keyword_threshold = 0.6
+        self.nli_threshold = 0.5
+        
+        # Minimum source reliability for NLI layer
+        self.nli_min_reliability = float(os.getenv("STANCE_NLI_MIN_REL", "0.3"))
+    
+    def classify(self, text: str, claim: str) -> str:
+        """
+        Backward-compatible interface for simple stance classification.
+        
+        Returns:
+            stance string: "supporting" | "contradicting" | "neutral"
+        """
+        stance, _, _ = self.classify_detailed(
+            title="", text=text, claim=claim, source_reliability=0.5
+        )
+        return stance
+    
+    def classify_detailed(
+        self,
+        title: str,
+        text: str,
+        claim: str,
+        source_reliability: float = 0.5,
+    ) -> Tuple[str, float, str]:
+        """
+        Enhanced stance classification with detailed output.
+        
+        Args:
+            title: Source title
+            text: Source text content
+            claim: Claim to verify against
+            source_reliability: Reliability score of the source (0.0-1.0)
+        
+        Returns:
+            (stance, confidence, winning_layer)
+        """
+        # Clean and preprocess text
+        combined_text = self.text_processor.clean_text(f"{title} {text}")
+        claim_type = self.semantic_layer.classify_claim_type(claim)
+        
+        # Layer 1: Enhanced Semantic Heuristics
+        semantic_result = self.semantic_layer.classify(claim, combined_text)
+        if semantic_result and semantic_result[1] >= self.semantic_threshold:
+            stance, confidence = semantic_result
+            logger.debug("Enhanced semantic layer: %s (%.2f)", stance, confidence)
+            return stance, confidence, "semantic"
+        
+        # Layer 2: Enhanced Keyword Matching
+        keyword_stance, keyword_conf = self.keyword_layer.classify(combined_text, claim)
+        if keyword_conf >= self.keyword_threshold:
+            logger.debug("Enhanced keyword layer: %s (%.2f)", keyword_stance, keyword_conf)
+            return keyword_stance, keyword_conf, "keyword"
+        
+        # Layer 3: Enhanced NLI (only for reliable sources)
+        if (self.nli_layer.available() and 
+            source_reliability >= self.nli_min_reliability):
+            
+            nli_result = self.nli_layer.classify(claim, title, text, claim_type)
+            if nli_result and nli_result[1] >= self.nli_threshold:
+                stance, confidence = nli_result
+                logger.debug("Enhanced NLI layer: %s (%.2f)", stance, confidence)
+                return stance, confidence, "nli"
+        
+        # Fallback: Use best available result with adjusted confidence
+        best_result = None
+        best_confidence = 0.0
+        best_layer = "fallback"
+        
+        if semantic_result and semantic_result[1] > best_confidence:
+            best_result = semantic_result
+            best_confidence = semantic_result[1]
+            best_layer = "semantic_fallback"
+        
+        if keyword_conf > best_confidence:
+            best_result = (keyword_stance, keyword_conf)
+            best_confidence = keyword_conf
+            best_layer = "keyword_fallback"
+        
+        if best_result:
+            stance, confidence = best_result
+            # Reduce confidence for fallback results
+            adjusted_confidence = confidence * 0.7
+            logger.debug("Fallback layer (%s): %s (%.2f -> %.2f)", 
+                        best_layer, stance, confidence, adjusted_confidence)
+            return stance, adjusted_confidence, best_layer
+        
+        # Ultimate fallback
+        return "neutral", 0.1, "default"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Factory function for backward compatibility
+# ─────────────────────────────────────────────────────────────────────────────
+
+def build_enhanced_stance_classifier(scorer=None) -> EnhancedStanceClassifier:
+    """Factory function to create enhanced stance classifier."""
+    return EnhancedStanceClassifier()
+
+# Alias for easy import
+StanceClassifier = EnhancedStanceClassifier

environment.py

@@ -0,0 +1,631 @@
+"""
+environment.py
+==============
+OpenEnv-compliant InformationIntegrityEnv.
+
+The environment is 100% offline and deterministic once a scenario has been
+collected by data_collector.py.  It accepts any scenario dict produced by
+DataCollector.collect() — no hardcoded content.
+
+OpenEnv contract
+----------------
+  env = InformationIntegrityEnv(scenario)
+  obs               = env.reset()
+  obs, rew, done, info = env.step(action)
+  state_dict        = env.state()
+
+Action space
+------------
+  verify_claim  claim_id                  → VerificationResult
+  check_source  source_id                 → SourceEvidence
+  decide        decision (allow/flag/remove) → episode ends
+
+Observation
+-----------
+  content, claims (status masked), available_sources,
+  interaction_history, status_flags, step_count
+
+Design invariants
+-----------------
+  - Ground truth NEVER exposed in Observation
+  - All randomness eliminated (same action sequence → same result)
+  - Reward computed by reward.py (configurable, not hardcoded here)
+  - Scenario loaded once at __init__; reset() clears episode state only
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+import time
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+import yaml
+
+from models import (
+    Action,
+    ActionType,
+    Claim,
+    DecisionType,
+    EpisodeResult,
+    InteractionRecord,
+    Observation,
+    Reward,
+    RewardBreakdown,
+    Scenario,
+    ScenarioClaim,
+    ScenarioSource,
+    SourceInfo,
+    Stance,
+    StatusFlags,
+    VerificationStatus,
+)
+from reward import EpisodeRewardState, RewardFunction
+
+try:
+    from retrieval import RetrievalPipeline
+    from reasoning import DeterministicReasoningEngine, reason_over_claims
+    _RETRIEVAL_AVAILABLE = True
+except Exception:
+    _RETRIEVAL_AVAILABLE = False
+
+RELIABILITY_CONFIG_PATH = os.getenv("RELIABILITY_CONFIG", "domain_reliability.yaml")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_evidence_thresholds() -> dict:
+    if os.path.exists(RELIABILITY_CONFIG_PATH):
+        with open(RELIABILITY_CONFIG_PATH, "r", encoding="utf-8") as fh:
+            cfg = yaml.safe_load(fh) or {}
+        return cfg.get("evidence_thresholds", {})
+    return {}
+
+
+def _scenario_from_dict(d: dict) -> Scenario:
+    """Deserialise a raw scenario dict (e.g. from DataCollector) into a Scenario model."""
+    claims = [ScenarioClaim(**c) for c in d["claims"]]
+    sources = [ScenarioSource(**s) for s in d["sources"]]
+    return Scenario(
+        id=d.get("id", str(uuid.uuid4())),
+        difficulty=d.get("difficulty", "medium"),
+        content=d["content"],
+        claims=claims,
+        sources=sources,
+        ground_truth=d["ground_truth"],
+        topic=d.get("topic", ""),
+        tags=d.get("tags", []),
+        explanation_hint=d.get("explanation_hint", ""),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main environment class
+# ---------------------------------------------------------------------------
+
+class InformationIntegrityEnv:
+    """
+    OpenEnv environment for reasoning-based content moderation.
+
+    Parameters
+    ----------
+    scenario : dict | Scenario
+        A collected scenario (from DataCollector) or a pre-built Scenario object.
+    max_steps : int
+        Maximum steps per episode (default 20).
+    reward_fn : RewardFunction | None
+        Pluggable reward function (default: RewardFunction()).
+    """
+
+    # Public metadata (read by openenv validate)
+    ENV_NAME    = "InformationIntegrityEnv"
+    ENV_VERSION = "1.0.0"
+    ENV_AUTHOR  = "openenv-content-moderation"
+
+    def __init__(
+        self,
+        scenario: dict | Scenario,
+        max_steps: int = 20,
+        reward_fn: Optional[RewardFunction] = None,
+    ) -> None:
+        if isinstance(scenario, dict):
+            scenario = _scenario_from_dict(scenario)
+        self._scenario   : Scenario          = scenario
+        self._max_steps  : int               = max_steps
+        self._reward_fn  : RewardFunction    = reward_fn or RewardFunction()
+        self._thresholds : dict              = _load_evidence_thresholds()
+
+        # Episode state (initialised by reset)
+        self._episode_id : str               = ""
+        self._claims     : List[Claim]       = []
+        self._history    : List[InteractionRecord] = []
+        self._flags      : StatusFlags       = StatusFlags()
+        self._step_count : int               = 0
+        self._done       : bool              = False
+        self._final_decision: Optional[str]  = None
+        self._reward_state: EpisodeRewardState = EpisodeRewardState()
+
+        # Index for fast lookup
+        self._source_index : Dict[str, ScenarioSource] = {
+            s.id: s for s in self._scenario.sources
+        }
+        self._claim_index  : Dict[str, ScenarioClaim]  = {
+            c.id: c for c in self._scenario.claims
+        }
+
+        # Retrieval + reasoning engines (lazy init for pickle compat)
+        self._retrieval_pipeline: Optional[Any] = None
+        self._reasoning_engine:   Optional[Any] = None
+        self._last_reasoning:     Optional[Any] = None  # StructuredReasoning cached
+
+    # ------------------------------------------------------------------
+    # OpenEnv API
+    # ------------------------------------------------------------------
+
+    def reset(
+        self,
+        difficulty: Optional[str] = None,
+        scenario_id: Optional[str | int] = None,
+    ) -> Observation:
+        """
+        Reset episode state and return initial observation.
+
+        Programmatic difficulty control (no UI dependency):
+
+        Parameters
+        ----------
+        difficulty : str | None
+            If provided, load a new scenario from the deterministic dataset
+            for that difficulty tier ('easy', 'medium', 'hard').
+            Overrides the scenario supplied at __init__ time.
+        scenario_id : str | int | None
+            Index (int) or scenario id (str) within the difficulty dataset.
+            If None and difficulty is provided, a random scenario is selected.
+            Ignored when difficulty is None.
+        """
+        if difficulty is not None:
+            from tasks.registry import TASKS
+            import random as _random
+            task = TASKS[difficulty]
+            if scenario_id is None:
+                sc_dict = task.sample()
+            else:
+                sc_dict = task.get_scenario(scenario_id)
+            self._scenario    = _scenario_from_dict(sc_dict)
+            self._source_index = {s.id: s for s in self._scenario.sources}
+            self._claim_index  = {c.id: c for c in self._scenario.claims}
+
+        self._episode_id      = str(uuid.uuid4())
+        self._step_count      = 0
+        self._done            = False
+        self._final_decision  = None
+        self._history         = []
+        self._flags           = StatusFlags()
+        self._reward_state    = EpisodeRewardState()
+        self._last_reasoning  = None
+
+        # Reinitialise mutable claim states (no ground-truth exposed)
+        self._claims = [
+            Claim(id=c.id, text=c.text)
+            for c in self._scenario.claims
+        ]
+
+        return self._build_observation()
+
+    def step(self, action: Action) -> Tuple[Observation, Reward, bool, Dict[str, Any]]:
+        """
+        Process one agent action.
+
+        Returns
+        -------
+        observation : Observation
+        reward      : Reward
+        done        : bool
+        info        : dict  (extra diagnostics — not for agent use)
+        """
+        if self._done:
+            raise RuntimeError(
+                "Episode has ended. Call reset() to start a new episode."
+            )
+
+        self._step_count += 1
+        self._reward_state.step_count = self._step_count
+
+        if action.type == ActionType.VERIFY_CLAIM:
+            step_reward, result = self._handle_verify_claim(action)
+        elif action.type == ActionType.CHECK_SOURCE:
+            step_reward, result = self._handle_check_source(action)
+        elif action.type == ActionType.DECIDE:
+            step_reward, result = self._handle_decide(action)
+        else:
+            raise ValueError(f"Unknown action type: {action.type}")
+
+        # Max-steps check
+        if self._step_count >= self._max_steps and not self._done:
+            self._done = True
+            self._flags.max_steps_reached = True
+            result["max_steps_reached"] = True
+
+        # Update evidence sufficiency flag
+        self._flags.sufficient_evidence = self._check_sufficient_evidence()
+
+        # Log interaction
+        record = InteractionRecord(
+            step=self._step_count,
+            action_type=action.type,
+            action_payload=action.model_dump(exclude_none=True),
+            result=result,
+            reward_delta=step_reward,
+        )
+        self._history.append(record)
+
+        obs    = self._build_observation()
+        reward = self._build_reward(step_reward, result.get("message", ""))
+        info   = {
+            "episode_id": self._episode_id,
+            "step":       self._step_count,
+            "done":       self._done,
+            **result,
+        }
+        return obs, reward, self._done, info
+
+    def state(self) -> Dict[str, Any]:
+        """Return full internal state (for debugging / logging — not for agent)."""
+        return {
+            "episode_id":       self._episode_id,
+            "scenario_id":      self._scenario.id,
+            "difficulty":       self._scenario.difficulty,
+            "step_count":       self._step_count,
+            "done":             self._done,
+            "final_decision":   self._final_decision,
+            "ground_truth":     self._scenario.ground_truth,  # hidden from agent obs
+            "claims": [
+                {
+                    "id":                  c.id,
+                    "text":                c.text,
+                    "verification_status": c.verification_status,
+                    "confidence":          c.confidence,
+                }
+                for c in self._claims
+            ],
+            "reward_breakdown": self._reward_fn.breakdown_dict(self._reward_state),
+            "flags":            self._flags.model_dump(),
+            "history_len":      len(self._history),
+            "last_reasoning":   (
+                {ct: r.to_dict() for ct, r in self._last_reasoning.items()}
+                if self._last_reasoning else None
+            ),
+        }
+
+    def episode_result(self, explanation: Optional[str] = None) -> EpisodeResult:
+        """Build a final EpisodeResult (call after done=True)."""
+        bd = self._reward_fn.breakdown_dict(self._reward_state)
+        ground_truth = self._scenario.ground_truth
+        correct = self._final_decision == ground_truth
+
+        from tasks.graders import GraderFactory
+        grader = GraderFactory.get(self._scenario.difficulty)
+        grader_score = grader.score(
+            decision=self._final_decision or "none",
+            ground_truth=ground_truth,
+            sources_checked=list(self._reward_state.checked_sources),
+            claims_verified=list(self._reward_state.verified_claims),
+            step_count=self._step_count,
+            all_source_ids=[s.id for s in self._scenario.sources],
+            all_claim_ids=[c.id for c in self._scenario.claims],
+        )
+
+        return EpisodeResult(
+            episode_id=self._episode_id,
+            task_difficulty=self._scenario.difficulty,
+            scenario_index=0,
+            total_reward=self._reward_fn.final_score(self._reward_state),
+            decision=self._final_decision,
+            ground_truth=ground_truth,
+            correct=correct,
+            steps_taken=self._step_count,
+            claims_verified=len(self._reward_state.verified_claims),
+            sources_checked=len(self._reward_state.checked_sources),
+            grader_score=grader_score,
+            reward_breakdown=RewardBreakdown(
+                verify_claim_reward=bd["verify_claim_reward"],
+                check_source_reward=bd["check_source_reward"],
+                multi_source_bonus=bd["multi_source_bonus"],
+                decision_reward=bd["decision_reward"],
+                premature_penalty=bd["premature_penalty"],
+                redundant_penalty=bd["redundant_penalty"],
+                inefficiency_penalty=bd["inefficiency_penalty"],
+                aggression_penalty=bd["aggression_penalty"],
+            ),
+            explanation=explanation,
+        )
+
+    # ------------------------------------------------------------------
+    # Action handlers
+    # ------------------------------------------------------------------
+
+    def _handle_verify_claim(self, action: Action) -> Tuple[float, dict]:
+        claim_id = action.claim_id
+        if claim_id not in self._claim_index:
+            return 0.0, {"error": f"Unknown claim_id: {claim_id}"}
+
+        scenario_claim = self._claim_index[claim_id]
+        agent_claim    = self._get_agent_claim(claim_id)
+
+        # Reveal verification status from scenario ground truth (masked from Observation)
+        status     = scenario_claim.ground_truth_status
+        confidence = scenario_claim.ground_truth_confidence
+
+        # Use RetrievalPipeline to find the most relevant sources for THIS claim
+        if _RETRIEVAL_AVAILABLE:
+            if self._retrieval_pipeline is None:
+                self._retrieval_pipeline = RetrievalPipeline()
+            raw_sources = [
+                {
+                    "id":          s.id,
+                    "title":       s.title,
+                    "text":        s.text,
+                    "url":         s.url,
+                    "stance":      s.stance,
+                    "reliability": s.reliability,
+                    "source_type": s.source_type,
+                }
+                for s in self._scenario.sources
+            ]
+            ranked = self._retrieval_pipeline.retrieve(scenario_claim.text, raw_sources)
+            relevant_sources = [s.id for s in ranked[:5]]
+        else:
+            relevant_sources = [
+                s.id for s in self._scenario.sources
+                if s.stance in ("contradicting", "supporting")
+            ]
+
+        # Update mutable claim object
+        agent_claim.verification_status = VerificationStatus(status)
+        agent_claim.confidence          = confidence
+        agent_claim.verified_by_sources = relevant_sources[:3]
+
+        # Reward
+        r, msg = self._reward_fn.compute_verify_claim(claim_id, self._reward_state)
+
+        result: dict = {
+            "claim_id":          claim_id,
+            "status":            status,
+            "confidence":        confidence,
+            "message":           msg,
+            "relevant_sources":  relevant_sources,
+            "hint":              f"Claim '{scenario_claim.text[:60]}…' assessed as {status}",
+        }
+        return r, result
+
+    def _handle_check_source(self, action: Action) -> Tuple[float, dict]:
+        source_id = action.source_id
+        if source_id not in self._source_index:
+            return 0.0, {"error": f"Unknown source_id: {source_id}"}
+
+        src = self._source_index[source_id]
+
+        # Reward
+        r, msg = self._reward_fn.compute_check_source(source_id, self._reward_state)
+
+        result: dict = {
+            "source_id":   source_id,
+            "title":       src.title,
+            "text":        src.text,
+            "url":         src.url,
+            "stance":      src.stance,
+            "reliability": src.reliability,
+            "source_type": src.source_type,
+            "message":     msg,
+        }
+        return r, result
+
+    def _handle_decide(self, action: Action) -> Tuple[float, dict]:
+        decision     = action.decision
+        ground_truth = self._scenario.ground_truth
+        num_claims   = len(self._scenario.claims)
+
+        # Run deterministic reasoning engine if available
+        reasoning_summary = {}
+        if _RETRIEVAL_AVAILABLE:
+            if self._retrieval_pipeline is None:
+                self._retrieval_pipeline = RetrievalPipeline()
+            if self._reasoning_engine is None:
+                self._reasoning_engine = DeterministicReasoningEngine()
+
+            raw_sources = [
+                {
+                    "id":          s.id,
+                    "title":       s.title,
+                    "text":        s.text,
+                    "url":         s.url,
+                    "stance":      s.stance,
+                    "reliability": s.reliability,
+                    "source_type": s.source_type,
+                }
+                for s in self._scenario.sources
+            ]
+            claim_texts = [c.text for c in self._scenario.claims]
+            claim_results = self._retrieval_pipeline.retrieve_for_all_claims(
+                claim_texts, raw_sources
+            )
+            agg_decision, per_claim_reasoning = reason_over_claims(
+                claim_results, self._reasoning_engine
+            )
+            # Cache reasoning for episode_result()
+            self._last_reasoning = per_claim_reasoning
+            reasoning_summary = {
+                "engine_decision": agg_decision,
+                "agent_decision":  decision,
+                "per_claim": {
+                    ct: r.to_dict() for ct, r in per_claim_reasoning.items()
+                },
+            }
+
+        r, msg = self._reward_fn.compute_decision(
+            decision=decision,
+            ground_truth=ground_truth,
+            state=self._reward_state,
+            num_claims=num_claims,
+        )
+
+        self._final_decision      = decision
+        self._done                = True
+        self._flags.decision_made = True
+
+        if "premature" in msg:
+            self._flags.premature_decision = True
+
+        result: dict = {
+            "decision":        decision,
+            "message":         msg,
+            "episode_done":    True,
+            "reasoning":       reasoning_summary,
+        }
+        return r, result
+
+    # ------------------------------------------------------------------
+    # State construction helpers
+    # ------------------------------------------------------------------
+
+    def _build_observation(self) -> Observation:
+        """Build agent-facing Observation — ground truth is NEVER included."""
+        sources_view = [
+            SourceInfo(
+                id=s.id,
+                title=s.title,
+                text=s.text,
+                url=s.url,
+                stance=Stance(s.stance),
+                reliability=s.reliability,
+                source_type=s.source_type,
+            )
+            for s in self._scenario.sources
+        ]
+        return Observation(
+            content=self._scenario.content,
+            claims=copy.deepcopy(self._claims),
+            available_sources=sources_view,
+            interaction_history=list(self._history),
+            status_flags=copy.deepcopy(self._flags),
+            step_count=self._step_count,
+            episode_id=self._episode_id,
+            task_difficulty=self._scenario.difficulty,
+        )
+
+    def _build_reward(self, score: float, message: str) -> Reward:
+        bd = self._reward_fn.breakdown_dict(self._reward_state)
+        return Reward(
+            score=score,
+            breakdown=RewardBreakdown(
+                verify_claim_reward=bd["verify_claim_reward"],
+                check_source_reward=bd["check_source_reward"],
+                multi_source_bonus=bd["multi_source_bonus"],
+                decision_reward=bd["decision_reward"],
+                premature_penalty=bd["premature_penalty"],
+                redundant_penalty=bd["redundant_penalty"],
+                inefficiency_penalty=bd["inefficiency_penalty"],
+                aggression_penalty=bd["aggression_penalty"],
+            ),
+            message=message,
+            is_terminal=self._done,
+        )
+
+    def _get_agent_claim(self, claim_id: str) -> Claim:
+        for c in self._claims:
+            if c.id == claim_id:
+                return c
+        raise KeyError(f"Claim {claim_id} not found in agent state")
+
+    def _check_sufficient_evidence(self) -> bool:
+        thresh = self._thresholds
+        min_sources  = int(thresh.get("min_sources_for_decision", 2))
+        min_verified = float(thresh.get("min_claims_verified_fraction", 0.5))
+        n_claims     = len(self._scenario.claims)
+        n_verified   = len(self._reward_state.verified_claims)
+        n_sources    = len(self._reward_state.checked_sources)
+
+        frac_ok = (n_verified / n_claims >= min_verified) if n_claims > 0 else True
+        return n_sources >= min_sources and frac_ok
+
+    # ------------------------------------------------------------------
+    # Convenience helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def scenario(self) -> Scenario:
+        return self._scenario
+
+    @property
+    def max_steps(self) -> int:
+        return self._max_steps
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    @classmethod
+    def from_dataset(
+        cls,
+        difficulty: str,
+        scenario_id: Optional[str | int] = None,
+        max_steps: int = 20,
+        reward_fn: Optional[RewardFunction] = None,
+    ) -> "InformationIntegrityEnv":
+        """
+        Build an env directly from the deterministic dataset — no DataCollector needed.
+
+        Parameters
+        ----------
+        difficulty : 'easy' | 'medium' | 'hard'
+        scenario_id : int index or str id; None = random selection
+        max_steps   : episode step limit
+        reward_fn   : optional custom RewardFunction
+
+        Example
+        -------
+        env = InformationIntegrityEnv.from_dataset("medium", scenario_id=2)
+        obs = env.reset()
+        """
+        from tasks.registry import TASKS
+        task = TASKS[difficulty]
+        if scenario_id is None:
+            sc_dict = task.sample()
+        else:
+            sc_dict = task.get_scenario(scenario_id)
+        return cls(scenario=sc_dict, max_steps=max_steps, reward_fn=reward_fn)
+
+    @classmethod
+    def from_collector(
+        cls,
+        content: str,
+        claims: List[str],
+        difficulty: str = "medium",
+        **collector_kwargs,
+    ) -> "InformationIntegrityEnv":
+        """
+        Convenience factory: collect a scenario on-the-fly and build an env.
+
+        Example
+        -------
+        env = InformationIntegrityEnv.from_collector(
+            content="Post text here",
+            claims=["Claim A", "Claim B"],
+            difficulty="hard",
+        )
+        obs = env.reset()
+        """
+        from data_collector import CollectionRequest, DataCollector
+
+        collector = DataCollector()
+        request   = CollectionRequest(
+            content=content,
+            claims=claims,
+            difficulty=difficulty,
+            **collector_kwargs,
+        )
+        scenario_dict = collector.collect(request)
+        return cls(scenario=scenario_dict)

explainability.py

@@ -0,0 +1,445 @@
+"""
+explainability.py
+=================
+Structured reasoning objects and template-based explanation generation.
+
+No API calls — fully deterministic.  The explanation is built from the
+agent's actual reasoning trace (claims verified, sources checked, decision)
+so it aligns with every moderation decision and is auditable.
+
+Enterprise platforms (Meta, Instagram, etc.) can:
+  - Replace `generate_explanation` with a call to their internal LLM
+  - Feed `ReasoningObject` into dashboards / audit logs
+  - Extend `DECISION_TEMPLATES` without touching engine code
+"""
+
+from __future__ import annotations
+
+import os
+import textwrap
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+EXPLANATION_CONFIG_PATH = os.getenv("EXPLANATION_CONFIG", "explanation_templates.yaml")
+
+
+# ---------------------------------------------------------------------------
+# Structured reasoning object (what the agent built up during the episode)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SourceEvidence:
+    source_id: str
+    title: str
+    stance: str           # supporting | contradicting | neutral
+    reliability: float
+    key_snippet: str = ""
+
+
+@dataclass
+class ClaimAssessment:
+    claim_id: str
+    claim_text: str
+    verification_status: str   # true | false | partially_true | unknown
+    confidence: float
+    supporting_sources: List[str]  = field(default_factory=list)
+    contradicting_sources: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ReasoningObject:
+    """
+    Complete structured reasoning trace for one episode.
+    Produced by the agent or inference script; consumed by the explainer.
+    """
+    content_summary: str
+    claims: List[ClaimAssessment]
+    sources_used: List[SourceEvidence]
+    decision: str                   # allow | flag | remove
+    confidence: float               # 0–1
+    step_count: int
+    episode_id: str = ""
+    difficulty: str = ""
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    # Derived helpers
+    @property
+    def contradicting_sources(self) -> List[SourceEvidence]:
+        return [s for s in self.sources_used if s.stance == "contradicting"]
+
+    @property
+    def supporting_sources(self) -> List[SourceEvidence]:
+        return [s for s in self.sources_used if s.stance == "supporting"]
+
+    @property
+    def high_reliability_sources(self) -> List[SourceEvidence]:
+        return [s for s in self.sources_used if s.reliability >= 0.80]
+
+    @property
+    def false_claims(self) -> List[ClaimAssessment]:
+        return [c for c in self.claims if c.verification_status in ("false", "partially_true")]
+
+    @property
+    def verified_fraction(self) -> float:
+        if not self.claims:
+            return 0.0
+        verified = sum(
+            1 for c in self.claims
+            if c.verification_status != "unknown"
+        )
+        return verified / len(self.claims)
+
+
+# ---------------------------------------------------------------------------
+# Template engine
+# ---------------------------------------------------------------------------
+
+# Built-in templates — can be fully overridden by explanation_templates.yaml
+_BUILTIN_TEMPLATES: Dict[str, str] = {
+
+    "remove": textwrap.dedent("""\
+        MODERATION DECISION: REMOVE
+
+        Content summary: {content_summary}
+
+        After examining {n_claims} claim(s) across {n_sources} source(s):
+
+        {claim_assessments}
+
+        KEY EVIDENCE
+        {evidence_list}
+
+        REASONING
+        {reasoning_narrative}
+
+        CONCLUSION
+        The content was removed because {removal_reason}.
+        Confidence: {confidence_pct}%.  Sources consulted: {n_sources}.
+    """),
+
+    "flag": textwrap.dedent("""\
+        MODERATION DECISION: FLAG FOR REVIEW
+
+        Content summary: {content_summary}
+
+        After examining {n_claims} claim(s) across {n_sources} source(s):
+
+        {claim_assessments}
+
+        KEY EVIDENCE
+        {evidence_list}
+
+        REASONING
+        {reasoning_narrative}
+
+        CONCLUSION
+        The content was flagged because {flag_reason}.
+        Confidence: {confidence_pct}%.  Sources consulted: {n_sources}.
+    """),
+
+    "allow": textwrap.dedent("""\
+        MODERATION DECISION: ALLOW
+
+        Content summary: {content_summary}
+
+        After examining {n_claims} claim(s) across {n_sources} source(s):
+
+        {claim_assessments}
+
+        KEY EVIDENCE
+        {evidence_list}
+
+        REASONING
+        {reasoning_narrative}
+
+        CONCLUSION
+        The content was allowed because {allow_reason}.
+        Confidence: {confidence_pct}%.  Sources consulted: {n_sources}.
+    """),
+}
+
+
+class ExplanationTemplates:
+    """Loads templates from YAML; falls back to built-ins."""
+
+    def __init__(self, path: str = EXPLANATION_CONFIG_PATH) -> None:
+        self._templates = dict(_BUILTIN_TEMPLATES)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as fh:
+                loaded = yaml.safe_load(fh) or {}
+            self._templates.update(loaded.get("templates", {}))
+
+    def get(self, decision: str) -> str:
+        return self._templates.get(decision, self._templates["flag"])
+
+
+# ---------------------------------------------------------------------------
+# Explainability engine
+# ---------------------------------------------------------------------------
+
+class ExplainabilityEngine:
+    """
+    Converts a ReasoningObject into a structured, human-readable explanation.
+
+    No ML or API calls.  All text is derived deterministically from the
+    agent's actual evidence trace.
+    """
+
+    def __init__(self, templates: Optional[ExplanationTemplates] = None) -> None:
+        self._tpl = templates or ExplanationTemplates()
+
+    def generate_explanation(self, reasoning: ReasoningObject) -> str:
+        """Return a formatted explanation string."""
+        template    = self._tpl.get(reasoning.decision)
+        variables   = self._build_variables(reasoning)
+        try:
+            return template.format(**variables)
+        except KeyError as exc:
+            # Graceful fallback — missing template var
+            return self._fallback(reasoning) + f"\n[template key missing: {exc}]"
+
+    def generate_structured(self, reasoning: ReasoningObject) -> dict:
+        """Return a machine-readable structured explanation for API responses."""
+        return {
+            "decision":          reasoning.decision,
+            "confidence":        round(reasoning.confidence, 3),
+            "content_summary":   reasoning.content_summary,
+            "claims_assessed": [
+                {
+                    "id":     c.claim_id,
+                    "text":   c.claim_text,
+                    "status": c.verification_status,
+                    "conf":   round(c.confidence, 3),
+                }
+                for c in reasoning.claims
+            ],
+            "sources_used": [
+                {
+                    "id":          s.source_id,
+                    "title":       s.title,
+                    "stance":      s.stance,
+                    "reliability": round(s.reliability, 3),
+                }
+                for s in reasoning.sources_used
+            ],
+            "evidence_summary": {
+                "contradicting": len(reasoning.contradicting_sources),
+                "supporting":    len(reasoning.supporting_sources),
+                "high_reliability": len(reasoning.high_reliability_sources),
+            },
+            "narrative": self.generate_explanation(reasoning),
+            "steps_taken": reasoning.step_count,
+            "episode_id":  reasoning.episode_id,
+        }
+
+    # ------------------------------------------------------------------
+    # Template variable builder
+    # ------------------------------------------------------------------
+
+    def _build_variables(self, r: ReasoningObject) -> dict:
+        return {
+            "content_summary":    r.content_summary or "(no summary)",
+            "n_claims":           len(r.claims),
+            "n_sources":          len(r.sources_used),
+            "confidence_pct":     int(r.confidence * 100),
+            "claim_assessments":  self._format_claims(r.claims),
+            "evidence_list":      self._format_evidence(r.sources_used),
+            "reasoning_narrative":self._narrative(r),
+            "removal_reason":     self._removal_reason(r),
+            "flag_reason":        self._flag_reason(r),
+            "allow_reason":       self._allow_reason(r),
+        }
+
+    @staticmethod
+    def _format_claims(claims: List[ClaimAssessment]) -> str:
+        if not claims:
+            return "  (no claims assessed)"
+        lines = []
+        for c in claims:
+            status_icon = {
+                "true":           "[TRUE]",
+                "false":          "[FALSE]",
+                "partially_true": "[PARTIAL]",
+                "unknown":        "[UNKNOWN]",
+                "unverified":     "[NOT VERIFIED]",
+            }.get(c.verification_status, "[?]")
+            lines.append(
+                f"  {status_icon} Claim: {c.claim_text}\n"
+                f"           Status: {c.verification_status}  "
+                f"(confidence {int(c.confidence * 100)}%)"
+            )
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_evidence(sources: List[SourceEvidence]) -> str:
+        if not sources:
+            return "  (no sources checked)"
+        lines = []
+        for s in sorted(sources, key=lambda x: -x.reliability):
+            icon = {"contradicting": "✗", "supporting": "✓", "neutral": "·"}.get(
+                s.stance, "·"
+            )
+            rel_bar = "█" * int(s.reliability * 10) + "░" * (10 - int(s.reliability * 10))
+            snippet = (s.key_snippet[:100] + "…") if len(s.key_snippet) > 100 else s.key_snippet
+            lines.append(
+                f"  {icon} [{s.stance.upper():<14}] rel={rel_bar} ({s.reliability:.2f})\n"
+                f"    {s.title}\n"
+                + (f"    \"{snippet}\"" if snippet else "")
+            )
+        return "\n".join(lines)
+
+    def _narrative(self, r: ReasoningObject) -> str:
+        parts = []
+
+        n_false = len(r.false_claims)
+        n_total = len(r.claims)
+        parts.append(
+            f"{n_false} of {n_total} claim(s) were found to be false or partially false."
+        )
+
+        if r.contradicting_sources:
+            top = max(r.contradicting_sources, key=lambda s: s.reliability)
+            parts.append(
+                f"The strongest contradicting source was '{top.title}' "
+                f"(reliability {top.reliability:.2f}), which "
+                f"directly contradicts the claims made in the content."
+            )
+
+        if r.supporting_sources:
+            top = max(r.supporting_sources, key=lambda s: s.reliability)
+            parts.append(
+                f"One supporting source was found: '{top.title}' "
+                f"(reliability {top.reliability:.2f})."
+            )
+        else:
+            parts.append("No credible supporting sources were identified.")
+
+        if r.high_reliability_sources:
+            names = ", ".join(
+                f"'{s.title[:40]}'" for s in r.high_reliability_sources[:3]
+            )
+            parts.append(
+                f"High-reliability sources consulted: {names}."
+            )
+
+        parts.append(
+            f"The agent took {r.step_count} reasoning step(s) "
+            f"and verified {int(r.verified_fraction * 100)}% of claims before deciding."
+        )
+
+        return "  " + "\n  ".join(parts)
+
+    @staticmethod
+    def _removal_reason(r: ReasoningObject) -> str:
+        false_count = len(r.false_claims)
+        hi_rel      = len(r.high_reliability_sources)
+        if false_count:
+            claim_texts = "; ".join(
+                f"'{c.claim_text[:50]}'" for c in r.false_claims[:2]
+            )
+            return (
+                f"{false_count} claim(s) were definitively false according to "
+                f"{hi_rel} high-reliability source(s), including: {claim_texts}"
+            )
+        return "overwhelming contradicting evidence from authoritative sources was found"
+
+    @staticmethod
+    def _flag_reason(r: ReasoningObject) -> str:
+        n_contra  = len(r.contradicting_sources)
+        n_support = len(r.supporting_sources)
+        if n_contra > 0 and n_support > 0:
+            return (
+                f"evidence was mixed ({n_contra} contradicting, {n_support} supporting), "
+                "requiring human review to determine context and intent"
+            )
+        if n_contra > 0:
+            return (
+                f"{n_contra} contradicting source(s) were found but evidence is "
+                "insufficient for removal; human review is recommended"
+            )
+        return "the claim could not be fully verified with available sources"
+
+    @staticmethod
+    def _allow_reason(r: ReasoningObject) -> str:
+        n_support = len(r.supporting_sources)
+        hi_rel    = len(r.high_reliability_sources)
+        return (
+            f"{n_support} supporting source(s) (including {hi_rel} high-reliability) "
+            "corroborate the claims and no significant contradicting evidence was found"
+        )
+
+    @staticmethod
+    def _fallback(r: ReasoningObject) -> str:
+        return (
+            f"MODERATION DECISION: {r.decision.upper()}\n"
+            f"Content: {r.content_summary}\n"
+            f"Claims verified: {len(r.claims)}. Sources checked: {len(r.sources_used)}.\n"
+            f"Decision confidence: {int(r.confidence * 100)}%."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Factory helper used by inference.py and server.py
+# ---------------------------------------------------------------------------
+
+def build_reasoning_from_episode(
+    obs,              # Final Observation object
+    decision: str,
+    episode_id: str = "",
+    difficulty: str = "",
+) -> ReasoningObject:
+    """
+    Convenience builder: converts a final Observation into a ReasoningObject.
+    Compatible with any agent that used verify_claim + check_source + decide.
+    """
+    # Collect checked sources from interaction history
+    checked_source_ids = {
+        r.action_payload.get("source_id")
+        for r in obs.interaction_history
+        if r.action_type == "check_source"
+    }
+
+    sources_used = [
+        SourceEvidence(
+            source_id=s.id,
+            title=s.title,
+            stance=s.stance if isinstance(s.stance, str) else s.stance.value,
+            reliability=s.reliability,
+            key_snippet=s.text[:200],
+        )
+        for s in obs.available_sources
+        if s.id in checked_source_ids
+    ]
+
+    claims_assessed = [
+        ClaimAssessment(
+            claim_id=c.id,
+            claim_text=c.text,
+            verification_status=(
+                c.verification_status
+                if isinstance(c.verification_status, str)
+                else c.verification_status.value
+            ),
+            confidence=c.confidence,
+        )
+        for c in obs.claims
+    ]
+
+    # Confidence = mean reliability of checked sources (or 0.5 fallback)
+    confidence = (
+        sum(s.reliability for s in sources_used) / len(sources_used)
+        if sources_used else 0.5
+    )
+
+    return ReasoningObject(
+        content_summary=obs.content[:200],
+        claims=claims_assessed,
+        sources_used=sources_used,
+        decision=decision,
+        confidence=confidence,
+        step_count=obs.step_count,
+        episode_id=episode_id,
+        difficulty=difficulty,
+    )

inference.py

@@ -0,0 +1,713 @@
+"""
+inference.py
+============
+Baseline ReAct-style agent for InformationIntegrityEnv.
+
+Two run modes
+-------------
+benchmark   Run all difficulties over all scenarios (default).
+            Prints per-episode [START]/[STEP]/[END] lines, then a final
+            summary table and tier-separation check.
+
+single      Run one episode against a specific scenario or a live server.
+
+Environment variables
+---------------------
+  API_BASE_URL      URL of the LLM provider (OpenAI-compatible)
+  MODEL_NAME        Model to use (e.g. gpt-4o, claude-3-5-sonnet, etc.)
+  HF_TOKEN          Bearer token / API key for the provider
+  ENV_SERVER_URL    URL of the env server (default http://localhost:8000)
+  MAX_STEPS         Per-episode step limit (default 20)
+  BENCHMARK_SEED    Random seed for reproducible scenario sampling (default 42)
+
+Logging protocol (required by OpenEnv)
+---------------------------------------
+  [START]  — once at episode start
+  [STEP]   — at every step
+  [END]    — with final score
+
+Benchmark summary format (required)
+-------------------------------------
+  difficulty=easy   avg_score=X.XXXX  avg_reward=X.XXXX  n=N
+  difficulty=medium avg_score=X.XXXX  avg_reward=X.XXXX  n=N
+  difficulty=hard   avg_score=X.XXXX  avg_reward=X.XXXX  n=N
+
+Usage
+-----
+  # Full benchmark (local, all scenarios)
+  python inference.py --benchmark
+
+  # Single episode from dataset
+  python inference.py --local --difficulty medium --scenario-id 0
+
+  # Single episode from JSON file
+  python inference.py --local --scenario scenario.json
+
+  # Against running env server
+  python inference.py --server --difficulty easy --scenario-id 1
+
+  # Write benchmark results to JSON
+  python inference.py --benchmark --out results.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import random
+import sys
+import time
+from typing import Any, Dict, List, Optional
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # rely on shell environment
+
+import requests as http_requests
+from openai import OpenAI
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+)
+logger = logging.getLogger("inference")
+
+# ---------------------------------------------------------------------------
+# Config from environment
+# ---------------------------------------------------------------------------
+
+API_BASE_URL    = os.getenv("API_BASE_URL",    "https://router.huggingface.co/v1")
+MODEL_NAME      = os.getenv("MODEL_NAME",      "Qwen/Qwen2.5-72B-Instruct")
+HF_TOKEN        = os.getenv("HF_TOKEN")
+ENV_SERVER_URL  = os.getenv("ENV_SERVER_URL",  "http://localhost:8000")
+MAX_STEPS       = int(os.getenv("MAX_STEPS",   10))
+BENCHMARK_SEED  = int(os.getenv("BENCHMARK_SEED", 42))
+DIFFICULTY      = os.getenv("DIFFICULTY",      "easy")
+SCENARIO_ID     = os.getenv("SCENARIO_ID",     None)   # int index or string scenario id
+
+DIFFICULTIES    = ["easy", "medium", "hard"]
+
+
+# ---------------------------------------------------------------------------
+# LLM client
+# ---------------------------------------------------------------------------
+
+def _build_client() -> OpenAI:
+    if not HF_TOKEN:
+        raise ValueError(
+            "No API key found. Set HF_TOKEN environment variable."
+        )
+    return OpenAI(api_key=HF_TOKEN, base_url=API_BASE_URL)
+
+
+# ---------------------------------------------------------------------------
+# Environment interface — local (in-process)
+# ---------------------------------------------------------------------------
+
+class LocalEnvClient:
+    """Runs InformationIntegrityEnv in-process against the static dataset."""
+
+    def __init__(
+        self,
+        difficulty: str,
+        scenario_id: Optional[str | int] = None,
+        scenario_dict: Optional[dict] = None,
+    ) -> None:
+        from environment import InformationIntegrityEnv
+
+        if scenario_dict is not None:
+            self._env = InformationIntegrityEnv(scenario=scenario_dict)
+        else:
+            self._env = InformationIntegrityEnv.from_dataset(
+                difficulty=difficulty,
+                scenario_id=scenario_id,
+            )
+        self._done = False
+
+    def reset(self, difficulty: Optional[str] = None, scenario_id: Optional[str | int] = None) -> dict:
+        obs = self._env.reset(difficulty=difficulty, scenario_id=scenario_id)
+        self._done = False
+        return obs.model_dump()
+
+    def step(self, action: dict) -> dict:
+        from models import Action
+        act = Action(**action)
+        obs, rew, done, info = self._env.step(act)
+        self._done = done
+        return {
+            "observation": obs.model_dump(),
+            "reward":      rew.model_dump(),
+            "done":        done,
+            "info":        info,
+        }
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def episode_result(self) -> dict:
+        return self._env.episode_result().model_dump()
+
+
+# ---------------------------------------------------------------------------
+# Environment interface — remote server
+# ---------------------------------------------------------------------------
+
+class ServerEnvClient:
+    """Communicates with a running FastAPI env server."""
+
+    def __init__(self, base_url: str = ENV_SERVER_URL) -> None:
+        self._base = base_url.rstrip("/")
+        self._session_id: Optional[str] = None
+
+    def reset(
+        self,
+        difficulty: Optional[str] = None,
+        scenario_id: Optional[str | int] = None,
+        scenario_dict: Optional[dict] = None,
+    ) -> dict:
+        payload: dict = {"max_steps": MAX_STEPS}
+        if scenario_dict:
+            payload["scenario"] = scenario_dict
+        elif difficulty:
+            payload["difficulty"] = difficulty
+            if scenario_id is not None:
+                payload["scenario_id"] = scenario_id
+        r = http_requests.post(f"{self._base}/reset", json=payload, timeout=30)
+        r.raise_for_status()
+        data = r.json()
+        self._session_id = data["session_id"]
+        return data["observation"]
+
+    def step(self, action: dict) -> dict:
+        payload = {"session_id": self._session_id, "action": action}
+        r = http_requests.post(f"{self._base}/step", json=payload, timeout=30)
+        r.raise_for_status()
+        return r.json()
+
+    def episode_result(self) -> dict:
+        # Server does not expose a dedicated episode_result endpoint;
+        # grader_score is included in the final step's info dict.
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = SYSTEM_PROMPT = """You are a high-precision content moderation agent.
+
+Your goal is to make the MOST ACCURATE moderation decision based on evidence.
+
+You MUST follow a structured reasoning process:
+
+1. First verify claims.
+2. Then evaluate sources carefully:
+   - Prefer HIGH reliability sources
+   - Consider stance (support/refute/neutral)
+3. Avoid redundant actions.
+4. Only decide when evidence is sufficient.
+
+Decision guidelines:
+- REMOVE → if content is clearly false and harmful
+- FLAG   → if uncertain, conflicting evidence, or partially misleading
+- ALLOW  → if claims are well-supported by reliable sources
+
+Action rules:
+- You MUST verify at least one claim
+- You MUST check at least two sources
+- NEVER repeat the same action
+- Be efficient (avoid unnecessary steps)
+
+Output STRICT JSON ONLY:
+{"type": "...", ...}
+"""
+
+
+def _observation_prompt(obs_dict: dict) -> str:
+    content = obs_dict.get("content", "")
+    claims  = obs_dict.get("claims", [])
+    sources = obs_dict.get("available_sources", [])
+    history = obs_dict.get("interaction_history", [])
+    flags   = obs_dict.get("status_flags", {})
+    step    = obs_dict.get("step_count", 0)
+
+    # Track what has already been done from full history
+    checked_source_ids  = {
+        h["action_payload"].get("source_id")
+        for h in history
+        if h.get("action_type") == "check_source" and h.get("action_payload", {}).get("source_id")
+    }
+    verified_claim_ids  = {
+        h["action_payload"].get("claim_id")
+        for h in history
+        if h.get("action_type") == "verify_claim" and h.get("action_payload", {}).get("claim_id")
+    }
+
+    claims_text = "\n".join(
+        f"  [{c['id']}] {c['text']} — status: {c.get('verification_status','unverified')}"
+        + (" [ALREADY VERIFIED — do not repeat]" if c['id'] in verified_claim_ids else "")
+        for c in claims
+    )
+    sources_text = "\n".join(
+        f"  [{s['id']}] {s['title']} | stance={s['stance']} | reliability={s['reliability']:.2f}"
+        + (" [ALREADY CHECKED — do not repeat]" if s['id'] in checked_source_ids else "")
+        for s in sources
+    )
+
+    last_result = ""
+    if history:
+        last = history[-1]
+        last_result = f"\nLast step result: {json.dumps(last.get('result', {}), ensure_ascii=False)[:300]}"
+
+    unchecked_sources  = [s['id'] for s in sources  if s['id']  not in checked_source_ids]
+    unverified_claims  = [c['id'] for c in claims   if c['id']  not in verified_claim_ids]
+    sufficient         = flags.get('sufficient_evidence', False)
+
+    next_step_hint = ""
+    if not sufficient:
+        if unverified_claims:
+            next_step_hint = f"\nHINT: You still need to verify claims: {unverified_claims}. Use verify_claim next."
+        elif unchecked_sources:
+            next_step_hint = f"\nHINT: You still need to check sources: {unchecked_sources}. Use check_source next."
+    else:
+        next_step_hint = "\nHINT: You have sufficient evidence. Use the 'decide' action now (allow/flag/remove)."
+
+    return f"""STEP {step}
+
+CONTENT UNDER REVIEW:
+{content}
+
+CLAIMS:
+{claims_text}
+
+AVAILABLE SOURCES:
+{sources_text}
+
+STATUS FLAGS:
+  decision_made={flags.get('decision_made', False)}
+  sufficient_evidence={sufficient}
+  redundant_actions={flags.get('redundant_actions', 0)}
+{last_result}{next_step_hint}
+
+Choose your next action (JSON only):"""
+
+
+# ---------------------------------------------------------------------------
+# LLM action call
+# ---------------------------------------------------------------------------
+
+def _llm_action(llm: OpenAI, messages: list, step: int, retries: int = 3) -> dict:
+    """Call LLM and parse JSON action. Retries on parse failure."""
+    last_exc = None
+    for attempt in range(retries):
+        try:
+            resp = llm.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=0.0,
+                max_tokens=256,
+                timeout=30,
+            )
+            raw = resp.choices[0].message.content.strip()
+            if raw.startswith("```"):
+                raw = raw.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            logger.warning("Step %d attempt %d: JSON parse error — %s", step, attempt + 1, exc)
+            last_exc = exc
+        except Exception as exc:
+            logger.error("LLM call failed at step %d: %s", step, exc)
+            last_exc = exc
+            if attempt < retries - 1:
+                time.sleep(2 ** attempt)
+
+    # Raise so the episode fails loudly rather than silently looping
+    raise RuntimeError(f"LLM call failed after {retries} attempts at step {step}: {last_exc}")
+
+
+# ---------------------------------------------------------------------------
+# Explanation builder
+# ---------------------------------------------------------------------------
+
+def _build_explanation(obs_dict: dict, decision: Optional[str]) -> str:
+    try:
+        from explainability import ExplainabilityEngine, build_reasoning_from_episode
+        from models import Observation
+        obs = Observation(**obs_dict)
+        reasoning = build_reasoning_from_episode(obs=obs, decision=decision or "none")
+        return ExplainabilityEngine().generate_explanation(reasoning)
+    except Exception as exc:
+        return f"(explanation unavailable: {exc})"
+
+
+# ---------------------------------------------------------------------------
+# OpenEnv-compliant logging helpers
+# ---------------------------------------------------------------------------
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: str = "null") -> None:
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={str(done).lower()} error={error}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, rewards: List[float], score: float = 0.0) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} score={score:.4f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# OpenEnv single-episode runner (primary entry point)
+# ---------------------------------------------------------------------------
+
+def run_single_episode(llm: OpenAI) -> dict:
+    """
+    Run one episode controlled entirely by DIFFICULTY and SCENARIO_ID env vars.
+    Prints strict OpenEnv-format logs: [START], [STEP]×n, [END].
+    """
+    from tasks.registry import TASKS
+    from environment import InformationIntegrityEnv
+
+    # Resolve scenario_id: prefer int index, fall back to string id
+    sid: Optional[str | int] = SCENARIO_ID
+    if sid is not None:
+        try:
+            sid = int(sid)
+        except (ValueError, TypeError):
+            pass  # keep as string scenario id
+
+    task         = TASKS[DIFFICULTY]
+    scenario_dict = task.get_scenario(sid if sid is not None else 0)
+    task_name = scenario_dict.get('id', f'{DIFFICULTY}_unknown')
+
+    env = InformationIntegrityEnv(scenario=scenario_dict)
+    obs = env.reset(difficulty=DIFFICULTY, scenario_id=sid)
+
+    log_start(task=task_name, env="information-integrity-env", model=MODEL_NAME)
+
+    messages: List[Dict[str, str]] = [{"role": "system", "content": SYSTEM_PROMPT}]
+    rewards: List[float] = []
+    steps_taken = 0
+    score       = 0.0
+
+    for step in range(1, MAX_STEPS + 1):
+        obs_dict = obs.model_dump()
+        messages.append({"role": "user", "content": _observation_prompt(obs_dict)})
+
+        try:
+            action_dict = _llm_action(llm, messages, step)
+        except RuntimeError as exc:
+            logger.error("Aborting episode: %s", exc)
+            break
+        messages.append({"role": "assistant", "content": json.dumps(action_dict)})
+
+        error_str   = "null"
+        step_reward = 0.0
+        done        = False
+
+        try:
+            from models import Action
+            obs, reward_obj, done, info = env.step(Action(**action_dict))
+            step_reward = reward_obj.score
+        except Exception as exc:
+            error_str = str(exc)[:80].replace("\n", " ")
+
+        rewards.append(step_reward)
+        steps_taken = step
+
+        log_step(
+            step=step,
+            action=action_dict.get("type", "unknown"),
+            reward=step_reward,
+            done=done,
+            error=error_str,
+        )
+
+        if done:
+            try:
+                ep_result = env.episode_result()
+                score = float(ep_result.grader_score or 0.0)
+            except Exception:
+                score = 0.0
+            score = min(max(score, 0.005), 0.995)
+            break
+
+    # Compute grader score even if episode didn't complete (LLM failed / max steps)
+    if score == 0.0:
+        try:
+            ep_result = env.episode_result()
+            score = float(ep_result.grader_score or 0.0)
+        except Exception:
+            score = 0.0
+    score = min(max(score, 0.005), 0.995)  # strictly in (0, 1) as required by validator
+
+    success = score >= 0.5
+    log_end(success=success, steps=steps_taken, rewards=rewards, score=score)
+
+    return {"score": score, "steps": steps_taken, "success": success}
+
+
+# ---------------------------------------------------------------------------
+# Single episode runner (legacy — used by benchmark loop and CLI)
+# ---------------------------------------------------------------------------
+
+def run_episode(
+    env: LocalEnvClient | ServerEnvClient,
+    llm: OpenAI,
+    difficulty: Optional[str] = None,
+    scenario_id: Optional[str | int] = None,
+) -> dict:
+    """Run one full episode using compliant log_start/log_step/log_end."""
+    messages: List[Dict[str, str]] = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    obs_dict = env.reset(difficulty=difficulty, scenario_id=scenario_id)
+
+    task_name = f"{difficulty}_{scenario_id}" if difficulty and scenario_id is not None \
+        else obs_dict.get("task_difficulty", "unknown")
+    log_start(task=task_name, env="information-integrity-env", model=MODEL_NAME)
+
+    rewards: List[float] = []
+    step        = 0
+    grader_score: Optional[float] = None
+
+    for step in range(1, MAX_STEPS + 1):
+        messages.append({"role": "user", "content": _observation_prompt(obs_dict)})
+
+        try:
+            action_dict = _llm_action(llm, messages, step)
+        except RuntimeError as exc:
+            break
+        messages.append({"role": "assistant", "content": json.dumps(action_dict)})
+
+        error_str   = "null"
+        step_reward = 0.0
+        done        = False
+
+        try:
+            result      = env.step(action_dict)
+            obs_dict    = result["observation"]
+            step_reward = result["reward"].get("score", 0.0)
+            done        = result["done"]
+        except Exception as exc:
+            error_str = str(exc)[:80].replace("\n", " ")
+
+        rewards.append(step_reward)
+        log_step(step=step, action=action_dict.get("type", "unknown"),
+                 reward=step_reward, done=done, error=error_str)
+
+        if done:
+            break
+
+    if isinstance(env, LocalEnvClient):
+        try:
+            grader_score = env.episode_result().get("grader_score")
+        except Exception:
+            pass
+
+    score   = max(float(grader_score or 0.005), 0.005)  # strictly > 0 as required by validator
+    success = score >= 0.5
+    log_end(success=success, steps=step, rewards=rewards, score=score)
+
+    return {
+        "difficulty":    difficulty,
+        "scenario_id":   scenario_id,
+        "steps":         step,
+        "grader_score":  score,      # always a float >= 0.005
+        "total_reward": sum(rewards),
+    }
+
+
+
+# ---------------------------------------------------------------------------
+# Benchmark loop
+# ---------------------------------------------------------------------------
+
+def run_benchmark(llm: OpenAI, out_path: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Loop over all difficulties × all scenarios in each dataset.
+    Prints per-episode logs, then the required summary table.
+
+    Returns
+    -------
+    dict with per-difficulty aggregates and all raw episode results.
+    """
+    from tasks.registry import TASKS
+
+    all_results: Dict[str, List[dict]] = {d: [] for d in DIFFICULTIES}
+    rng = random.Random(BENCHMARK_SEED)
+
+    for difficulty in DIFFICULTIES:
+        task       = TASKS[difficulty]
+        scenarios  = task.get_all_scenarios()
+        n          = len(scenarios)
+        logger.info("=== Benchmarking difficulty=%s  (%d scenarios) ===", difficulty, n)
+
+        for idx, sc_dict in enumerate(scenarios):
+            # Build a fresh local env for each scenario
+            env = LocalEnvClient(
+                difficulty=difficulty,
+                scenario_id=idx,
+            )
+            result = run_episode(
+                env=env,
+                llm=llm,
+                difficulty=difficulty,
+                scenario_id=idx,
+            )
+            result["scenario_index"] = idx
+            result["scenario_id"]    = sc_dict.get("id", str(idx))
+            all_results[difficulty].append(result)
+
+    # ---- Summary ----
+    summary: Dict[str, dict] = {}
+    print()  # blank line before summary
+    for difficulty in DIFFICULTIES:
+        episodes = all_results[difficulty]
+        n = len(episodes)
+
+        scores  = [e["grader_score"] for e in episodes]  # always float >= 0.005
+        rewards = [e["total_reward"]  for e in episodes]
+
+        avg_score  = sum(scores) / len(scores) if scores else 0.005
+        avg_reward = sum(rewards) / len(rewards) if rewards else 0.0
+
+        summary[difficulty] = {
+            "avg_score":  round(avg_score,  4),
+            "avg_reward": round(avg_reward, 4),
+            "n":          n,
+        }
+        print(
+            f"difficulty={difficulty:<6} "
+            f"avg_score={avg_score:.4f}  "
+            f"avg_reward={avg_reward:.4f}  "
+            f"n={n}"
+        )
+
+    # ---- Difficulty tier separation check ----
+    easy_s   = summary["easy"]["avg_score"]
+    medium_s = summary["medium"]["avg_score"]
+    hard_s   = summary["hard"]["avg_score"]
+
+    if easy_s > medium_s > hard_s:
+        print("Difficulty tiers well separated: easy > medium > hard ✓")
+    else:
+        print(
+            "WARNING: Difficulty tiers not well separated "
+            f"(easy={easy_s:.4f}, medium={medium_s:.4f}, hard={hard_s:.4f})"
+        )
+
+    benchmark_output = {
+        "summary":  summary,
+        "episodes": all_results,
+    }
+
+    if out_path:
+        with open(out_path, "w", encoding="utf-8") as fh:
+            json.dump(benchmark_output, fh, indent=2, ensure_ascii=False)
+        logger.info("Benchmark results written to %s", out_path)
+
+    return benchmark_output
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="InformationIntegrity benchmark agent",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--benchmark", action="store_true",
+        help="Run full benchmark over all difficulties and all scenarios (default mode)",
+    )
+    mode.add_argument(
+        "--local", action="store_true",
+        help="Run a single episode in-process (requires --difficulty or --scenario)",
+    )
+    mode.add_argument(
+        "--server", action="store_true",
+        help="Run a single episode against a running env server",
+    )
+
+    parser.add_argument("--difficulty", default="medium",
+                        choices=DIFFICULTIES,
+                        help="Difficulty tier (used with --local or --server)")
+    parser.add_argument("--scenario-id", default=None,
+                        help="Scenario index (int) or id (str); None = random")
+    parser.add_argument("--scenario", default=None,
+                        help="Path to a pre-collected scenario JSON file (overrides --difficulty)")
+    parser.add_argument("--out", default=None,
+                        help="Write episode/benchmark result JSON to this path")
+
+    return parser.parse_args()
+
+
+def main() -> None:
+    args   = _parse_args()
+    llm    = _build_client()
+
+    # ---------- Default: OpenEnv single-episode mode (env-var driven) ----------
+    if not args.benchmark and not args.local and not args.server:
+        run_single_episode(llm)
+        return
+
+    # ---------- Benchmark ----------
+    if args.benchmark:
+        run_benchmark(llm, out_path=args.out)
+        return
+
+    # ---------- Single episode ----------
+    scenario_id: Optional[str | int] = args.scenario_id
+    if scenario_id is not None:
+        try:
+            scenario_id = int(scenario_id)
+        except (ValueError, TypeError):
+            pass  # keep as string id
+
+    # Load scenario from file if specified
+    scenario_dict: Optional[dict] = None
+    if args.scenario:
+        with open(args.scenario, "r", encoding="utf-8") as fh:
+            scenario_dict = json.load(fh)
+
+    if args.local:
+        env = LocalEnvClient(
+            difficulty=args.difficulty,
+            scenario_id=scenario_id,
+            scenario_dict=scenario_dict,
+        )
+    else:
+        env = ServerEnvClient(base_url=ENV_SERVER_URL)
+
+    result = run_episode(
+        env=env,
+        llm=llm,
+        difficulty=args.difficulty,
+        scenario_id=scenario_id,
+    )
+
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            json.dump(result, fh, indent=2, ensure_ascii=False)
+        logger.info("Episode result written to %s", args.out)
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,277 @@
+"""
+Pydantic models for the InformationIntegrity OpenEnv environment.
+All models are strict and versioned for deterministic serialisation.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+# ---------------------------------------------------------------------------
+# Enumerations
+# ---------------------------------------------------------------------------
+
+class Stance(str, Enum):
+    SUPPORTING = "supporting"
+    CONTRADICTING = "contradicting"
+    NEUTRAL = "neutral"
+
+
+class VerificationStatus(str, Enum):
+    UNVERIFIED = "unverified"
+    TRUE = "true"
+    FALSE = "false"
+    PARTIALLY_TRUE = "partially_true"
+    UNKNOWN = "unknown"
+
+
+class DecisionType(str, Enum):
+    ALLOW = "allow"
+    FLAG = "flag"
+    REMOVE = "remove"
+
+
+class ActionType(str, Enum):
+    VERIFY_CLAIM = "verify_claim"
+    CHECK_SOURCE = "check_source"
+    DECIDE = "decide"
+
+
+class TaskDifficulty(str, Enum):
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+
+
+# ---------------------------------------------------------------------------
+# Core domain models
+# ---------------------------------------------------------------------------
+
+class SourceInfo(BaseModel):
+    """A single evidence source presented to the agent."""
+
+    id: str = Field(..., description="Unique source identifier, e.g. 'src_001'")
+    title: str = Field(..., description="Headline or document title")
+    text: str = Field(..., description="Excerpt or full text snippet")
+    url: str = Field(..., description="Canonical URL of the source")
+    stance: Stance = Field(..., description="Relationship of source to the primary claim")
+    reliability: float = Field(..., ge=0.0, le=1.0,
+                               description="0=unreliable, 1=highly authoritative")
+    source_type: str = Field(default="unknown",
+                             description="official | news | blog | social | academic")
+
+    class Config:
+        use_enum_values = True
+
+
+class Claim(BaseModel):
+    """A single verifiable claim extracted from the content."""
+
+    id: str = Field(..., description="Unique claim identifier, e.g. 'claim_001'")
+    text: str = Field(..., description="Verbatim claim text")
+    verification_status: VerificationStatus = Field(
+        default=VerificationStatus.UNVERIFIED,
+        description="Agent-updated verification result"
+    )
+    confidence: float = Field(
+        default=0.0, ge=0.0, le=1.0,
+        description="Agent confidence in the verification (0–1)"
+    )
+    verified_by_sources: List[str] = Field(
+        default_factory=list,
+        description="List of source IDs used to verify this claim"
+    )
+
+    class Config:
+        use_enum_values = True
+
+
+class StatusFlags(BaseModel):
+    """Bookkeeping flags that track episode-level constraints."""
+
+    decision_made: bool = False
+    sufficient_evidence: bool = False
+    premature_decision: bool = False
+    redundant_actions: int = Field(default=0, ge=0)
+    max_steps_reached: bool = False
+
+
+class InteractionRecord(BaseModel):
+    """One entry in the interaction history."""
+
+    step: int
+    action_type: str
+    action_payload: Dict[str, Any]
+    result: Dict[str, Any]
+    reward_delta: float = 0.0
+
+
+class Observation(BaseModel):
+    """Full observable state returned to the agent after each step."""
+
+    content: str = Field(..., description="The piece of content under review")
+    claims: List[Claim] = Field(..., description="Extracted claims (may be partially verified)")
+    available_sources: List[SourceInfo] = Field(..., description="Evidence pool for this scenario")
+    interaction_history: List[InteractionRecord] = Field(default_factory=list)
+    status_flags: StatusFlags = Field(default_factory=StatusFlags)
+    step_count: int = Field(default=0, ge=0)
+    episode_id: str = Field(default="", description="Unique identifier for this episode")
+    task_difficulty: str = Field(default="easy")
+
+    class Config:
+        use_enum_values = True
+
+
+# ---------------------------------------------------------------------------
+# Action model
+# ---------------------------------------------------------------------------
+
+class Action(BaseModel):
+    """Agent action submitted to the environment."""
+
+    type: ActionType = Field(..., description="Which action to perform")
+    claim_id: Optional[str] = Field(
+        default=None,
+        description="Required when type=verify_claim"
+    )
+    source_id: Optional[str] = Field(
+        default=None,
+        description="Required when type=check_source"
+    )
+    decision: Optional[DecisionType] = Field(
+        default=None,
+        description="Required when type=decide"
+    )
+    reasoning: Optional[str] = Field(
+        default=None,
+        description="Agent's free-text reasoning (logged, not evaluated directly)"
+    )
+
+    @model_validator(mode="after")
+    def validate_action_payload(self) -> "Action":
+        if self.type == ActionType.VERIFY_CLAIM and not self.claim_id:
+            raise ValueError("claim_id is required for verify_claim actions")
+        if self.type == ActionType.CHECK_SOURCE and not self.source_id:
+            raise ValueError("source_id is required for check_source actions")
+        if self.type == ActionType.DECIDE and not self.decision:
+            raise ValueError("decision is required for decide actions")
+        return self
+
+    class Config:
+        use_enum_values = True
+
+
+# ---------------------------------------------------------------------------
+# Reward models
+# ---------------------------------------------------------------------------
+
+class RewardBreakdown(BaseModel):
+    """Itemised reward components for transparency."""
+
+    verify_claim_reward: float = 0.0
+    check_source_reward: float = 0.0
+    multi_source_bonus: float = 0.0
+    decision_reward: float = 0.0
+    premature_penalty: float = 0.0
+    redundant_penalty: float = 0.0
+    inefficiency_penalty: float = 0.0
+    aggression_penalty: float = 0.0
+
+    @property
+    def total(self) -> float:
+        return (
+            self.verify_claim_reward
+            + self.check_source_reward
+            + self.multi_source_bonus
+            + self.decision_reward
+            + self.premature_penalty
+            + self.redundant_penalty
+            + self.inefficiency_penalty
+            + self.aggression_penalty
+        )
+
+
+class Reward(BaseModel):
+    """Reward signal returned after each step."""
+
+    score: float = Field(..., description="Clipped total reward for this step")
+    breakdown: RewardBreakdown
+    message: str = Field(default="", description="Human-readable reward explanation")
+    is_terminal: bool = Field(default=False)
+
+    class Config:
+        use_enum_values = True
+
+
+# ---------------------------------------------------------------------------
+# Episode result (returned at episode end)
+# ---------------------------------------------------------------------------
+
+class EpisodeResult(BaseModel):
+    """Accumulated statistics at the end of an episode."""
+
+    episode_id: str
+    task_difficulty: str
+    scenario_index: int
+    total_reward: float
+    decision: Optional[str] = None
+    ground_truth: str
+    correct: bool
+    steps_taken: int
+    claims_verified: int
+    sources_checked: int
+    grader_score: float = Field(ge=0.0, le=1.0)
+    reward_breakdown: RewardBreakdown
+    explanation: Optional[str] = None
+
+    class Config:
+        use_enum_values = True
+
+
+# ---------------------------------------------------------------------------
+# Scenario (loaded from dataset JSON)
+# ---------------------------------------------------------------------------
+
+class ScenarioSource(BaseModel):
+    """Source as stored in the dataset file."""
+
+    id: str
+    title: str
+    text: str
+    url: str
+    stance: str
+    reliability: float = Field(ge=0.0, le=1.0)
+    source_type: str = "unknown"
+    # Hidden from agent — used only by environment internals
+    verification_weight: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
+class ScenarioClaim(BaseModel):
+    """Claim as stored in the dataset file."""
+
+    id: str
+    text: str
+    # Hidden ground truth for the verifier
+    ground_truth_status: str
+    ground_truth_confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
+class Scenario(BaseModel):
+    """A complete evaluation scenario loaded from a dataset file."""
+
+    id: str
+    difficulty: str
+    content: str
+    claims: List[ScenarioClaim]
+    sources: List[ScenarioSource]
+    ground_truth: str = Field(..., description="allow | flag | remove")
+    topic: str = ""
+    tags: List[str] = Field(default_factory=list)
+    explanation_hint: str = Field(
+        default="",
+        description="Template hint for explanation generation"
+    )

openenv.yaml

@@ -0,0 +1,270 @@
+# ============================================================================
+# openenv.yaml  v1.1.0
+# OpenEnv environment specification — passes `openenv validate`
+# ============================================================================
+
+name: information-integrity-env
+version: "1.1.0"
+author: openenv-content-moderation
+description: >
+  A deterministic, benchmarkable content moderation environment where agents
+  verify claims, reason over pre-built evidence sources, and make explainable
+  moderation decisions (allow / flag / remove).
+
+  Evaluation runs fully offline — no external API calls during episodes.
+  Three difficulty tiers (easy / medium / hard) with static scenario datasets
+  ensure reproducible, comparable benchmarks across agent runs.
+
+license: Apache-2.0
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+server:
+  type: http
+  reset_endpoint:    POST /reset
+  step_endpoint:     POST /step
+  health_endpoint:   GET  /health
+  tasks_endpoint:    GET  /tasks
+  grade_endpoint:    POST /grade
+  collect_endpoint:  POST /collect   # dataset creation only; not used during eval
+  state_endpoint:    GET  /state/{session_id}
+
+# ---------------------------------------------------------------------------
+# Observation space
+# ---------------------------------------------------------------------------
+observation:
+  type: object
+  description: >
+    The agent observes the content under review, extracted claims (with live
+    verification status), a pre-built evidence pool, and a running interaction
+    history. Ground truth is never exposed.
+  properties:
+    content:
+      type: string
+      description: The piece of content under moderation review.
+    claims:
+      type: array
+      description: Verifiable claims extracted from the content.
+      items:
+        type: object
+        properties:
+          id:                  { type: string }
+          text:                { type: string }
+          verification_status: { type: string, enum: [unverified, true, false, partially_true, unknown] }
+          confidence:          { type: number, minimum: 0.0, maximum: 1.0 }
+          verified_by_sources: { type: array, items: { type: string } }
+    available_sources:
+      type: array
+      description: Pre-built evidence pool — fully deterministic, no live fetching.
+      items:
+        type: object
+        properties:
+          id:          { type: string }
+          title:       { type: string }
+          text:        { type: string }
+          url:         { type: string }
+          stance:      { type: string, enum: [supporting, contradicting, neutral] }
+          reliability: { type: number, minimum: 0.0, maximum: 1.0 }
+          source_type: { type: string }
+    interaction_history:
+      type: array
+      description: Log of all previous actions and their results this episode.
+    status_flags:
+      type: object
+      properties:
+        decision_made:       { type: boolean }
+        sufficient_evidence: { type: boolean }
+        premature_decision:  { type: boolean }
+        redundant_actions:   { type: integer }
+        max_steps_reached:   { type: boolean }
+    step_count:       { type: integer }
+    episode_id:       { type: string }
+    task_difficulty:  { type: string, enum: [easy, medium, hard] }
+
+# ---------------------------------------------------------------------------
+# Action space
+# ---------------------------------------------------------------------------
+actions:
+  verify_claim:
+    description: Investigate a specific claim and receive its verification status.
+    required_fields: [claim_id]
+    optional_fields: [reasoning]
+    example:
+      type: verify_claim
+      claim_id: claim_001
+      reasoning: "This is the central assertion — verify first."
+
+  check_source:
+    description: Read a source and receive its full text, stance, and reliability.
+    required_fields: [source_id]
+    optional_fields: [reasoning]
+    example:
+      type: check_source
+      source_id: src_003
+      reasoning: "WHO source — likely authoritative."
+
+  decide:
+    description: >
+      Make the final moderation decision, ending the episode.
+      Must verify >= 1 claim and check >= 2 sources first (or incur premature penalty).
+    required_fields: [decision]
+    optional_fields: [reasoning]
+    example:
+      type: decide
+      decision: remove
+      reasoning: "All claims false per three high-reliability sources."
+
+# ---------------------------------------------------------------------------
+# Reward
+# ---------------------------------------------------------------------------
+reward:
+  type: float
+  range: [-2.0, 2.0]
+  description: >
+    Dense step-level reward. Non-sparse by design — agents receive positive
+    signals for every unique claim verified and source checked.
+    See reward_config.yaml for configurable magnitudes.
+  components:
+    verify_claim_reward:  "+0.20 per unique claim verified"
+    check_source_reward:  "+0.20 per unique source checked"
+    multi_source_bonus:   "+0.20 when >= 3 unique sources checked"
+    decision_correct:     "+1.00 exact match with ground truth"
+    decision_partial:     "+0.50 one step away (flag<->remove, flag<->allow)"
+    decision_wrong:       "0.00"
+    premature_decision:   "-0.50 deciding before sufficient evidence"
+    redundant_action:     "-0.10 re-verifying / re-checking same id"
+    step_inefficiency:    "-0.05 per step beyond efficient threshold"
+    over_aggression:      "-0.30 choosing remove when ground truth is allow/flag"
+
+# ---------------------------------------------------------------------------
+# Tasks  (deterministic datasets — no live API calls)
+# ---------------------------------------------------------------------------
+tasks:
+  - id: easy
+    difficulty: easy
+    description: >
+      Clear-cut claims with overwhelming contradicting evidence from authoritative
+      sources (WHO, CDC, NASA, official government).  Decision should be
+      straightforward for a competent agent.
+    dataset: tasks/easy/scenarios.json
+    n_scenarios: 5
+    grader:
+      enabled: true
+      class: tasks.graders.EasyGrader
+      method: grade
+      score_range: [0.0, 1.0]
+    weights: { decision: 0.50, evidence: 0.25, reasoning: 0.15, efficiency: 0.10 }
+    ideal_max_steps: 8
+    ground_truth_distribution: { allow: 1, flag: 1, remove: 3 }
+
+  - id: medium
+    difficulty: medium
+    description: >
+      Partially true or misleading content. Mixed evidence with some supporting
+      and some contradicting sources.  Requires careful claim-by-claim verification
+      and evidence weighing.
+    dataset: tasks/medium/scenarios.json
+    n_scenarios: 5
+    grader:
+      enabled: true
+      class: tasks.graders.MediumGrader
+      method: grade
+      score_range: [0.0, 1.0]
+    weights: { decision: 0.35, evidence: 0.35, reasoning: 0.20, efficiency: 0.10 }
+    ideal_max_steps: 12
+    ground_truth_distribution: { allow: 1, flag: 4, remove: 0 }
+
+  - id: hard
+    difficulty: hard
+    description: >
+      Conflicting evidence from credible sources; genuinely contested ground truth.
+      Requires nuanced multi-claim reasoning, evidence reliability weighting, and
+      tolerance for ambiguity.  All four scoring dimensions count equally.
+    dataset: tasks/hard/scenarios.json
+    n_scenarios: 5
+    grader:
+      enabled: true
+      class: tasks.graders.HardGrader
+      method: grade
+      score_range: [0.0, 1.0]
+    weights: { decision: 0.30, evidence: 0.30, reasoning: 0.30, efficiency: 0.10 }
+    ideal_max_steps: 18
+    ground_truth_distribution: { allow: 0, flag: 5, remove: 0 }
+
+# ---------------------------------------------------------------------------
+# Grader
+# ---------------------------------------------------------------------------
+grader:
+  output_range: [0.0, 1.0]
+  dimensions:
+    decision_score:
+      description: Correctness of the final moderation call (partial credit for adjacent decisions)
+    evidence_score:
+      description: Fraction of available sources consulted
+    reasoning_score:
+      description: Fraction of claims fully verified before deciding
+    efficiency_score:
+      description: Steps used relative to difficulty-specific ideal maximum
+
+# ---------------------------------------------------------------------------
+# Evaluation protocol
+# ---------------------------------------------------------------------------
+evaluation:
+  description: >
+    Run inference.py in benchmark mode to evaluate an agent across all 15 scenarios.
+    No external API calls are made during evaluation episodes.
+  command: python inference.py --benchmark --out results.json
+  expected_output_format: |
+    difficulty=easy   avg_score=X.XXXX  avg_reward=X.XXXX  n=5
+    difficulty=medium avg_score=X.XXXX  avg_reward=X.XXXX  n=5
+    difficulty=hard   avg_score=X.XXXX  avg_reward=X.XXXX  n=5
+  tier_validation: easy_avg > medium_avg > hard_avg
+  runtime_budget: "< 20 minutes on 2 vCPU / 8 GB RAM"
+  logging_protocol: "[START] / [STEP] / [END]"
+
+# ---------------------------------------------------------------------------
+# Data pipeline  (dataset creation only — not used during eval)
+# ---------------------------------------------------------------------------
+data_pipeline:
+  description: >
+    DataCollector is used ONLY to build the static scenario datasets in
+    tasks/{difficulty}/scenarios.json.  It is NOT called during evaluation episodes.
+  backends:
+    - { name: serpapi,          env_key: SERPAPI_KEY }
+    - { name: newsapi,          env_key: NEWSAPI_KEY }
+    - { name: brave_search,     env_key: BRAVE_SEARCH_KEY }
+    - { name: google_factcheck, env_key: GOOGLE_FACTCHECK_KEY }
+    - { name: duckduckgo,       env_key: null, note: "No key required; rate-limited fallback" }
+  cache:
+    backend: redis
+    env_key: REDIS_URL
+    default: redis://localhost:6379
+    ttl_seconds: 86400
+
+# ---------------------------------------------------------------------------
+# Constraints
+# ---------------------------------------------------------------------------
+constraints:
+  - Ground truth is never exposed in the Observation
+  - No external API calls occur during env.step() or env.reset()
+  - All reward computations are deterministic
+  - Agents must gather evidence before deciding (premature decision penalty applies)
+  - Redundant actions (re-checking same id) are penalised
+  - Scenario datasets are static JSON — reproducible across runs
+
+# ---------------------------------------------------------------------------
+# Baseline
+# ---------------------------------------------------------------------------
+baseline:
+  script: inference.py
+  mode: --benchmark
+  agent_type: ReAct (LLM-driven)
+  logging_protocol: "[START] / [STEP] / [END]"
+  model_env_var: MODEL_NAME
+  api_base_env_var: API_BASE_URL
+  token_env_var: HF_TOKEN
+  expected_scores:
+    easy:   { avg_score: "~0.78", avg_reward: "~1.20" }
+    medium: { avg_score: "~0.63", avg_reward: "~0.90" }
+    hard:   { avg_score: "~0.52", avg_reward: "~0.65" }

pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "information-integrity-env"
+version = "1.1.0"
+description = "OpenEnv-compatible deterministic benchmark for reasoning-based content moderation"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.10.0",
+    "requests>=2.32.0",
+    "duckduckgo-search>=6.3.0",
+    "redis>=5.2.0",
+    "pyyaml>=6.0.0",
+    "python-dotenv>=1.0.0",
+    "openai>=1.0.0",
+    "scikit-learn>=1.4.0",
+    "numpy>=1.26.0",
+    "gradio>=4.44.0",
+    "openenv-core>=0.2.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[project.urls]
+Homepage = "https://huggingface.co/spaces/Ruhis/InfoClassifier"

quality_weighted_aggregator.py

@@ -0,0 +1,433 @@
+"""
+quality_weighted_aggregator.py
+==============================
+Advanced aggregation system that combines multiple stance signals with
+quality weighting, confidence calibration, and uncertainty handling.
+
+This module provides sophisticated methods for combining stance classifications
+from multiple sources, taking into account source reliability, confidence scores,
+and contextual factors to produce more accurate final decisions.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Dict, List, Tuple, Optional, Any
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger("quality_weighted_aggregator")
+
+@dataclass
+class StanceEvidence:
+    """Represents a single piece of stance evidence with metadata."""
+    stance: str  # "supporting", "contradicting", "neutral"
+    confidence: float  # 0.0 to 1.0
+    source_reliability: float  # 0.0 to 1.0
+    source_type: str  # "official", "news", "academic", etc.
+    method: str  # "semantic", "keyword", "nli", etc.
+    text_length: int  # Length of analyzed text
+    claim_relevance: float = 1.0  # How relevant the source is to the claim
+    temporal_weight: float = 1.0  # Recency weight if applicable
+
+class AggregationStrategy(Enum):
+    """Different strategies for aggregating stance evidence."""
+    WEIGHTED_MAJORITY = "weighted_majority"
+    CONFIDENCE_THRESHOLD = "confidence_threshold"
+    RELIABILITY_WEIGHTED = "reliability_weighted"
+    BAYESIAN_UPDATE = "bayesian_update"
+    ENSEMBLE = "ensemble"
+
+class QualityWeightedAggregator:
+    """
+    Advanced aggregation system for combining multiple stance classifications
+    with quality weighting and uncertainty handling.
+    """
+    
+    def __init__(self, strategy: AggregationStrategy = AggregationStrategy.ENSEMBLE):
+        self.strategy = strategy
+        
+        # Source type weights (can be configured)
+        self.source_type_weights = {
+            "official": 1.2,
+            "academic": 1.1,
+            "news": 1.0,
+            "fact_check": 1.3,
+            "social": 0.7,
+            "blog": 0.6,
+            "unknown": 0.8,
+        }
+        
+        # Method confidence multipliers
+        self.method_weights = {
+            "semantic": 1.1,
+            "nli": 1.0,
+            "keyword": 0.8,
+            "fallback": 0.6,
+            "default": 0.3,
+        }
+        
+        # Minimum evidence thresholds
+        self.min_evidence_count = 2
+        self.min_total_weight = 1.0
+        self.uncertainty_threshold = 0.3
+    
+    def aggregate_stance_evidence(
+        self, 
+        evidence_list: List[StanceEvidence],
+        claim_text: str = "",
+        context: Optional[Dict[str, Any]] = None
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """
+        Aggregate multiple stance evidence pieces into a final decision.
+        
+        Args:
+            evidence_list: List of StanceEvidence objects
+            claim_text: The original claim text for context
+            context: Additional context information
+        
+        Returns:
+            (final_stance, confidence, metadata)
+        """
+        if not evidence_list:
+            return "neutral", 0.1, {"reason": "no_evidence"}
+        
+        # Apply the selected aggregation strategy
+        if self.strategy == AggregationStrategy.WEIGHTED_MAJORITY:
+            return self._weighted_majority_aggregation(evidence_list)
+        elif self.strategy == AggregationStrategy.CONFIDENCE_THRESHOLD:
+            return self._confidence_threshold_aggregation(evidence_list)
+        elif self.strategy == AggregationStrategy.RELIABILITY_WEIGHTED:
+            return self._reliability_weighted_aggregation(evidence_list)
+        elif self.strategy == AggregationStrategy.BAYESIAN_UPDATE:
+            return self._bayesian_update_aggregation(evidence_list)
+        else:  # ENSEMBLE
+            return self._ensemble_aggregation(evidence_list, claim_text, context)
+    
+    def _weighted_majority_aggregation(
+        self, 
+        evidence_list: List[StanceEvidence]
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """Simple weighted majority voting."""
+        stance_weights = {"supporting": 0.0, "contradicting": 0.0, "neutral": 0.0}
+        total_weight = 0.0
+        
+        for evidence in evidence_list:
+            weight = self._calculate_evidence_weight(evidence)
+            stance_weights[evidence.stance] += weight
+            total_weight += weight
+        
+        if total_weight == 0:
+            return "neutral", 0.1, {"reason": "zero_weight"}
+        
+        # Normalize weights
+        for stance in stance_weights:
+            stance_weights[stance] /= total_weight
+        
+        best_stance = max(stance_weights, key=stance_weights.get)
+        confidence = stance_weights[best_stance]
+        
+        return best_stance, confidence, {
+            "method": "weighted_majority",
+            "stance_weights": stance_weights,
+            "total_weight": total_weight
+        }
+    
+    def _confidence_threshold_aggregation(
+        self, 
+        evidence_list: List[StanceEvidence]
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """Aggregation based on confidence thresholds."""
+        high_confidence_evidence = [
+            e for e in evidence_list 
+            if e.confidence >= 0.7 and e.source_reliability >= 0.6
+        ]
+        
+        if high_confidence_evidence:
+            return self._weighted_majority_aggregation(high_confidence_evidence)
+        
+        # Fall back to all evidence if no high-confidence evidence
+        medium_confidence_evidence = [
+            e for e in evidence_list 
+            if e.confidence >= 0.4
+        ]
+        
+        if medium_confidence_evidence:
+            result = self._weighted_majority_aggregation(medium_confidence_evidence)
+            # Reduce confidence for medium-confidence aggregation
+            return result[0], result[1] * 0.8, {**result[2], "fallback": "medium_confidence"}
+        
+        return "neutral", 0.2, {"reason": "low_confidence_evidence"}
+    
+    def _reliability_weighted_aggregation(
+        self, 
+        evidence_list: List[StanceEvidence]
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """Aggregation heavily weighted by source reliability."""
+        stance_scores = {"supporting": 0.0, "contradicting": 0.0, "neutral": 0.0}
+        total_reliability = 0.0
+        
+        for evidence in evidence_list:
+            # Weight primarily by reliability, with confidence as secondary factor
+            weight = evidence.source_reliability * (0.5 + 0.5 * evidence.confidence)
+            weight *= self.source_type_weights.get(evidence.source_type, 1.0)
+            
+            stance_scores[evidence.stance] += weight
+            total_reliability += evidence.source_reliability
+        
+        if total_reliability == 0:
+            return "neutral", 0.1, {"reason": "no_reliable_sources"}
+        
+        best_stance = max(stance_scores, key=stance_scores.get)
+        
+        # Confidence based on reliability and consensus
+        max_score = stance_scores[best_stance]
+        second_max = max(score for stance, score in stance_scores.items() if stance != best_stance)
+        margin = max_score - second_max if second_max > 0 else max_score
+        
+        confidence = min(0.95, (max_score / sum(stance_scores.values())) + margin * 0.1)
+        
+        return best_stance, confidence, {
+            "method": "reliability_weighted",
+            "stance_scores": stance_scores,
+            "avg_reliability": total_reliability / len(evidence_list)
+        }
+    
+    def _bayesian_update_aggregation(
+        self, 
+        evidence_list: List[StanceEvidence]
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """Bayesian updating approach to stance aggregation."""
+        # Prior probabilities (neutral prior)
+        priors = {"supporting": 0.33, "contradicting": 0.33, "neutral": 0.34}
+        posteriors = priors.copy()
+        
+        for evidence in evidence_list:
+            # Calculate likelihood based on evidence quality
+            reliability_factor = evidence.source_reliability
+            confidence_factor = evidence.confidence
+            method_factor = self.method_weights.get(evidence.method, 1.0)
+            
+            # Likelihood of observing this evidence given each stance
+            if evidence.stance == "supporting":
+                likelihood = {
+                    "supporting": 0.8 * reliability_factor * confidence_factor * method_factor,
+                    "contradicting": 0.1,
+                    "neutral": 0.3
+                }
+            elif evidence.stance == "contradicting":
+                likelihood = {
+                    "supporting": 0.1,
+                    "contradicting": 0.8 * reliability_factor * confidence_factor * method_factor,
+                    "neutral": 0.3
+                }
+            else:  # neutral
+                likelihood = {
+                    "supporting": 0.2,
+                    "contradicting": 0.2,
+                    "neutral": 0.6 * reliability_factor * confidence_factor * method_factor
+                }
+            
+            # Bayesian update
+            evidence_prob = sum(posteriors[stance] * likelihood[stance] for stance in posteriors)
+            if evidence_prob > 0:
+                for stance in posteriors:
+                    posteriors[stance] = (posteriors[stance] * likelihood[stance]) / evidence_prob
+        
+        best_stance = max(posteriors, key=posteriors.get)
+        confidence = posteriors[best_stance]
+        
+        return best_stance, confidence, {
+            "method": "bayesian_update",
+            "posteriors": posteriors,
+            "evidence_count": len(evidence_list)
+        }
+    
+    def _ensemble_aggregation(
+        self, 
+        evidence_list: List[StanceEvidence],
+        claim_text: str = "",
+        context: Optional[Dict[str, Any]] = None
+    ) -> Tuple[str, float, Dict[str, Any]]:
+        """
+        Ensemble method combining multiple aggregation strategies.
+        """
+        # Get results from different strategies
+        strategies = [
+            AggregationStrategy.WEIGHTED_MAJORITY,
+            AggregationStrategy.RELIABILITY_WEIGHTED,
+            AggregationStrategy.BAYESIAN_UPDATE
+        ]
+        
+        results = []
+        for strategy in strategies:
+            old_strategy = self.strategy
+            self.strategy = strategy
+            try:
+                result = self.aggregate_stance_evidence(evidence_list, claim_text, context)
+                results.append(result)
+            except Exception as e:
+                logger.warning("Strategy %s failed: %s", strategy, e)
+            finally:
+                self.strategy = old_strategy
+        
+        if not results:
+            return "neutral", 0.1, {"reason": "all_strategies_failed"}
+        
+        # Combine results with weighted voting
+        stance_votes = {"supporting": 0.0, "contradicting": 0.0, "neutral": 0.0}
+        total_confidence = 0.0
+        
+        strategy_weights = [1.0, 1.2, 0.8]  # Weight reliability-weighted higher
+        
+        for i, (stance, confidence, metadata) in enumerate(results):
+            weight = strategy_weights[i] * confidence
+            stance_votes[stance] += weight
+            total_confidence += confidence
+        
+        if total_confidence == 0:
+            return "neutral", 0.1, {"reason": "zero_ensemble_confidence"}
+        
+        # Final decision
+        best_stance = max(stance_votes, key=stance_votes.get)
+        
+        # Ensemble confidence calculation
+        max_vote = stance_votes[best_stance]
+        total_votes = sum(stance_votes.values())
+        consensus_strength = max_vote / total_votes if total_votes > 0 else 0
+        avg_confidence = total_confidence / len(results)
+        
+        final_confidence = min(0.95, consensus_strength * avg_confidence + 
+                              self._calculate_ensemble_bonus(evidence_list))
+        
+        return best_stance, final_confidence, {
+            "method": "ensemble",
+            "strategy_results": results,
+            "stance_votes": stance_votes,
+            "consensus_strength": consensus_strength,
+            "avg_confidence": avg_confidence
+        }
+    
+    def _calculate_evidence_weight(self, evidence: StanceEvidence) -> float:
+        """Calculate the weight of a piece of evidence."""
+        base_weight = evidence.confidence * evidence.source_reliability
+        
+        # Apply source type multiplier
+        type_multiplier = self.source_type_weights.get(evidence.source_type, 1.0)
+        
+        # Apply method multiplier
+        method_multiplier = self.method_weights.get(evidence.method, 1.0)
+        
+        # Apply relevance and temporal weights
+        relevance_weight = evidence.claim_relevance
+        temporal_weight = evidence.temporal_weight
+        
+        # Text length bonus (longer analysis generally more reliable)
+        length_bonus = min(1.2, 1.0 + (evidence.text_length / 1000) * 0.1)
+        
+        final_weight = (base_weight * type_multiplier * method_multiplier * 
+                       relevance_weight * temporal_weight * length_bonus)
+        
+        return max(0.01, final_weight)  # Minimum weight to avoid zero
+    
+    def _calculate_ensemble_bonus(self, evidence_list: List[StanceEvidence]) -> float:
+        """Calculate bonus confidence for ensemble methods."""
+        # Bonus for having multiple high-quality sources
+        high_quality_count = sum(
+            1 for e in evidence_list 
+            if e.source_reliability >= 0.7 and e.confidence >= 0.6
+        )
+        
+        # Bonus for method diversity
+        unique_methods = len(set(e.method for e in evidence_list))
+        
+        # Bonus for source type diversity
+        unique_source_types = len(set(e.source_type for e in evidence_list))
+        
+        quality_bonus = min(0.15, high_quality_count * 0.03)
+        method_bonus = min(0.1, unique_methods * 0.02)
+        type_bonus = min(0.1, unique_source_types * 0.02)
+        
+        return quality_bonus + method_bonus + type_bonus
+    
+    def assess_uncertainty(self, evidence_list: List[StanceEvidence]) -> Dict[str, Any]:
+        """
+        Assess the uncertainty in the stance classification.
+        
+        Returns:
+            Dictionary with uncertainty metrics
+        """
+        if not evidence_list:
+            return {"high_uncertainty": True, "reason": "no_evidence"}
+        
+        # Calculate stance distribution
+        stance_weights = {"supporting": 0.0, "contradicting": 0.0, "neutral": 0.0}
+        total_weight = 0.0
+        
+        for evidence in evidence_list:
+            weight = self._calculate_evidence_weight(evidence)
+            stance_weights[evidence.stance] += weight
+            total_weight += weight
+        
+        if total_weight == 0:
+            return {"high_uncertainty": True, "reason": "zero_weight"}
+        
+        # Normalize
+        for stance in stance_weights:
+            stance_weights[stance] /= total_weight
+        
+        # Calculate entropy (uncertainty measure)
+        entropy = -sum(p * math.log2(p) for p in stance_weights.values() if p > 0)
+        max_entropy = math.log2(3)  # Maximum entropy for 3 classes
+        normalized_entropy = entropy / max_entropy
+        
+        # Calculate margin between top two stances
+        sorted_weights = sorted(stance_weights.values(), reverse=True)
+        margin = sorted_weights[0] - sorted_weights[1] if len(sorted_weights) > 1 else sorted_weights[0]
+        
+        # Assess evidence quality
+        avg_reliability = sum(e.source_reliability for e in evidence_list) / len(evidence_list)
+        avg_confidence = sum(e.confidence for e in evidence_list) / len(evidence_list)
+        
+        # Determine if uncertainty is high
+        high_uncertainty = (
+            normalized_entropy > 0.8 or  # High entropy
+            margin < 0.2 or  # Small margin
+            avg_reliability < 0.4 or  # Low reliability
+            avg_confidence < 0.5 or  # Low confidence
+            len(evidence_list) < self.min_evidence_count  # Insufficient evidence
+        )
+        
+        return {
+            "high_uncertainty": high_uncertainty,
+            "entropy": entropy,
+            "normalized_entropy": normalized_entropy,
+            "margin": margin,
+            "avg_reliability": avg_reliability,
+            "avg_confidence": avg_confidence,
+            "evidence_count": len(evidence_list),
+            "stance_distribution": stance_weights
+        }
+
+def create_stance_evidence_from_classification(
+    stance: str,
+    confidence: float,
+    source_reliability: float,
+    source_type: str,
+    method: str,
+    text_length: int,
+    claim_relevance: float = 1.0,
+    temporal_weight: float = 1.0
+) -> StanceEvidence:
+    """Helper function to create StanceEvidence from classification results."""
+    return StanceEvidence(
+        stance=stance,
+        confidence=confidence,
+        source_reliability=source_reliability,
+        source_type=source_type,
+        method=method,
+        text_length=text_length,
+        claim_relevance=claim_relevance,
+        temporal_weight=temporal_weight
+    )

reasoning.py

@@ -0,0 +1,862 @@
+"""
+reasoning.py
+============
+Deterministic reasoning engine for InformationIntegrityEnv.
+
+Architecture
+------------
+  EvidenceAggregator   — turns List[ScoredSource] into a numeric evidence score
+  RiskClassifier       — detects high-risk claim domains (medical, violence, etc.)
+  SafetyRules          — override decisions when evidence is insufficient
+  DeterministicReasoningEngine — combines all into a StructuredReasoning result
+
+Evidence score formula
+----------------------
+  For each source:
+    contribution = stance_weight(stance) × reliability × similarity_boost(similarity)
+
+  Stance weights:
+    supporting    → +1.0   (positive contribution)
+    contradicting → -1.0   (negative contribution)
+    neutral       →  0.0   (ignored)
+
+  similarity_boost(sim):
+    sim ≥ 0.60 → 1.20  (high confidence amplifier)
+    sim ≥ 0.40 → 1.00  (normal)
+    sim < 0.40 →  0.60  (low confidence dampener — source is weakly relevant)
+
+  evidence_score = Σ contributions   (not normalised; bounded by SafetyRules logic)
+
+High-risk multiplier
+--------------------
+  When a claim is classified as high-risk (medical misinformation, harmful
+  actions, public health emergencies), the evidence score is multiplied by
+  a configurable factor (default 1.5) to lower the bar for REMOVE.
+
+Decision thresholds (default)
+------------------------------
+  score >  0.30  → ALLOW
+  score < -0.50  → REMOVE   (lowered from -0.70; high-risk claims use -0.35)
+  otherwise      → FLAG
+
+Safety rules (all override the score-based decision)
+------------------------------------------------------
+  1. No sources at all                   → FLAG
+  2. All sources are neutral             → FLAG
+  3. REMOVE needs ≥ min_remove_sources   contradicting sources
+  4. REMOVE needs contradicting reliability ≥ min_remove_reliability
+  5. Score near boundary (|score| < boundary_margin) → FLAG
+  6. ALLOW requires ≥1 high-reliability supporting source
+  7. HIGH-RISK + strong_contra + ≥1 authoritative source → force REMOVE
+
+Multiple-source confidence boost
+---------------------------------
+  When ≥3 contradicting sources agree, confidence is boosted to "high"
+  regardless of individual reliability scores.
+
+All thresholds are configurable via reasoning_config.yaml or env-vars.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+import yaml
+
+from retrieval import ScoredSource
+
+logger = logging.getLogger("reasoning")
+
+REASONING_CONFIG_PATH = os.getenv("REASONING_CONFIG", "reasoning_config.yaml")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Config
+# ─────────────────────────────────────────────────────────────────────────────
+
+_DEFAULTS: Dict[str, float | int] = {
+    # Decision thresholds
+    "allow_threshold":              0.30,   # score > this → ALLOW
+    "remove_threshold":            -0.50,   # score < this → REMOVE
+    "boundary_margin":              0.15,   # |score| < this → force FLAG
+    # High-risk domain settings
+    "high_risk_multiplier":         1.50,   # amplify score magnitude for risky claims
+    "high_risk_remove_threshold":  -0.35,   # lower REMOVE bar for high-risk claims
+    # Similarity boost knees
+    "high_sim_cutoff":              0.60,
+    "low_sim_cutoff":               0.40,
+    "high_sim_boost":               1.20,
+    "low_sim_boost":                0.60,
+    # Safety rule thresholds
+    "min_remove_sources":           2,      # int: min contradicting sources for REMOVE
+    "min_remove_reliability":       0.35,   # avg reliability of contra sources
+    # Consensus-based confidence scaling
+    # Confidence level = min(1.0, base + n_contra * per_source_boost)
+    "consensus_base_confidence":    0.40,   # starting confidence with 1 contra source
+    "consensus_per_source_boost":   0.12,   # +0.12 per additional contradicting source
+    "consensus_high_cutoff":        0.75,   # ≥ this scaled value → "high"
+    "consensus_medium_cutoff":      0.50,   # ≥ this scaled value → "medium"
+    # No-support confidence boost
+    "no_support_bonus":             0.15,   # added when zero supporting sources found
+    # Settled-science auto-remove
+    "settled_science_remove":       1,      # 1=enabled, 0=disabled
+    # Confidence descriptors (fallback when consensus logic doesn't apply)
+    "high_confidence_threshold":    0.50,
+    "low_confidence_threshold":     0.20,
+}
+
+
+class ReasoningConfig:
+    def __init__(self, path: str = REASONING_CONFIG_PATH) -> None:
+        self._cfg = dict(_DEFAULTS)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as fh:
+                loaded = yaml.safe_load(fh) or {}
+            self._cfg.update(loaded)
+
+    def __getattr__(self, name: str):
+        if name == "_cfg":
+            raise AttributeError(name)
+        try:
+            return self._cfg[name]
+        except KeyError:
+            raise AttributeError(f"ReasoningConfig has no attribute '{name}'")
+
+
+_CFG = ReasoningConfig()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Risk Classifier  — identifies high-stakes claim domains
+# ─────────────────────────────────────────────────────────────────────────────
+
+import re as _re
+
+# Each entry: (domain_name, compiled_regex_for_claim_text)
+# A claim matching ANY pattern is tagged as high-risk.
+_RISK_PATTERNS: List[Tuple[str, "_re.Pattern"]] = [
+    # Medical / health misinformation (highest harm)
+    ("medical", _re.compile(
+        r"\b(vaccine|vaccination|vaxx?|covid|coronavirus|sars|flu|cancer|"
+        r"cure|cures|treat|treatment|drug|medication|dose|overdose|"
+        r"autism|5g|radiation|chemotherapy|hiv|aids|ebola|"
+        r"causes?\s+death|kills?|deadly|toxic|poison)\b",
+        _re.IGNORECASE,
+    )),
+    # Harmful actions / violence incitement
+    ("harmful_action", _re.compile(
+        r"\b(drink\s+bleach|inject\s+disinfectant|eat\s+tide|tide\s+pod|"
+        r"ivermectin\s+for\s+human|horse\s+dewormer|"
+        r"suicide\s+method|how\s+to\s+harm|self.harm|bomb\s+making|"
+        r"attack|assassin|terrorist|shoot|stab|murder)\b",
+        _re.IGNORECASE,
+    )),
+    # Public health emergencies
+    ("public_health", _re.compile(
+        r"\b(pandemic|epidemic|outbreak|spread|contagious|"
+        r"herd\s+immunity|lockdown|quarantine|mask|ventilator|"
+        r"hospital\s+overwhelm|icu|death\s+toll)\b",
+        _re.IGNORECASE,
+    )),
+    # Election / democratic integrity
+    ("election", _re.compile(
+        r"\b(election|vote|ballot|voter\s+fraud|stolen\s+election|"
+        r"rigged|electoral|polling|count|recount|certification)\b",
+        _re.IGNORECASE,
+    )),
+    # Climate / environment denial used to block policy
+    ("climate", _re.compile(
+        r"\b(climate\s+change|global\s+warming|carbon|emissions?|"
+        r"ipcc|greenhouse|sea\s+level|arctic|glacier)\b",
+        _re.IGNORECASE,
+    )),
+]
+
+# Authoritative domains that count as "official contradiction"
+_AUTHORITATIVE_DOMAINS = {
+    "who.int", "cdc.gov", "nih.gov", "fda.gov", "nhs.uk",
+    "ecdc.europa.eu", "nasa.gov", "noaa.gov", "reuters.com",
+    "apnews.com", "bbc.com", "bbc.co.uk", "snopes.com",
+    "factcheck.org", "politifact.com", "fullfact.org",
+}
+
+
+class RiskClassifier:
+    """
+    Classifies a claim into a risk domain.
+    High-risk claims get a score multiplier that lowers the REMOVE threshold,
+    mirroring how platforms like Meta and YouTube apply stricter rules to
+    medical misinformation and election integrity content.
+    """
+
+    def classify(self, claim_text: str) -> Optional[str]:
+        """
+        Returns the risk domain name (e.g. 'medical') or None if not high-risk.
+        """
+        for domain, pattern in _RISK_PATTERNS:
+            if pattern.search(claim_text):
+                return domain
+        return None
+
+    def is_authoritative_contra(self, sources: "List[ScoredSource]") -> bool:
+        """
+        Returns True if at least one contradicting source comes from an
+        authoritative domain (WHO, CDC, Reuters, etc.).
+        """
+        for src in sources:
+            if src.stance == "contradicting":
+                domain = self._extract_domain(src.url or "")
+                if any(auth in domain for auth in _AUTHORITATIVE_DOMAINS):
+                    return True
+        return False
+
+    @staticmethod
+    def _extract_domain(url: str) -> str:
+        url = url.lower().split("//")[-1]
+        return url.split("/")[0]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Settled Science Detector
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Claims where scientific consensus is overwhelming (>97% of experts agree).
+# When a claim matches AND contradicting sources exist, the system treats it as
+# settled — confidence is forced to "high" and decision → REMOVE regardless of
+# source count or reliability scores.
+#
+# Each entry: (topic_label, regex_that_matches_the_false_claim)
+_SETTLED_SCIENCE_CLAIMS: List[Tuple[str, "_re.Pattern"]] = [
+    ("flat_earth", _re.compile(
+        r"\b(earth\s+is\s+flat|flat\s+earth|earth\s+isn.t?\s+(round|spherical|a\s+globe))\b",
+        _re.IGNORECASE,
+    )),
+    ("vaccines_autism", _re.compile(
+        r"\bvaccines?\s+(cause[sd]?|linked?\s+to|lead[s]?\s+to)\s+autism\b",
+        _re.IGNORECASE,
+    )),
+    ("climate_hoax", _re.compile(
+        r"\bclimate\s+change\s+is\s+(a\s+)?(hoax|fake|not\s+real|fabricated|made\s+up)\b",
+        _re.IGNORECASE,
+    )),
+    ("evolution_denial", _re.compile(
+        r"\b(evolution\s+is\s+(false|fake|a\s+lie|wrong|disproven)|humans?\s+didn.t?\s+evolve)\b",
+        _re.IGNORECASE,
+    )),
+    ("moon_landing_hoax", _re.compile(
+        r"\b(moon\s+landing\s+(was\s+)?(fake|faked|hoax|staged)|never\s+landed\s+on\s+(the\s+)?moon)\b",
+        _re.IGNORECASE,
+    )),
+    ("5g_covid", _re.compile(
+        r"\b5g\s+(causes?|spreads?|transmits?|created?)\s+(covid|coronavirus|virus|cancer)\b",
+        _re.IGNORECASE,
+    )),
+    ("bleach_cure", _re.compile(
+        r"\b(drink(ing)?\s+bleach|bleach\s+cures?|mms\s+cures?|chlorine\s+dioxide\s+cure)\b",
+        _re.IGNORECASE,
+    )),
+    ("hiv_not_real", _re.compile(
+        r"\b(hiv\s+(doesn.t?\s+cause|doesn.t?\s+exist|is\s+fake)|aids\s+is\s+(a\s+)?(hoax|fake))\b",
+        _re.IGNORECASE,
+    )),
+]
+
+
+class SettledScienceDetector:
+    """
+    Detects claims that contradict overwhelming scientific consensus.
+    When matched + contradicting evidence exists, confidence is forced to
+    "high" and the decision is escalated directly to REMOVE.
+    """
+
+    def is_settled(self, claim_text: str) -> Optional[str]:
+        """
+        Returns the topic label (e.g. 'flat_earth') if the claim contradicts
+        settled science, otherwise None.
+        """
+        for label, pattern in _SETTLED_SCIENCE_CLAIMS:
+            if pattern.search(claim_text):
+                return label
+        return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Data classes
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class SourceEvidence:
+    """Per-source evidence contribution (for explainability)."""
+    source_id:    str
+    title:        str
+    stance:       str
+    reliability:  float
+    similarity:   float
+    contribution: float   # signed score contribution
+
+
+@dataclass
+class StructuredReasoning:
+    """
+    Complete reasoning artifact produced by DeterministicReasoningEngine.
+    Consumed by ExplainabilityEngine and the environment's decide handler.
+    """
+    # Core decision output
+    decision:        str            # "allow" | "flag" | "remove"
+    evidence_score:  float          # raw aggregated score
+    confidence:      str            # "high" | "medium" | "low"
+
+    # Per-source breakdown
+    source_evidence: List[SourceEvidence] = field(default_factory=list)
+
+    # Counts
+    n_supporting:      int = 0
+    n_contradicting:   int = 0
+    n_neutral:         int = 0
+    n_total:           int = 0
+
+    # Safety rule audit trail
+    safety_rules_fired: List[str] = field(default_factory=list)
+
+    # Risk / settled-science classification
+    risk_domain:          Optional[str] = None   # e.g. "medical", "election"
+    settled_science_topic: Optional[str] = None  # e.g. "flat_earth", None
+
+    # Human-readable summary
+    rationale: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "decision":              self.decision,
+            "evidence_score":        round(self.evidence_score, 4),
+            "confidence":            self.confidence,
+            "risk_domain":           self.risk_domain,
+            "settled_science_topic": self.settled_science_topic,
+            "n_supporting":          self.n_supporting,
+            "n_contradicting":       self.n_contradicting,
+            "n_neutral":             self.n_neutral,
+            "n_total":               self.n_total,
+            "safety_rules_fired":    self.safety_rules_fired,
+            "rationale":             self.rationale,
+            "source_breakdown": [
+                {
+                    "id":           e.source_id,
+                    "title":        e.title[:80],
+                    "stance":       e.stance,
+                    "reliability":  round(e.reliability, 3),
+                    "similarity":   round(e.similarity, 3),
+                    "contribution": round(e.contribution, 4),
+                }
+                for e in self.source_evidence
+            ],
+        }
+
+
+# ─────────────────────────────────────���───────────────────────────────────────
+# Part 1 — Evidence Aggregator
+# ─────────────────────────────────────────────────────────────────────────────
+
+class EvidenceAggregator:
+    """
+    Converts a list of scored+filtered sources into a signed numeric score
+    and a per-source breakdown for transparency.
+    """
+
+    # Stance → sign of contribution
+    _STANCE_WEIGHT = {
+        "supporting":    +1.0,
+        "contradicting": -1.0,
+        "neutral":        0.0,
+    }
+
+    # Reliability threshold for "high-quality" source classification
+    _HI_REL = 0.65
+
+    def __init__(self, config: Optional[ReasoningConfig] = None) -> None:
+        self._cfg = config or _CFG
+
+    def aggregate(self, sources: List[ScoredSource]) -> Tuple[float, List[SourceEvidence]]:
+        """
+        Returns (evidence_score, per_source_evidence_list).
+
+        evidence_score is the sum of signed contributions.  It is NOT
+        normalised — callers compare it against the configured thresholds.
+        """
+        evidence: List[SourceEvidence] = []
+        total_score = 0.0
+
+        for src in sources:
+            stance_w = self._STANCE_WEIGHT.get(src.stance, 0.0)
+            sim_boost = self._sim_boost(src.similarity)
+            contribution = stance_w * src.reliability * sim_boost
+
+            evidence.append(SourceEvidence(
+                source_id    = src.id,
+                title        = src.title,
+                stance       = src.stance,
+                reliability  = src.reliability,
+                similarity   = src.similarity,
+                contribution = round(contribution, 4),
+            ))
+            total_score += contribution
+
+        return round(total_score, 4), evidence
+
+    def classify_evidence_state(self, sources: List[ScoredSource]) -> str:
+        """
+        Categorises the overall state of evidence.  Used by the reasoning
+        engine for calibrated confidence and safety-rule decisions.
+
+        Returns one of:
+          "no_evidence"    — no relevant sources at all
+          "strong_contra"  — ≥2 high-reliability contradicting sources
+          "weak_contra"    — contradicting sources but low reliability
+          "strong_support" — ≥2 high-reliability supporting sources
+          "weak_support"   — some supporting but low reliability
+          "conflicting"    — both high-reliability supporting AND contradicting
+          "neutral_only"   — sources exist but all neutral
+        """
+        if not sources:
+            return "no_evidence"
+
+        contra    = [s for s in sources if s.stance == "contradicting"]
+        supp      = [s for s in sources if s.stance == "supporting"]
+        hi_contra = [s for s in contra if s.reliability >= self._HI_REL]
+        hi_supp   = [s for s in supp   if s.reliability >= self._HI_REL]
+
+        if hi_contra and hi_supp:
+            return "conflicting"
+        if len(hi_contra) >= 2:
+            return "strong_contra"
+        if contra:
+            return "weak_contra"
+        if len(hi_supp) >= 2:
+            return "strong_support"
+        if supp:
+            return "weak_support"
+        return "neutral_only"
+
+    def _sim_boost(self, sim: float) -> float:
+        if sim >= self._cfg.high_sim_cutoff:
+            return self._cfg.high_sim_boost
+        if sim >= self._cfg.low_sim_cutoff:
+            return 1.0
+        return self._cfg.low_sim_boost
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 2 — Safety Rules
+# ─────────────────────────────────────────────────────────────────────────────
+
+class SafetyRules:
+    """
+    Post-processes the score-based decision with hard safety constraints.
+    Returns (final_decision, list_of_rules_fired).
+    """
+
+    def __init__(self, config: Optional[ReasoningConfig] = None) -> None:
+        self._cfg = config or _CFG
+
+    def apply(
+        self,
+        score_decision: str,
+        evidence_score: float,
+        sources: List[ScoredSource],
+        evidence: List[SourceEvidence],
+        evidence_state: str = "unknown",
+        risk_domain: Optional[str] = None,
+        has_authoritative_contra: bool = False,
+    ) -> Tuple[str, List[str]]:
+        """
+        Returns (final_decision, fired_rules).
+
+        Rules are evaluated in priority order; first match wins for decision
+        overrides, but ALL fired rules are reported for transparency.
+        """
+        fired: List[str] = []
+        final = score_decision
+
+        # Rule 1: No sources at all → must FLAG
+        if not sources:
+            fired.append("NO_SOURCES: no evidence retrieved — defaulting to FLAG")
+            return "flag", fired
+
+        # Rule 2: All sources neutral → FLAG (can't confirm or deny)
+        if all(s.stance == "neutral" for s in sources):
+            fired.append("ALL_NEUTRAL: all sources are neutral — defaulting to FLAG")
+            final = "flag"
+
+        # Rule 3: REMOVE requires sufficient contradicting evidence
+        if final == "remove":
+            contra = [s for s in sources if s.stance == "contradicting"]
+            if len(contra) < int(self._cfg.min_remove_sources):
+                fired.append(
+                    f"INSUFFICIENT_CONTRA: only {len(contra)} contradicting source(s), "
+                    f"need ≥{int(self._cfg.min_remove_sources)} for REMOVE → downgrading to FLAG"
+                )
+                final = "flag"
+
+        # Rule 4: REMOVE requires contradicting sources to be reliable
+        if final == "remove":
+            contra = [s for s in sources if s.stance == "contradicting"]
+            if contra:
+                avg_rel = sum(s.reliability for s in contra) / len(contra)
+                if avg_rel < self._cfg.min_remove_reliability:
+                    fired.append(
+                        f"LOW_CONTRA_RELIABILITY: avg reliability of contradicting "
+                        f"sources={avg_rel:.2f} < {self._cfg.min_remove_reliability:.2f} → "
+                        f"downgrading to FLAG"
+                    )
+                    final = "flag"
+
+        # Rule 5: Score near boundary → resolve uncertainty with FLAG
+        boundary = self._cfg.boundary_margin
+        if abs(evidence_score) < boundary and final != "flag":
+            fired.append(
+                f"BOUNDARY_UNCERTAINTY: |score|={abs(evidence_score):.3f} < "
+                f"margin={boundary:.2f} — insufficient evidence → FLAG"
+            )
+            final = "flag"
+
+        # Rule 6: ALLOW requires at least one credible supporting source.
+        if final == "allow":
+            hi_rel_support = [
+                s for s in sources
+                if s.stance == "supporting" and s.reliability >= 0.60
+            ]
+            if not hi_rel_support:
+                fired.append(
+                    "NO_CREDIBLE_SUPPORT: decision was ALLOW but no high-reliability "
+                    "supporting sources found — downgrading to FLAG"
+                )
+                final = "flag"
+
+        # Rule 7: HIGH-RISK + strong_contra + authoritative source → force REMOVE
+        # Mirrors Meta/YouTube policy: medical/election misinformation with official
+        # fact-check contradictions is removed automatically, not just flagged.
+        if (
+            risk_domain is not None
+            and evidence_state in ("strong_contra", "weak_contra")
+            and has_authoritative_contra
+            and final in ("flag", "remove")
+        ):
+            fired.append(
+                f"HIGH_RISK_AUTO_REMOVE: claim is in high-risk domain '{risk_domain}' "
+                f"and contradicted by an authoritative source — forcing REMOVE"
+            )
+            final = "remove"
+
+        return final, fired
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 3 — Deterministic Reasoning Engine
+# ─────────────────────────────────────────────────────────────────────────────
+
+class DeterministicReasoningEngine:
+    """
+    Main entry point.  Consumes a list of already-ranked ScoredSources
+    (output of RetrievalPipeline) and produces a StructuredReasoning.
+
+    Usage
+    -----
+        engine  = DeterministicReasoningEngine()
+        result  = engine.reason(claim_text="5G causes COVID", sources=scored_sources)
+        # result.decision → "flag" | "allow" | "remove"
+        # result.to_dict() → full JSON-serialisable breakdown
+    """
+
+    def __init__(self, config: Optional[ReasoningConfig] = None) -> None:
+        self._cfg        = config or _CFG
+        self._aggregator = EvidenceAggregator(config)
+        self._safety     = SafetyRules(config)
+        self._risk       = RiskClassifier()
+        self._settled    = SettledScienceDetector()
+
+    def reason(
+        self,
+        claim_text: str,
+        sources: List[ScoredSource],
+    ) -> StructuredReasoning:
+        """
+        Full deterministic reasoning pass for one claim against its sources.
+        """
+        # Step 1: classify evidence state
+        evidence_state = self._aggregator.classify_evidence_state(sources)
+
+        # Step 2: classify claim risk + settled-science
+        risk_domain        = self._risk.classify(claim_text)
+        has_auth_contra    = self._risk.is_authoritative_contra(sources)
+        settled_topic      = self._settled.is_settled(claim_text)
+
+        # Step 3: aggregate evidence, apply high-risk multiplier if needed
+        score, evidence = self._aggregator.aggregate(sources)
+        if risk_domain is not None and score < 0:
+            score = round(score * self._cfg.high_risk_multiplier, 4)
+            logger.debug("High-risk domain '%s': score amplified to %.3f", risk_domain, score)
+
+        # Step 4: score → raw decision (tighter threshold for high-risk)
+        raw_decision = self._score_to_decision(score, risk_domain)
+
+        # Step 5: apply safety rules
+        final_decision, fired = self._safety.apply(
+            raw_decision, score, sources, evidence,
+            evidence_state, risk_domain, has_auth_contra,
+        )
+
+        # Step 6: settled-science override — any contradicting evidence → REMOVE
+        n_con = sum(1 for s in sources if s.stance == "contradicting")
+        if (
+            settled_topic is not None
+            and n_con >= 1
+            and int(self._cfg.settled_science_remove) == 1
+        ):
+            fired.append(
+                f"SETTLED_SCIENCE: '{settled_topic}' contradicts scientific consensus "
+                f"({n_con} source(s) agree) — forcing REMOVE with high confidence"
+            )
+            final_decision = "remove"
+
+        # Step 7: compute calibrated confidence
+        n_sup = sum(1 for s in sources if s.stance == "supporting")
+        n_neu = sum(1 for s in sources if s.stance == "neutral")
+        confidence = self._confidence(
+            score, sources, evidence_state,
+            n_con=n_con, n_sup=n_sup,
+            settled_topic=settled_topic,
+        )
+
+        # Step 8: build rationale
+        rationale = self._build_rationale(
+            claim_text, final_decision, score, confidence,
+            n_sup, n_con, n_neu, fired, evidence_state,
+            risk_domain, settled_topic,
+        )
+
+        result = StructuredReasoning(
+            decision              = final_decision,
+            evidence_score        = score,
+            confidence            = confidence,
+            source_evidence       = evidence,
+            n_supporting          = n_sup,
+            n_contradicting       = n_con,
+            n_neutral             = n_neu,
+            n_total               = len(sources),
+            safety_rules_fired    = fired,
+            risk_domain           = risk_domain,
+            settled_science_topic = settled_topic,
+            rationale             = rationale,
+        )
+
+        logger.info(
+            "Reasoning: claim='%s…' risk=%s settled=%s state=%s score=%.3f "
+            "raw=%s final=%s conf=%s sources=%d(sup=%d/con=%d/neu=%d) rules=%d",
+            claim_text[:50], risk_domain or "none", settled_topic or "none",
+            evidence_state, score, raw_decision, final_decision, confidence,
+            len(sources), n_sup, n_con, n_neu, len(fired),
+        )
+        return result
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _score_to_decision(self, score: float, risk_domain: Optional[str] = None) -> str:
+        remove_thresh = (
+            self._cfg.high_risk_remove_threshold
+            if risk_domain is not None
+            else self._cfg.remove_threshold
+        )
+        if score > self._cfg.allow_threshold:
+            return "allow"
+        if score < remove_thresh:
+            return "remove"
+        return "flag"
+
+    def _confidence(
+        self,
+        score: float,
+        sources: List[ScoredSource],
+        evidence_state: str,
+        n_con: int = 0,
+        n_sup: int = 0,
+        settled_topic: Optional[str] = None,
+    ) -> str:
+        """
+        Confidence reflects how certain the system is about its decision.
+
+        Priority cascade (highest wins):
+          1. Settled science + any contra evidence  → always "high"
+          2. Consensus scaling: confidence grows with n_contra sources
+             base=0.40, +0.12 per source, +0.15 bonus when n_sup=0
+          3. Evidence state shortcuts (strong_contra/strong_support)
+          4. Reliability-weighted fallback
+        """
+        abs_score = abs(score)
+
+        if evidence_state == "no_evidence" or not sources:
+            return "low"
+
+        # Rule 1: settled science is always high certainty when contradicted
+        if settled_topic is not None and n_con >= 1:
+            return "high"
+
+        # Rule 2: consensus-based scaling
+        if n_con >= 1:
+            raw = self._cfg.consensus_base_confidence + (n_con - 1) * self._cfg.consensus_per_source_boost
+            # Bonus when absolutely no supporting sources exist (no counter-narrative)
+            if n_sup == 0:
+                raw += self._cfg.no_support_bonus
+            raw = min(1.0, raw)
+            if raw >= self._cfg.consensus_high_cutoff:
+                return "high"
+            if raw >= self._cfg.consensus_medium_cutoff:
+                return "medium"
+            return "low"
+
+        # Rule 3: conflicting evidence
+        if evidence_state == "conflicting":
+            return "medium" if abs_score >= 0.3 else "low"
+
+        # Rule 4: strong supporting state
+        if evidence_state == "strong_support" and abs_score >= 0.3:
+            return "high"
+
+        # Rule 5: reliability-weighted fallback
+        n_hi_rel = sum(1 for s in sources if s.reliability >= 0.70)
+        if n_hi_rel >= 2 and abs_score >= 0.40:
+            return "high"
+        if n_hi_rel >= 1 and abs_score >= 0.20:
+            return "medium"
+
+        if abs_score >= self._cfg.high_confidence_threshold:
+            return "high"
+        if abs_score >= self._cfg.low_confidence_threshold:
+            return "medium"
+        return "low"
+
+    @staticmethod
+    def _build_rationale(
+        claim: str,
+        decision: str,
+        score: float,
+        confidence: str,
+        n_sup: int,
+        n_con: int,
+        n_neu: int,
+        fired: List[str],
+        evidence_state: str = "",
+        risk_domain: Optional[str] = None,
+        settled_topic: Optional[str] = None,
+    ) -> str:
+        parts = []
+
+        # Settled science notice (highest priority label)
+        if settled_topic:
+            settled_labels = {
+                "flat_earth":       "flat-Earth (Earth is spherical — settled science)",
+                "vaccines_autism":  "vaccine-autism link (disproven by large-scale studies)",
+                "climate_hoax":     "climate change denial (97%+ scientific consensus)",
+                "evolution_denial": "evolution denial (established biological science)",
+                "moon_landing_hoax": "moon landing conspiracy (documented historical fact)",
+                "5g_covid":         "5G-COVID link (physically impossible — settled science)",
+                "bleach_cure":      "bleach as cure (extremely dangerous pseudoscience)",
+                "hiv_not_real":     "HIV/AIDS denial (settled medical science)",
+            }
+            label = settled_labels.get(settled_topic, f"{settled_topic} (settled science)")
+            parts.append(f"SETTLED SCIENCE: This claim involves {label}.")
+
+        elif risk_domain:
+            domain_labels = {
+                "medical":        "medical/health misinformation",
+                "harmful_action": "content promoting harmful actions",
+                "public_health":  "public health misinformation",
+                "election":       "election integrity misinformation",
+                "climate":        "climate misinformation",
+            }
+            label = domain_labels.get(risk_domain, f"{risk_domain} misinformation")
+            parts.append(f"HIGH-RISK: This claim involves {label}.")
+
+        decision_map = {
+            "allow":  "The claim is supported by available evidence.",
+            "flag":   "The evidence is insufficient or conflicting — the claim is flagged for review.",
+            "remove": "Strong contradicting evidence indicates the claim is false or harmful.",
+        }
+        parts.append(decision_map.get(decision, "Decision made."))
+
+        state_desc = {
+            "strong_contra":  "Multiple high-credibility sources contradict this claim.",
+            "weak_contra":    "Low-credibility sources contradict this claim.",
+            "strong_support": "Multiple high-credibility sources support this claim.",
+            "weak_support":   "Some sources support this claim but their credibility is limited.",
+            "conflicting":    "Sources are divided — some support and some contradict this claim.",
+            "neutral_only":   "Available sources are neutral and do not confirm or deny the claim.",
+            "no_evidence":    "No relevant sources were found to assess this claim.",
+        }
+        if evidence_state in state_desc:
+            parts.append(state_desc[evidence_state])
+
+        # Consensus strength note
+        if n_con >= 1 and n_sup == 0:
+            parts.append(f"No supporting sources found — all {n_con} source(s) contradict the claim.")
+        elif n_con >= 3:
+            parts.append(f"{n_con} independent sources contradict this claim (strong consensus).")
+
+        parts.append(
+            f"Evidence score: {score:+.3f} ({confidence} confidence). "
+            f"Sources: {n_sup} supporting, {n_con} contradicting, {n_neu} neutral."
+        )
+
+        # Safety rules
+        if fired:
+            parts.append("Safety rules applied: " + " | ".join(fired))
+
+        return "  ".join(parts)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Convenience: reason over multiple claims, return aggregate decision
+# ──────────────────────��──────────────────────────────────────────────────────
+
+def reason_over_claims(
+    claim_results: Dict[str, List[ScoredSource]],
+    engine: Optional[DeterministicReasoningEngine] = None,
+) -> Tuple[str, Dict[str, StructuredReasoning]]:
+    """
+    Run reasoning for each claim independently, then derive a single
+    aggregate content decision.
+
+    Parameters
+    ----------
+    claim_results : dict mapping claim_text → List[ScoredSource]
+    engine        : optional pre-built engine (created if None)
+
+    Returns
+    -------
+    (aggregate_decision, per_claim_reasoning_dict)
+
+    Aggregate logic:
+        ANY "remove"  → aggregate = "remove"
+        ANY "flag"    → aggregate = "flag"   (unless already remove)
+        ALL "allow"   → aggregate = "allow"
+    """
+    eng = engine or DeterministicReasoningEngine()
+    per_claim: Dict[str, StructuredReasoning] = {}
+
+    for claim_text, sources in claim_results.items():
+        per_claim[claim_text] = eng.reason(claim_text, sources)
+
+    decisions = [r.decision for r in per_claim.values()]
+    if "remove" in decisions:
+        agg = "remove"
+    elif "flag" in decisions:
+        agg = "flag"
+    elif decisions:
+        agg = "allow"
+    else:
+        agg = "flag"   # no claims → conservative default
+
+    return agg, per_claim

requirements.txt

@@ -0,0 +1,30 @@
+# Core server
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+pydantic>=2.10.0
+
+# HuggingFace Spaces UI
+gradio>=4.44.0
+
+# HTTP client (inference.py ServerEnvClient)
+requests>=2.32.0
+
+# OpenEnv validator
+openenv-core>=0.2.0
+
+# Search backends
+duckduckgo-search==6.3.7
+
+# Redis cache (optional, falls back to in-process dict)
+redis==5.2.1
+
+# Config
+pyyaml==6.0.2
+python-dotenv==1.0.1
+
+# OpenAI-compatible LLM client
+openai>=1.0.0
+
+# Lightweight retrieval
+scikit-learn>=1.4.0
+numpy>=1.26.0

retrieval.py

@@ -0,0 +1,935 @@
+"""
+retrieval.py
+============
+RAG-style retrieval pipeline for InformationIntegrityEnv.
+
+Pipeline:
+  1. QueryRewriter       — rewrites claims into effective search queries
+  2. RelevanceFilter     — scores claim↔source semantic similarity
+  3. SourceRanker        — combines similarity + reliability into a final score
+  4. RetrievalPipeline   — orchestrates all stages, returns ranked sources only
+
+Public helper API (importable standalone):
+  rewrite_query(claim)              → str
+  generate_queries(claim)           → List[str]
+  filter_relevant_sources(claim, sources) → List[dict]
+
+Zero runtime API calls.  Fully deterministic given the same inputs.
+
+Embedding backend (auto-selected at startup):
+  Priority 1 → sentence-transformers  (all-MiniLM-L6-v2, fast + accurate)
+  Priority 2 → scikit-learn TF-IDF    (good for keyword-rich claims)
+  Priority 3 → BM25-style BoW cosine  (pure stdlib, always available)
+
+Configuration via retrieval_config.yaml or environment variables.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import os
+import re
+import string
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+import yaml
+
+logger = logging.getLogger("retrieval")
+
+RETRIEVAL_CONFIG_PATH = os.getenv("RETRIEVAL_CONFIG", "retrieval_config.yaml")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Config
+# ─────────────────────────────────────────────────────────────────────────────
+
+_DEFAULTS = {
+    "relevance_threshold":     0.08,   # min TF-IDF similarity (bigrams improve precision enough)
+    "reliability_threshold":   0.30,   # min reliability to keep a source
+    "top_k":                   6,      # max sources returned per claim
+    "similarity_weight":       0.55,   # weight in combined score
+    "reliability_weight":      0.45,   # weight in combined score
+    "embedding_model":         "all-MiniLM-L6-v2",
+    "keyword_boost_min_overlap": 2,    # keyword overlap to grant a sim boost to high-rel sources
+    "keyword_boost_amount":    0.08,   # added to sim when high-rel source has sufficient overlap
+    "keyword_boost_min_rel":   0.65,   # min reliability to receive keyword boost
+}
+
+
+class RetrievalConfig:
+    def __init__(self, path: str = RETRIEVAL_CONFIG_PATH) -> None:
+        self._cfg = dict(_DEFAULTS)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as fh:
+                loaded = yaml.safe_load(fh) or {}
+            self._cfg.update(loaded)
+
+    def __getattr__(self, name: str):
+        if name == "_cfg":
+            raise AttributeError(name)
+        try:
+            return self._cfg[name]
+        except KeyError:
+            raise AttributeError(f"RetrievalConfig has no attribute '{name}'")
+
+
+_CFG = RetrievalConfig()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Data class for a source that has been scored
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class ScoredSource:
+    id:           str
+    title:        str
+    text:         str
+    url:          str
+    stance:       str
+    reliability:  float
+    source_type:  str
+    similarity:   float  = 0.0   # claim↔source semantic similarity [0,1]
+    combined:     float  = 0.0   # final ranking score [0,1]
+
+    def to_dict(self) -> dict:
+        return {
+            "id":          self.id,
+            "title":       self.title,
+            "text":        self.text,
+            "url":         self.url,
+            "stance":      self.stance,
+            "reliability": round(self.reliability, 4),
+            "source_type": self.source_type,
+            "similarity":  round(self.similarity, 4),
+            "combined":    round(self.combined, 4),
+        }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 1 — Query Rewriter
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Claim type detection ───────────────���─────────────────────────────────────
+_CLAIM_TYPE_PATTERNS = [
+    ("scientific_fact", re.compile(
+        r"\b\d+\s*°[cCfF]\b"
+        r"|\b\d+\s*(degrees?|celsius|fahrenheit|kelvin)\b"
+        r"|\b(speed|velocity)\s+of\s+(light|sound)\b"
+        r"|\b(boil|melt|freez)\w+\s+(point|at)\b"
+        r"|\b(atomic|molecular|chemical|formula|element|compound|periodic)\b"
+        r"|\bph\s*(of|level|value)\b"
+        r"|\b\d+\s*(km|m|cm|mm|kg|g|mg|l|ml|hz|mhz|ghz|nm|km/h|m/s)\b",
+        re.IGNORECASE,
+    )),
+    ("myth", re.compile(
+        r"\b(only\s+use|only\s+uses?)\s+\d+\s*(%|percent)"
+        r"|\b\d+\s*(%|percent)\s+of\s+(your|our|the|their|human)\s+brain\b"
+        r"|\b(flat\s+earth|earth\s+is\s+flat)\b"
+        r"|\b(vaccines?\s+(cause|causes?|link|linked)\s+autism)\b"
+        r"|\b(5g\s+(cause|spread|create)\w*\s+(covid|virus|cancer))\b"
+        r"|\b(bleach\s+cure|drink\s+bleach|inject\s+disinfectant)\b"
+        r"|\b(moon\s+landing\s+(fake|hoax|staged))\b"
+        r"|\b(evolution\s+is\s+(false|fake|wrong|a\s+lie))\b",
+        re.IGNORECASE,
+    )),
+    ("health", re.compile(
+        r"\b(vaccine|vaccination|drug|medication|dose|treatment|cure|cancer|"
+        r"covid|virus|bacteria|disease|symptom|clinical|fda|who|cdc|nhs|"
+        r"study|trial|efficacy|side\s+effect|immune)\b",
+        re.IGNORECASE,
+    )),
+    ("news_event", re.compile(
+        r"\b(government|ministry|president|prime\s+minister|parliament|congress|"
+        r"announce[sd]?|pass(?:ed)?|sign(?:ed)?|reform|policy|election|vote|"
+        r"january|february|march|april|may|june|july|august|september|"
+        r"october|november|december|\b20\d{2}\b)\b",
+        re.IGNORECASE,
+    )),
+]
+
+# ── Symbol / phrase normalisation ────────────────────────────────────────────
+_SYMBOL_NORMALISE = [
+    (re.compile(r"(\d+)\s*°\s*[Cc]\b"), r"\1 degrees celsius"),
+    (re.compile(r"(\d+)\s*°\s*[Ff]\b"), r"\1 degrees fahrenheit"),
+    (re.compile(r"(\d+)\s*°\s*[Kk]\b"), r"\1 kelvin"),
+    (re.compile(r"(\d+)\s*°\b"),         r"\1 degrees"),
+    (re.compile(r"(\d+)\s*%\b"),         r"\1 percent"),
+    (re.compile(r"\bkm/h\b"),            "kilometres per hour"),
+    (re.compile(r"\bm/s\b"),             "metres per second"),
+    (re.compile(r"\bpH\b"),              "pH level"),
+    (re.compile(r"\bCO2\b"),             "carbon dioxide"),
+    (re.compile(r"\bH2O\b"),             "water"),
+    (re.compile(r"\bO2\b"),              "oxygen"),
+    (re.compile(r"\bNaCl\b"),            "sodium chloride salt"),
+]
+
+# ── Type-specific rewrite rules ───────────────────────────────────────────────
+_REWRITE_RULES = [
+    ("scientific_fact",
+     re.compile(r"^(water|mercury|lead|iron|alcohol|ethanol|nitrogen|oxygen)\s+boils?\s+at\b", re.IGNORECASE),
+     lambda m: f"boiling point of {m.group(1).lower()}"),
+    ("scientific_fact",
+     re.compile(r"^(.*?)\s+melts?\s+at\b", re.IGNORECASE),
+     lambda m: f"melting point of {m.group(1).lower()}"),
+    ("myth",
+     re.compile(r"humans?\s+only\s+use[sd]?\s+(\d+\s*(?:percent|%))\s+of\s+(?:their|the|our|human)?\s*brain", re.IGNORECASE),
+     lambda m: f"{m.group(1).replace('%','percent')} brain myth scientific fact"),
+    ("myth",
+     re.compile(r"(earth|world)\s+is\s+flat", re.IGNORECASE),
+     lambda m: f"{m.group(1)} spherical globe scientific proof"),
+]
+
+# ── Negative context keywords (for off-topic filtering) ──────────────────────
+_NEGATIVE_CONTEXT = {
+    "scientific_fact": ["reactor", "nuclear", "fission", "steam turbine", "power plant",
+                        "cooking tip", "recipe for"],
+    "myth": [],
+    "health": ["fictional", "novel", "movie", "song", "game"],
+    "news_event": ["historical", "ancient", "fiction", "fantasy"],
+    "default": [],
+}
+
+# Fact-check site anchors
+_FACTCHECK_SITES = (
+    "site:snopes.com OR site:factcheck.org OR site:politifact.com OR "
+    "site:fullfact.org OR site:boomlive.in OR site:altnews.in OR "
+    "site:factchecker.in OR site:vishvasnews.com"
+)
+
+# Countries for lightweight NER
+_COUNTRIES = [
+    "india", "china", "usa", "united states", "uk", "united kingdom", "russia",
+    "pakistan", "france", "germany", "japan", "australia", "canada", "brazil",
+    "nigeria", "south africa", "italy", "spain", "mexico", "indonesia", "turkey",
+    "saudi arabia", "iran", "ukraine", "israel", "egypt", "argentina",
+]
+
+_TOPIC_TEMPLATES = {
+    "health":     ["{claim}", "fact check {claim}", "is it true {claim} evidence study"],
+    "politics":   ["{claim}", "fact check {claim}", "{claim} evidence official statement"],
+    "technology": ["{claim}", "{claim} scientific evidence", "fact check {claim}"],
+    "climate":    ["{claim}", "{claim} scientific consensus", "fact check {claim}"],
+    "default":    ["{claim}", "fact check {claim}", "{claim} true false evidence"],
+}
+
+_TOPIC_SIGNALS = {
+    "health":     r"vaccine|virus|cancer|disease|drug|health|medical|cure|symptom|covid|pandemic",
+    "politics":   r"government|president|election|congress|policy|law|vote|senator|parliament",
+    "technology": r"5g|ai|chip|algorithm|robot|software|data|internet|cyber|phone",
+    "climate":    r"climate|carbon|emission|warming|fossil|renewable|greenhouse|temperature",
+}
+
+
+def _classify_claim_type(claim: str) -> str:
+    """Return the claim type: scientific_fact | myth | health | news_event | default."""
+    for label, pattern in _CLAIM_TYPE_PATTERNS:
+        if pattern.search(claim):
+            return label
+    return "default"
+
+
+def _normalise_symbols(text: str) -> str:
+    """Replace symbols with word forms for better search-engine matching."""
+    for pattern, replacement in _SYMBOL_NORMALISE:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+class QueryRewriter:
+    """
+    Rewrites a raw claim string into multiple targeted search queries.
+
+    Key improvements:
+    - Claim type detection (scientific_fact / myth / health / news_event)
+    - Symbol normalisation (°C → degrees celsius, % → percent)
+    - Type-specific rewrite rules (boiling point phrasing, myth framing)
+    - 4-variant expansion: factual | verbatim | question-style | fact-check
+    """
+
+    def rewrite(self, claim: str) -> str:
+        """
+        Return the best single search query for a claim.
+
+        Steps: strip prefixes → normalise symbols → type-specific rewrite.
+        """
+        claim = claim.strip().rstrip("?!.")
+        claim = re.sub(
+            r"^(BREAKING|URGENT|CONFIRMED|SHOCKING|EXCLUSIVE)[:\s!]+",
+            "", claim, flags=re.IGNORECASE,
+        ).strip()
+        claim = re.sub(
+            r"^(i heard|they say|apparently|reportedly|rumour has it)[,\s]+",
+            "", claim, flags=re.IGNORECASE,
+        ).strip()
+
+        normalised = _normalise_symbols(claim)
+        claim_type = _classify_claim_type(claim)
+
+        for rule_type, pattern, replacement in _REWRITE_RULES:
+            if rule_type != claim_type:
+                continue
+            m = pattern.search(normalised)
+            if m:
+                prefix = replacement(m)
+                tail   = normalised[m.end():].strip()
+                result = f"{prefix} {tail}".strip()
+                logger.debug("QueryRewriter [%s]: '%s' → '%s'", claim_type, claim[:60], result[:60])
+                return result
+
+        return normalised
+
+    def expand(self, claim: str) -> List[str]:
+        """
+        Generate up to 4 orthogonal search query variants.
+
+        Q1 — rewritten/factual query  (precision for scientific facts & myths)
+        Q2 — verbatim claim           (recall for news articles)
+        Q3 — question-style           (FAQ / encyclopedia pages)
+        Q4 — fact-check site anchor   (explicit debunking/verification)
+        """
+        cleaned    = claim.strip().rstrip("?!.")
+        rewritten  = self.rewrite(cleaned)
+        claim_type = _classify_claim_type(cleaned)
+        entities   = self._extract_entities(cleaned)
+        queries: List[str] = []
+
+        # Q1: type-specific primary query
+        if claim_type == "scientific_fact":
+            queries.append(rewritten)
+        elif claim_type == "myth":
+            base = rewritten if rewritten != cleaned else cleaned
+            queries.append(f"{base} myth scientific evidence explanation")
+        elif claim_type == "health":
+            queries.append(f"{rewritten} clinical evidence study research")
+        elif claim_type == "news_event":
+            anchors = [e for e in [entities.get("country"), entities.get("date")] if e]
+            kw      = " ".join(entities.get("keywords", [])[:3])
+            queries.append(f'{" ".join(anchors)} official {kw}'.strip() if anchors else rewritten)
+        else:
+            queries.append(rewritten)
+
+        # Q2: verbatim (finds news articles that quote the claim directly)
+        if cleaned.lower() != queries[0].lower():
+            queries.append(cleaned)
+
+        # Q3: question-style
+        question = self._to_question(rewritten, claim_type)
+        if question not in queries:
+            queries.append(question)
+
+        # Q4: fact-check site anchor
+        fc_query = f'{_FACTCHECK_SITES} {rewritten}'
+        if fc_query not in queries:
+            queries.append(fc_query)
+
+        seen: set = set()
+        result = []
+        for q in queries:
+            if q not in seen:
+                seen.add(q)
+                result.append(q)
+        return result[:4]
+
+    def to_semantic_text(self, claim: str) -> str:
+        """
+        Produce the text embedded when comparing a claim against a source.
+        Repeats key entities so TF-IDF gives them higher weight.
+        """
+        rewritten = self.rewrite(claim)
+        entities  = self._extract_entities(claim)
+
+        parts = [rewritten]
+        if entities.get("country"):
+            parts.append(entities["country"])
+        if entities.get("date"):
+            parts.append(entities["date"])
+        parts.extend(entities.get("keywords", [])[:3])
+        return " ".join(parts)
+
+    def extract_entities(self, claim: str) -> dict:
+        """Public wrapper around _extract_entities."""
+        return self._extract_entities(self.rewrite(claim))
+
+    def _extract_entities(self, text: str) -> dict:
+        low = text.lower()
+
+        country = None
+        for c in sorted(_COUNTRIES, key=len, reverse=True):
+            if c in low:
+                country = c.title()
+                break
+
+        date_match = re.search(
+            r'\b(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|'
+            r'jul(?:y)?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|'
+            r'dec(?:ember)?)[\s.]*\d{1,2}(?:st|nd|rd|th)?\b'
+            r'|\b\d{1,2}[\s/-]\d{1,2}[\s/-]\d{2,4}\b'
+            r'|\b\d{4}\b',
+            text, re.IGNORECASE,
+        )
+        date = date_match.group(0).strip() if date_match else None
+
+        qty_match = re.search(
+            r'\b\d+(?:\.\d+)?(?:\s*percent|\s*million|\s*billion|\s*crore|\s*lakh)?\b',
+            text,
+        )
+
+        _stop = {
+            "the","a","an","is","are","was","were","in","on","at","to","from",
+            "of","and","or","but","that","this","it","be","will","has","have",
+            "its","by","for","not","with","also","into","than","more","about",
+        }
+        keywords = [
+            w for w in re.findall(r'\b[a-zA-Z]{4,}\b', text.lower())
+            if w not in _stop
+        ][:5]
+
+        return {
+            "country":  country,
+            "date":     date,
+            "quantity": qty_match.group(0) if qty_match else None,
+            "keywords": keywords,
+        }
+
+    @staticmethod
+    def _to_question(rewritten: str, claim_type: str) -> str:
+        low = rewritten.lower()
+        if claim_type == "scientific_fact":
+            if "boiling point" in low or "melting point" in low:
+                return f"what is the {rewritten}"
+            return f"is it true that {rewritten}"
+        if claim_type == "myth":
+            return f"is the {rewritten} true or false"
+        if claim_type == "health":
+            return f"does {rewritten} according to research"
+        return f"is it true that {rewritten}"
+
+    @staticmethod
+    def _detect_topic(text: str) -> str:
+        low = text.lower()
+        for topic, pattern in _TOPIC_SIGNALS.items():
+            if re.search(pattern, low):
+                return topic
+        return "default"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 2 — Embedding / Similarity backend  (auto-selected)
+# ─────────────────────────────────────────────────────────────────────────────
+
+class _EmbeddingBackend:
+    """Abstract interface for all similarity backends."""
+    name: str = "base"
+
+    def similarity(self, text_a: str, text_b: str) -> float:
+        raise NotImplementedError
+
+    def batch_similarity(self, query: str, texts: List[str]) -> List[float]:
+        return [self.similarity(query, t) for t in texts]
+
+
+class _SentenceTransformerBackend(_EmbeddingBackend):
+    name = "sentence-transformers"
+
+    def __init__(self, model_name: str) -> None:
+        from sentence_transformers import SentenceTransformer
+        import numpy as np
+        self._model = SentenceTransformer(model_name)
+        self._np    = np
+        logger.info("Embedding backend: sentence-transformers (%s)", model_name)
+
+    def batch_similarity(self, query: str, texts: List[str]) -> List[float]:
+        np    = self._np
+        all_t = [query] + texts
+        embs  = self._model.encode(all_t, normalize_embeddings=True, show_progress_bar=False)
+        q_emb = embs[0]
+        sims  = [float(np.dot(q_emb, e)) for e in embs[1:]]
+        return [max(0.0, min(1.0, s)) for s in sims]
+
+    def similarity(self, text_a: str, text_b: str) -> float:
+        return self.batch_similarity(text_a, [text_b])[0]
+
+
+class _TfidfBackend(_EmbeddingBackend):
+    name = "tfidf"
+
+    def __init__(self) -> None:
+        from sklearn.feature_extraction.text import TfidfVectorizer
+        from sklearn.metrics.pairwise import cosine_similarity as cos_sim
+        import numpy as np
+        self._Tfidf = TfidfVectorizer
+        self._cos   = cos_sim
+        self._np    = np
+        logger.info("Embedding backend: scikit-learn TF-IDF")
+
+    def batch_similarity(self, query: str, texts: List[str]) -> List[float]:
+        if not texts:
+            return []
+        corpus = [query] + texts
+        try:
+            mat = self._Tfidf(
+                stop_words="english",
+                sublinear_tf=True,      # log(1+tf) — reduces noise from repeated words
+                ngram_range=(1, 2),     # bigrams catch "sunday holiday", "april 5"
+                min_df=1,               # don't drop rare claim-specific terms
+                max_features=8000,
+            ).fit_transform(corpus)
+            sims = self._cos(mat[0:1], mat[1:]).flatten().tolist()
+            return [max(0.0, min(1.0, float(s))) for s in sims]
+        except Exception:
+            return [0.0] * len(texts)
+
+    def similarity(self, text_a: str, text_b: str) -> float:
+        return self.batch_similarity(text_a, [text_b])[0]
+
+
+class _BowBackend(_EmbeddingBackend):
+    """
+    Bag-of-words cosine similarity.  Pure stdlib — zero extra dependencies.
+    Sufficient for keyword-based filtering when better backends are absent.
+    """
+    name = "bow"
+
+    def __init__(self) -> None:
+        logger.info("Embedding backend: BoW cosine (stdlib fallback)")
+        self._stop = {
+            "a","an","the","is","it","in","on","at","to","for","of","and",
+            "or","but","not","be","are","was","were","has","have","had",
+            "this","that","with","from","by","as","about","its","their",
+        }
+
+    def _tokenize(self, text: str) -> dict[str, int]:
+        tokens = re.sub(r"[^a-z0-9\s]", " ", text.lower()).split()
+        freq: dict[str, int] = {}
+        for t in tokens:
+            if t not in self._stop and len(t) > 2:
+                freq[t] = freq.get(t, 0) + 1
+        return freq
+
+    def similarity(self, text_a: str, text_b: str) -> float:
+        fa, fb = self._tokenize(text_a), self._tokenize(text_b)
+        if not fa or not fb:
+            return 0.0
+        vocab   = set(fa) | set(fb)
+        dot     = sum(fa.get(t, 0) * fb.get(t, 0) for t in vocab)
+        norm_a  = math.sqrt(sum(v * v for v in fa.values()))
+        norm_b  = math.sqrt(sum(v * v for v in fb.values()))
+        if norm_a == 0 or norm_b == 0:
+            return 0.0
+        return max(0.0, min(1.0, dot / (norm_a * norm_b)))
+
+    def batch_similarity(self, query: str, texts: List[str]) -> List[float]:
+        return [self.similarity(query, t) for t in texts]
+
+
+def _build_backend(model_name: str) -> _EmbeddingBackend:
+    """Auto-select the best available embedding backend."""
+    try:
+        return _SentenceTransformerBackend(model_name)
+    except Exception:
+        pass
+    try:
+        return _TfidfBackend()
+    except Exception:
+        pass
+    return _BowBackend()
+
+
+# Singleton — loaded once at import time
+_BACKEND: Optional[_EmbeddingBackend] = None
+
+
+def get_backend() -> _EmbeddingBackend:
+    global _BACKEND
+    if _BACKEND is None:
+        _BACKEND = _build_backend(_CFG.embedding_model)
+    return _BACKEND
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 3 — Relevance Filter
+# ─────────────────────────────────────────────────────────────────────────────
+
+class RelevanceFilter:
+    """
+    Scores each source against a claim using semantic similarity.
+    Filters out sources below the relevance threshold.
+    Also enforces a minimum reliability gate.
+    """
+
+    def __init__(
+        self,
+        relevance_threshold: float = _CFG.relevance_threshold,
+        reliability_threshold: float = _CFG.reliability_threshold,
+    ) -> None:
+        self._rel_thr = relevance_threshold
+        self._crd_thr = reliability_threshold
+
+    def filter(
+        self,
+        claim_text: str,
+        sources: List[dict],
+        rewriter: Optional[QueryRewriter] = None,
+    ) -> List[ScoredSource]:
+        """
+        Returns sources that pass both the relevance and reliability gates,
+        each annotated with its similarity score.
+
+        High-reliability sources receive a keyword-overlap boost.
+        Off-topic sources (e.g. "boiling water reactor" for a temperature claim)
+        receive a -0.20 sim penalty before the gate is applied.
+        """
+        if not sources:
+            return []
+
+        rw         = rewriter or QueryRewriter()
+        query_txt  = rw.to_semantic_text(claim_text)
+        claim_type = _classify_claim_type(claim_text)
+        backend    = get_backend()
+
+        source_texts = [
+            s.get("title", "") + " " + s.get("text", "")
+            for s in sources
+        ]
+        similarities = backend.batch_similarity(query_txt, source_texts)
+
+        # Precompute keyword overlap for the boost
+        _stop = {"the","a","an","is","are","was","were","in","on","at","to","from",
+                 "of","and","or","but","that","this","it","be","will","has","have"}
+        claim_kws = {
+            w for w in re.findall(r'\b[a-z]{3,}\b', claim_text.lower())
+            if w not in _stop
+        }
+        boost_min_overlap = int(_CFG.keyword_boost_min_overlap)
+        boost_amount      = float(_CFG.keyword_boost_amount)
+        boost_min_rel     = float(_CFG.keyword_boost_min_rel)
+
+        scored = []
+        for src, sim in zip(sources, similarities):
+            rel = float(src.get("reliability", 0.0))
+
+            # Keyword boost: high-reliability sources with ≥N overlapping claim
+            # keywords get a sim boost so they aren't penalised for paraphrasing
+            if rel >= boost_min_rel and claim_kws:
+                src_kws = {
+                    w for w in re.findall(r'\b[a-z]{3,}\b',
+                    (src.get("title","") + " " + src.get("text","")).lower())
+                    if w not in _stop
+                }
+                if len(claim_kws & src_kws) >= boost_min_overlap:
+                    sim = min(1.0, sim + boost_amount)
+
+            # Off-topic noise penalty: penalise sources whose text contains
+            # known negative-context words for this claim type but lacks
+            # any claim keyword.  This kills "boiling water reactor" matches
+            # when the claim is about temperature, "recipe for pasta" etc.
+            neg_words = _NEGATIVE_CONTEXT.get(claim_type, [])
+            if neg_words:
+                src_low = (src.get("title", "") + " " + src.get("text", "")).lower()
+                has_neg = any(neg in src_low for neg in neg_words)
+                has_claim_kw = bool(claim_kws & {
+                    w for w in re.findall(r'\b[a-z]{3,}\b', src_low) if w not in _stop
+                })
+                if has_neg and not has_claim_kw:
+                    logger.debug(
+                        "Off-topic penalty applied to '%s'",
+                        src.get("title", "?")[:50],
+                    )
+                    sim = max(0.0, sim - 0.20)
+
+            # Hard gates
+            if sim < self._rel_thr:
+                logger.debug(
+                    "Filtered out '%s' (sim=%.3f < threshold=%.3f)",
+                    src.get("title", "?")[:50], sim, self._rel_thr,
+                )
+                continue
+            if rel < self._crd_thr:
+                logger.debug(
+                    "Filtered out '%s' (reliability=%.3f < threshold=%.3f)",
+                    src.get("title", "?")[:50], rel, self._crd_thr,
+                )
+                continue
+
+            scored.append(ScoredSource(
+                id          = src.get("id", ""),
+                title       = src.get("title", ""),
+                text        = src.get("text", ""),
+                url         = src.get("url", ""),
+                stance      = src.get("stance", "neutral"),
+                reliability = rel,
+                source_type = src.get("source_type", "unknown"),
+                similarity  = round(sim, 4),
+            ))
+
+        return scored
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 4 — Source Ranker
+# ─────────────────────────────────────────────────────────────────────────────
+
+class SourceRanker:
+    """
+    Ranks filtered sources by a combined score:
+        combined = w_sim × similarity + w_rel × reliability
+
+    Sources that are contradicting/supporting receive a stance boost
+    because they carry more signal than neutral sources.
+    """
+
+    STANCE_BOOST = {"supporting": 1.10, "contradicting": 1.10, "neutral": 0.80}
+
+    def __init__(
+        self,
+        similarity_weight: float  = _CFG.similarity_weight,
+        reliability_weight: float = _CFG.reliability_weight,
+    ) -> None:
+        self._w_sim = similarity_weight
+        self._w_rel = reliability_weight
+
+    def rank(
+        self,
+        sources: List[ScoredSource],
+        top_k: int = _CFG.top_k,
+    ) -> List[ScoredSource]:
+        """Return at most top_k sources sorted by combined score descending."""
+        for src in sources:
+            boost = self.STANCE_BOOST.get(src.stance, 1.0)
+            src.combined = round(
+                (self._w_sim * src.similarity + self._w_rel * src.reliability) * boost,
+                4,
+            )
+
+        ranked = sorted(sources, key=lambda s: -s.combined)
+        return ranked[:top_k]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 5 — Full RetrievalPipeline
+# ─────────────────────────────────────────────────────��───────────────────────
+
+class RetrievalPipeline:
+    """
+    Orchestrates: rewrite → filter → rank → top-k sources per claim.
+
+    Usage
+    -----
+        pipeline = RetrievalPipeline()
+        ranked   = pipeline.retrieve(claim_text="5G causes COVID", sources=scenario_sources)
+        # ranked is a List[ScoredSource] — relevant only, sorted by quality
+    """
+
+    def __init__(
+        self,
+        rewriter: Optional[QueryRewriter]     = None,
+        filt:     Optional[RelevanceFilter]   = None,
+        ranker:   Optional[SourceRanker]      = None,
+        top_k:    int                         = _CFG.top_k,
+    ) -> None:
+        self._rewriter = rewriter or QueryRewriter()
+        self._filter   = filt    or RelevanceFilter()
+        self._ranker   = ranker  or SourceRanker()
+        self._top_k    = top_k
+
+    def retrieve(
+        self,
+        claim_text: str,
+        sources: List[dict],
+        top_k: Optional[int] = None,
+    ) -> List[ScoredSource]:
+        """
+        Full pipeline for a single claim against a pool of sources.
+
+        Returns
+        -------
+        List[ScoredSource]  — relevant, ranked, top-k.  May be empty if
+                              nothing passes the relevance/reliability gates.
+        """
+        k       = top_k or self._top_k
+        filtered = self._filter.filter(claim_text, sources, self._rewriter)
+        ranked   = self._ranker.rank(filtered, top_k=k)
+
+        logger.info(
+            "Retrieval: claim='%s…' → %d/%d sources pass gates, top-%d returned",
+            claim_text[:50], len(filtered), len(sources), len(ranked),
+        )
+        return ranked
+
+    def retrieve_for_all_claims(
+        self,
+        claims: List[str],
+        sources: List[dict],
+        top_k: Optional[int] = None,
+    ) -> dict[str, List[ScoredSource]]:
+        """
+        Run retrieval for every claim, return a dict keyed by claim text.
+        Sources may appear in multiple claim buckets.
+        """
+        return {
+            claim: self.retrieve(claim, sources, top_k)
+            for claim in claims
+        }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Public standalone API
+# Importable directly: from retrieval import rewrite_query, generate_queries,
+#                                            filter_relevant_sources
+# ─────────────────────────────────────────────────────────────────────────────
+
+_REWRITER_SINGLETON = QueryRewriter()
+
+
+def rewrite_query(claim: str) -> str:
+    """
+    Convert a raw claim into an optimised search query.
+
+    Handles:
+    - Scientific facts  → noun-phrase form  ("boiling point of water 100 degrees celsius")
+    - Myths             → debunking frame   ("10 percent brain myth scientific fact")
+    - News events       → entity-anchored   (keeps country/date context)
+    - Symbols           → word form         (°C → degrees celsius, % → percent)
+
+    Examples
+    --------
+    >>> rewrite_query("Water boils at 100°C at sea level")
+    'boiling point of water 100 degrees celsius at sea level'
+    >>> rewrite_query("Humans only use 10% of their brain")
+    '10 percent brain myth scientific fact'
+    >>> rewrite_query("India removed Sunday holidays in April")
+    'India removed Sunday holidays in April'   # news event — kept as-is with normalisation
+    """
+    return _REWRITER_SINGLETON.rewrite(claim)
+
+
+def generate_queries(claim: str) -> List[str]:
+    """
+    Generate 2–4 orthogonal search query variants for a claim.
+
+    Variant 1 — factual / rewritten (best precision for scientific & myth claims)
+    Variant 2 — verbatim claim      (best recall for news articles)
+    Variant 3 — question-style      ("what is the boiling point of water?")
+    Variant 4 — fact-check anchored ("site:snopes.com OR site:factcheck.org …")
+
+    Examples
+    --------
+    >>> generate_queries("Water boils at 100°C at sea level")
+    [
+      'boiling point of water 100 degrees celsius at sea level',
+      'Water boils at 100°C at sea level',
+      'what is the boiling point of water 100 degrees celsius at sea level',
+      'site:snopes.com OR ... boiling point of water ...',
+    ]
+    """
+    return _REWRITER_SINGLETON.expand(claim)
+
+
+def filter_relevant_sources(
+    claim: str,
+    sources: List[dict],
+    top_k: int = 5,
+    relevance_threshold: float = 0.08,
+) -> List[dict]:
+    """
+    Filter and rank a list of source dicts by relevance to the claim.
+
+    Each source dict must contain at least:
+        {"title": str, "snippet": str, "url": str}
+    Optional keys used if present: "reliability" (float), "stance" (str).
+
+    Scoring
+    -------
+    relevance_score = keyword_overlap_ratio (40%)
+                    + semantic_similarity   (60%, via TF-IDF or sentence-transformers)
+                    - off_topic_penalty     (-0.20 if negative-context words found
+                                             but no claim keywords present)
+
+    Off-topic filter example
+    ------------------------
+    Claim: "Water boils at 100°C at sea level"
+    Rejected: "Boiling Water Reactor — nuclear power plant design"
+              (contains "reactor", "nuclear", no temperature keywords)
+    Accepted: "Boiling point of water — Wikipedia"
+              (contains "boiling", "point", "water", "celsius")
+
+    Parameters
+    ----------
+    claim              : the raw claim string
+    sources            : list of source dicts
+    top_k              : max number of results to return (default 5)
+    relevance_threshold: minimum relevance score to keep a source (default 0.08)
+
+    Returns
+    -------
+    List of source dicts, each augmented with:
+        "relevance_score" : float  (0–1, higher = more relevant)
+        "keyword_overlap" : int    (number of claim keywords found in source)
+    Sorted by relevance_score descending, top_k results only.
+    """
+    if not sources:
+        return []
+
+    claim_type = _classify_claim_type(claim)
+    rewritten  = _REWRITER_SINGLETON.rewrite(claim)
+    backend    = get_backend()
+
+    _stop = {
+        "the","a","an","is","are","was","were","in","on","at","to","from",
+        "of","and","or","but","that","this","it","be","will","has","have",
+        "its","by","for","not","with","also","into","than","more","about",
+    }
+
+    # Claim keywords (from both original and rewritten form)
+    claim_kws = {
+        w for w in re.findall(r'\b[a-z]{3,}\b', (claim + " " + rewritten).lower())
+        if w not in _stop
+    }
+
+    # Normalise sources so both "snippet" and "text" keys work
+    normalised = []
+    for s in sources:
+        text = s.get("snippet") or s.get("text") or ""
+        normalised.append({**s, "_body": s.get("title", "") + " " + text})
+
+    # Semantic similarity scores
+    bodies = [s["_body"] for s in normalised]
+    sem_scores = backend.batch_similarity(
+        _REWRITER_SINGLETON.to_semantic_text(claim), bodies
+    )
+
+    neg_words = _NEGATIVE_CONTEXT.get(claim_type, [])
+    results = []
+
+    for src, sem in zip(normalised, sem_scores):
+        body_low = src["_body"].lower()
+        body_kws = {w for w in re.findall(r'\b[a-z]{3,}\b', body_low) if w not in _stop}
+
+        # Keyword overlap ratio
+        overlap       = len(claim_kws & body_kws)
+        max_possible  = max(len(claim_kws), 1)
+        kw_score      = min(1.0, overlap / max_possible)
+
+        # Combined relevance score
+        relevance = 0.40 * kw_score + 0.60 * sem
+
+        # Off-topic penalty
+        if neg_words:
+            has_neg      = any(neg in body_low for neg in neg_words)
+            has_claim_kw = bool(claim_kws & body_kws)
+            if has_neg and not has_claim_kw:
+                relevance = max(0.0, relevance - 0.20)
+
+        if relevance < relevance_threshold:
+            continue
+
+        out = {k: v for k, v in src.items() if k != "_body"}
+        out["relevance_score"] = round(relevance, 4)
+        out["keyword_overlap"] = overlap
+        results.append(out)
+
+    results.sort(key=lambda x: -x["relevance_score"])
+    return results[:top_k]

reward.py

@@ -0,0 +1,297 @@
+"""
+reward.py
+=========
+Deterministic, itemised reward function for the InformationIntegrity environment.
+
+All reward constants are read from REWARD_CONFIG (default: reward_config.yaml)
+so platform teams can tune them without touching Python code.
+
+Scoring schema
+--------------
+Process rewards (per step):
+  +verify_claim_reward   per unique claim verified
+  +check_source_reward   per unique source checked
+  +multi_source_bonus    when ≥ multi_source_threshold sources consulted
+
+Decision reward (episode end):
+  +decision_correct          decision exactly matches ground truth
+  +decision_partial          decision is one step away (e.g. flag vs remove)
+   0                         decision is fully wrong
+
+Penalties:
+  premature_decision         deciding before min evidence thresholds are met
+  redundant_action           re-verifying a claim or re-checking a source
+  step_inefficiency          applied per step beyond efficient_step_threshold
+  over_aggression            choosing remove when ground truth is allow/flag
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+import yaml
+
+REWARD_CONFIG_PATH = os.getenv("REWARD_CONFIG", "reward_config.yaml")
+
+
+# ---------------------------------------------------------------------------
+# Default constants (used when YAML is absent)
+# ---------------------------------------------------------------------------
+
+_DEFAULTS: Dict[str, float | int] = {
+    # Process
+    "verify_claim_reward":       0.20,
+    "check_source_reward":       0.20,
+    "multi_source_bonus":        0.20,
+    "multi_source_threshold":    3,       # int: sources needed for bonus
+    # Decision
+    "decision_correct":          1.00,
+    "decision_partial":          0.50,
+    "decision_wrong":            0.00,
+    # Penalties (negative values)
+    "premature_decision":       -0.50,
+    "redundant_action":         -0.10,
+    "step_inefficiency":        -0.05,
+    "over_aggression":          -0.30,
+    # Clipping
+    "min_total_reward":         -2.00,
+    "max_total_reward":          2.00,
+    # Evidence gate
+    "min_sources_for_decision":  2,       # int
+    "min_claims_verified_frac":  0.50,    # fraction
+    # Efficiency gate
+    "efficient_step_threshold":  6,       # int: steps before inefficiency kicks in
+}
+
+# Decision adjacency: maps (predicted, ground_truth) → partial credit
+_PARTIAL_CREDIT = {
+    ("flag",   "remove"): True,
+    ("remove", "flag"):   True,
+    ("flag",   "allow"):  True,
+    ("allow",  "flag"):   True,
+}
+
+
+# ---------------------------------------------------------------------------
+# Config loader
+# ---------------------------------------------------------------------------
+
+class RewardConfig:
+    def __init__(self, path: str = REWARD_CONFIG_PATH) -> None:
+        self._cfg = dict(_DEFAULTS)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as fh:
+                loaded = yaml.safe_load(fh) or {}
+            self._cfg.update(loaded)
+
+    def __getattr__(self, name: str):
+        # Guard: _cfg may not exist yet during unpickling/__init__
+        if name == "_cfg":
+            raise AttributeError(name)
+        try:
+            return self._cfg[name]
+        except KeyError:
+            raise AttributeError(f"RewardConfig has no attribute '{name}'")
+
+    def as_dict(self) -> dict:
+        return dict(self._cfg)
+
+
+# ---------------------------------------------------------------------------
+# Episode reward tracker
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EpisodeRewardState:
+    """
+    Mutable accumulator attached to one environment episode.
+    Tracks which claims/sources have already received process rewards.
+    """
+    verified_claims: set[str]     = field(default_factory=set)
+    checked_sources: set[str]     = field(default_factory=set)
+    cumulative_reward: float      = 0.0
+    step_count: int               = 0
+
+    # Itemised totals
+    verify_claim_total: float     = 0.0
+    check_source_total: float     = 0.0
+    multi_source_bonus_total: float = 0.0
+    decision_reward_total: float  = 0.0
+    premature_penalty_total: float = 0.0
+    redundant_penalty_total: float = 0.0
+    inefficiency_penalty_total: float = 0.0
+    aggression_penalty_total: float = 0.0
+
+    def reset(self) -> None:
+        self.verified_claims      = set()
+        self.checked_sources      = set()
+        self.cumulative_reward    = 0.0
+        self.step_count           = 0
+        self.verify_claim_total   = 0.0
+        self.check_source_total   = 0.0
+        self.multi_source_bonus_total = 0.0
+        self.decision_reward_total = 0.0
+        self.premature_penalty_total = 0.0
+        self.redundant_penalty_total = 0.0
+        self.inefficiency_penalty_total = 0.0
+        self.aggression_penalty_total = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Reward function
+# ---------------------------------------------------------------------------
+
+class RewardFunction:
+    """
+    Stateless reward computer — receives episode state + action result,
+    returns itemised reward dict and a human-readable message.
+    """
+
+    def __init__(self, config: Optional[RewardConfig] = None) -> None:
+        self._cfg = config or RewardConfig()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def compute_verify_claim(
+        self,
+        claim_id: str,
+        state: EpisodeRewardState,
+    ) -> tuple[float, str]:
+        """Reward for verifying a claim."""
+        if claim_id in state.verified_claims:
+            penalty = self._cfg.redundant_action
+            state.redundant_penalty_total += penalty
+            state.cumulative_reward       += penalty
+            return penalty, f"Redundant verification of {claim_id} ({penalty:+.2f})"
+
+        reward = self._cfg.verify_claim_reward
+        state.verified_claims.add(claim_id)
+        state.verify_claim_total  += reward
+        state.cumulative_reward   += reward
+
+        # Step inefficiency
+        ineff, msg = self._inefficiency(state)
+        return reward + ineff, f"Verified claim {claim_id} ({reward:+.2f}){msg}"
+
+    def compute_check_source(
+        self,
+        source_id: str,
+        state: EpisodeRewardState,
+    ) -> tuple[float, str]:
+        """Reward for checking a source."""
+        if source_id in state.checked_sources:
+            penalty = self._cfg.redundant_action
+            state.redundant_penalty_total += penalty
+            state.cumulative_reward       += penalty
+            return penalty, f"Redundant source check {source_id} ({penalty:+.2f})"
+
+        reward = self._cfg.check_source_reward
+        state.checked_sources.add(source_id)
+        state.check_source_total  += reward
+        state.cumulative_reward   += reward
+
+        # Multi-source bonus
+        bonus = 0.0
+        n_sources = len(state.checked_sources)
+        threshold = int(self._cfg.multi_source_threshold)
+        if n_sources == threshold:
+            bonus = self._cfg.multi_source_bonus
+            state.multi_source_bonus_total += bonus
+            state.cumulative_reward        += bonus
+
+        # Step inefficiency
+        ineff, msg = self._inefficiency(state)
+        total = reward + bonus + ineff
+        bonus_msg = f" +multi-source bonus ({bonus:+.2f})" if bonus else ""
+        return total, f"Checked source {source_id} ({reward:+.2f}){bonus_msg}{msg}"
+
+    def compute_decision(
+        self,
+        decision: str,
+        ground_truth: str,
+        state: EpisodeRewardState,
+        num_claims: int,
+    ) -> tuple[float, str]:
+        """Reward/penalty for the final decision action."""
+        total = 0.0
+        messages = []
+
+        # ---- Premature decision gate ----
+        n_sources    = len(state.checked_sources)
+        n_verified   = len(state.verified_claims)
+        min_sources  = int(self._cfg.min_sources_for_decision)
+        min_verified = self._cfg.min_claims_verified_frac
+
+        is_premature = (
+            n_sources  < min_sources
+            or (num_claims > 0 and n_verified / num_claims < min_verified)
+        )
+        if is_premature:
+            penalty = self._cfg.premature_decision
+            state.premature_penalty_total += penalty
+            state.cumulative_reward       += penalty
+            total   += penalty
+            messages.append(f"premature decision ({penalty:+.2f})")
+
+        # ---- Correctness ----
+        if decision == ground_truth:
+            reward = self._cfg.decision_correct
+            messages.append(f"correct decision ({reward:+.2f})")
+        elif _PARTIAL_CREDIT.get((decision, ground_truth), False):
+            reward = self._cfg.decision_partial
+            messages.append(f"partially correct decision ({reward:+.2f})")
+        else:
+            reward = self._cfg.decision_wrong
+            messages.append("wrong decision (0.00)")
+
+        state.decision_reward_total += reward
+        state.cumulative_reward     += reward
+        total += reward
+
+        # ---- Over-aggression penalty ----
+        if decision == "remove" and ground_truth in ("allow", "flag"):
+            penalty = self._cfg.over_aggression
+            state.aggression_penalty_total += penalty
+            state.cumulative_reward        += penalty
+            total += penalty
+            messages.append(f"over-aggressive moderation ({penalty:+.2f})")
+
+        return total, "; ".join(messages)
+
+    def final_score(self, state: EpisodeRewardState) -> float:
+        """Return cumulative reward clipped to [min, max]."""
+        return float(max(
+            self._cfg.min_total_reward,
+            min(self._cfg.max_total_reward, state.cumulative_reward),
+        ))
+
+    def breakdown_dict(self, state: EpisodeRewardState) -> dict:
+        return {
+            "verify_claim_reward":    round(state.verify_claim_total, 4),
+            "check_source_reward":    round(state.check_source_total, 4),
+            "multi_source_bonus":     round(state.multi_source_bonus_total, 4),
+            "decision_reward":        round(state.decision_reward_total, 4),
+            "premature_penalty":      round(state.premature_penalty_total, 4),
+            "redundant_penalty":      round(state.redundant_penalty_total, 4),
+            "inefficiency_penalty":   round(state.inefficiency_penalty_total, 4),
+            "aggression_penalty":     round(state.aggression_penalty_total, 4),
+            "cumulative":             round(state.cumulative_reward, 4),
+            "final_clipped":          round(self.final_score(state), 4),
+        }
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _inefficiency(self, state: EpisodeRewardState) -> tuple[float, str]:
+        threshold = int(self._cfg.efficient_step_threshold)
+        if state.step_count > threshold:
+            penalty = self._cfg.step_inefficiency
+            state.inefficiency_penalty_total += penalty
+            state.cumulative_reward          += penalty
+            return penalty, f" inefficiency ({penalty:+.2f})"
+        return 0.0, ""

reward_config.yaml

@@ -0,0 +1,31 @@
+# reward_config.yaml
+# Tune reward/penalty magnitudes without touching Python code.
+# All values loaded at runtime by reward.py.
+
+# Process rewards
+verify_claim_reward:    0.20
+check_source_reward:    0.20
+multi_source_bonus:     0.20
+multi_source_threshold: 3      # int: number of unique sources for bonus
+
+# Decision rewards
+decision_correct:  1.00
+decision_partial:  0.50
+decision_wrong:    0.00
+
+# Penalties (applied as negative values)
+premature_decision:  -0.50
+redundant_action:    -0.10
+step_inefficiency:   -0.05
+over_aggression:     -0.30
+
+# Clipping
+min_total_reward: -2.00
+max_total_reward:  2.00
+
+# Evidence gate (before decide is allowed without premature penalty)
+min_sources_for_decision: 2
+min_claims_verified_frac: 0.50
+
+# Efficiency gate
+efficient_step_threshold: 6    # int: steps before inefficiency penalty kicks in

run_evaluation.py

@@ -0,0 +1,221 @@
+"""
+run_evaluation.py
+=================
+Runs inference.py once per scenario across all difficulties and aggregates results.
+
+Usage:
+    python run_evaluation.py
+
+Environment variables forwarded to each inference.py subprocess:
+    API_BASE_URL, MODEL_NAME, HF_TOKEN, OPENAI_API_KEY, MAX_STEPS
+
+Each subprocess is run as:
+    DIFFICULTY=<d> SCENARIO_ID=<id> python inference.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+DIFFICULTIES   = ["easy", "medium", "hard"]
+TASKS_DIR      = Path(__file__).parent / "tasks"
+PYTHON         = sys.executable          # same interpreter that runs this script
+INFERENCE_SCRIPT = Path(__file__).parent / "inference.py"
+TIMEOUT        = 180                     # seconds per episode (3 min ceiling)
+
+# Env vars to forward to subprocesses (all LLM + infra config)
+FORWARD_VARS = [
+    "API_BASE_URL", "MODEL_NAME",
+    "HF_TOKEN", "OPENAI_API_KEY",
+    "MAX_STEPS", "REDIS_URL",
+]
+
+
+# ---------------------------------------------------------------------------
+# Load scenarios
+# ---------------------------------------------------------------------------
+
+def load_scenario_ids(difficulty: str) -> list[str]:
+    path = TASKS_DIR / difficulty / "scenarios.json"
+    with open(path, "r", encoding="utf-8") as f:
+        scenarios = json.load(f)
+    return [s["id"] for s in scenarios]
+
+
+# ---------------------------------------------------------------------------
+# Parse [END] line
+# ---------------------------------------------------------------------------
+
+_END_RE = re.compile(
+    r"\[END\]\s+"
+    r"success=(?P<success>\w+)\s+"
+    r"steps=(?P<steps>\d+)\s+"
+    r"score=(?P<score>[\d.]+)"
+)
+
+
+def parse_end_line(output: str) -> Optional[dict]:
+    """Extract score/steps/success from [END] line in subprocess stdout."""
+    for line in output.splitlines():
+        m = _END_RE.search(line)
+        if m:
+            return {
+                "score":   float(m.group("score")),
+                "steps":   int(m.group("steps")),
+                "success": m.group("success").lower() == "true",
+            }
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Run one episode
+# ---------------------------------------------------------------------------
+
+def run_episode(difficulty: str, scenario_id: str) -> Optional[dict]:
+    """
+    Invoke inference.py as a subprocess with DIFFICULTY and SCENARIO_ID set.
+    Returns parsed result dict or None on failure.
+    """
+    print(f"  Running {scenario_id}...", flush=True)
+
+    env = {**os.environ}
+    env["DIFFICULTY"]  = difficulty
+    env["SCENARIO_ID"] = scenario_id
+
+    try:
+        proc = subprocess.run(
+            [PYTHON, str(INFERENCE_SCRIPT)],
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        print(f"    TIMEOUT after {TIMEOUT}s — skipping", flush=True)
+        return None
+    except Exception as exc:
+        print(f"    ERROR launching subprocess: {exc}", flush=True)
+        return None
+
+    # Print [START]/[STEP]/[END] lines live (already captured, echo them)
+    for line in proc.stdout.splitlines():
+        if line.startswith(("[START]", "[STEP]", "[END]")):
+            print(f"    {line}", flush=True)
+
+    if proc.returncode != 0:
+        print(f"    FAILED (exit {proc.returncode})", flush=True)
+        if proc.stderr:
+            # Show last error line only to keep output clean
+            last_err = [l for l in proc.stderr.splitlines() if l.strip()]
+            if last_err:
+                print(f"    stderr: {last_err[-1]}", flush=True)
+        return None
+
+    result = parse_end_line(proc.stdout)
+    if result is None:
+        print(f"    WARNING: could not parse [END] line", flush=True)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Main evaluation loop
+# ---------------------------------------------------------------------------
+
+def run_evaluation() -> dict:
+    results: dict[str, list[dict]] = {d: [] for d in DIFFICULTIES}
+
+    for difficulty in DIFFICULTIES:
+        print(f"\n{'='*40}", flush=True)
+        print(f"Difficulty: {difficulty.upper()}", flush=True)
+        print(f"{'='*40}", flush=True)
+
+        ids = load_scenario_ids(difficulty)
+        for scenario_id in ids:
+            ep = run_episode(difficulty, scenario_id)
+            if ep is not None:
+                ep["scenario_id"] = scenario_id
+                results[difficulty].append(ep)
+            else:
+                results[difficulty].append({
+                    "scenario_id": scenario_id,
+                    "score":       0.0,
+                    "steps":       0,
+                    "success":     False,
+                    "error":       True,
+                })
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Metrics + summary
+# ---------------------------------------------------------------------------
+
+def compute_metrics(episodes: list[dict]) -> dict:
+    if not episodes:
+        return {"avg_score": 0.0, "avg_steps": 0.0, "success_rate": 0.0, "n": 0}
+    n            = len(episodes)
+    avg_score    = sum(e["score"] for e in episodes) / n
+    avg_steps    = sum(e["steps"] for e in episodes) / n
+    success_rate = sum(1 for e in episodes if e["success"]) / n * 100
+    return {"avg_score": avg_score, "avg_steps": avg_steps, "success_rate": success_rate, "n": n}
+
+
+def print_summary(results: dict[str, list[dict]]) -> None:
+    metrics = {d: compute_metrics(results[d]) for d in DIFFICULTIES}
+
+    print("\n" + "=" * 34)
+    print("      FINAL RESULTS")
+    print("=" * 34)
+
+    for difficulty in DIFFICULTIES:
+        m = metrics[difficulty]
+        print(f"\n{difficulty}:")
+        print(f"  avg_score:    {m['avg_score']:.2f}")
+        print(f"  avg_steps:    {m['avg_steps']:.1f}")
+        print(f"  success_rate: {m['success_rate']:.0f}%  ({sum(e['success'] for e in results[difficulty])}/{m['n']})")
+
+    # Difficulty tier validation
+    easy_s   = metrics["easy"]["avg_score"]
+    medium_s = metrics["medium"]["avg_score"]
+    hard_s   = metrics["hard"]["avg_score"]
+
+    print()
+    if easy_s > medium_s > hard_s:
+        print("Difficulty progression validated ✓  (easy > medium > hard)")
+    else:
+        print(
+            "WARNING: Difficulty tiers not well separated "
+            f"(easy={easy_s:.3f}, medium={medium_s:.3f}, hard={hard_s:.3f})"
+        )
+    print()
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    print("Starting evaluation — 15 episodes across easy / medium / hard")
+    print(f"Model : {os.getenv('MODEL_NAME', 'gpt-4o')}")
+    print(f"API   : {os.getenv('API_BASE_URL', 'https://api.openai.com/v1')}")
+    print(f"Timeout per episode: {TIMEOUT}s")
+
+    results = run_evaluation()
+    print_summary(results)

server.py

@@ -0,0 +1,574 @@
+"""
+server.py
+=========
+FastAPI server — exposes InformationIntegrityEnv as an HTTP API.
+
+Compatible with:
+  - HuggingFace Spaces (gradio or docker)
+  - Local Docker deployment
+  - Any OpenEnv-compatible evaluation harness
+
+Endpoints
+---------
+  POST /reset        Start a new episode
+  POST /step         Submit one action
+  GET  /state        Full internal state (debug)
+  POST /collect      Collect a new scenario via DataCollector
+  GET  /health       Liveness probe
+  GET  /scenario     Return current scenario metadata (no ground truth)
+
+Session management
+------------------
+  Each POST /reset returns a session_id.
+  Subsequent /step calls MUST include session_id in the request body.
+  Sessions are stored in Redis (TTL = SESSION_TTL_SECONDS).
+  Fallback: in-process dict (single-worker mode).
+
+Environment variables
+---------------------
+  REDIS_URL            (default redis://localhost:6379)
+  SESSION_TTL_SECONDS  (default 3600)
+  HOST                 (default 0.0.0.0)
+  PORT                 (default 8000)
+  LOG_LEVEL            (default info)
+"""
+
+import json
+import logging
+import os
+import pickle
+import traceback
+import uuid
+from contextlib import asynccontextmanager
+from typing import Any, Dict, List, Optional
+
+import uvicorn
+from fastapi import Body, FastAPI, HTTPException, Query, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, RedirectResponse
+from pydantic import BaseModel, Field
+
+from data_collector import CollectionRequest, DataCollector
+from environment import InformationIntegrityEnv
+from explainability import ExplainabilityEngine, build_reasoning_from_episode
+from models import Action, ActionType, DecisionType, Observation
+
+logger = logging.getLogger("server")
+
+REDIS_URL         = os.getenv("REDIS_URL",           "redis://localhost:6379")
+SESSION_TTL       = int(os.getenv("SESSION_TTL_SECONDS", 3600))
+HOST              = os.getenv("HOST",                 "0.0.0.0")
+PORT              = int(os.getenv("PORT",             7860))
+LOG_LEVEL         = os.getenv("LOG_LEVEL",            "info")
+
+
+# ---------------------------------------------------------------------------
+# Session store (Redis-backed with in-process fallback)
+# ---------------------------------------------------------------------------
+
+class SessionStore:
+    def __init__(self) -> None:
+        self._mem: Dict[str, bytes] = {}
+        self._redis = None
+        try:
+            import redis
+            r = redis.from_url(REDIS_URL)
+            r.ping()
+            self._redis = r
+            logger.info("Session store: Redis at %s", REDIS_URL)
+        except Exception as exc:
+            logger.warning("Redis unavailable (%s) — using in-process session store", exc)
+
+    def get(self, session_id: str) -> Optional[InformationIntegrityEnv]:
+        if self._redis:
+            raw = self._redis.get(f"session:{session_id}")
+        else:
+            raw = self._mem.get(session_id)
+        if raw is None:
+            return None
+        return pickle.loads(raw)
+
+    def set(self, session_id: str, env: InformationIntegrityEnv) -> None:
+        raw = pickle.dumps(env)
+        if self._redis:
+            self._redis.setex(f"session:{session_id}", SESSION_TTL, raw)
+        else:
+            self._mem[session_id] = raw
+
+    def delete(self, session_id: str) -> None:
+        if self._redis:
+            self._redis.delete(f"session:{session_id}")
+        else:
+            self._mem.pop(session_id, None)
+
+    def touch(self, session_id: str) -> None:
+        if self._redis:
+            self._redis.expire(f"session:{session_id}", SESSION_TTL)
+
+
+_sessions = SessionStore()
+_collector = DataCollector()
+_explainer = ExplainabilityEngine()
+
+
+# ---------------------------------------------------------------------------
+# Request / response schemas
+# ---------------------------------------------------------------------------
+
+class ResetRequest(BaseModel):
+    # ---- Programmatic difficulty control (OpenEnv eval path) ----
+    difficulty: Optional[str] = Field(
+        default=None,
+        description="Load a deterministic scenario: 'easy' | 'medium' | 'hard'. "
+                    "Mutually exclusive with `scenario`."
+    )
+    scenario_id: Optional[Any] = Field(
+        default=None,
+        description="Scenario index (int) or id (str) within the difficulty dataset. "
+                    "None = random selection."
+    )
+    # ---- Legacy / custom scenario (DataCollector output) ----
+    scenario: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Pre-collected scenario dict (from POST /collect). "
+                    "If provided, `difficulty` and `scenario_id` are ignored."
+    )
+    max_steps: int = Field(default=20, ge=1, le=100)
+
+
+class ResetResponse(BaseModel):
+    session_id: str
+    observation: Dict[str, Any]
+    message: str = "Episode started"
+
+
+class StepRequest(BaseModel):
+    session_id: str
+    action: Dict[str, Any] = Field(
+        ...,
+        description='e.g. {"type":"verify_claim","claim_id":"claim_001"}'
+    )
+
+
+class StepResponse(BaseModel):
+    session_id: str
+    observation: Dict[str, Any]
+    reward: Dict[str, Any]
+    done: bool
+    info: Dict[str, Any]
+    explanation: Optional[str] = None
+
+
+class CollectRequest(BaseModel):
+    content: str
+    claims: List[str] = Field(..., min_length=1)
+    difficulty: str = "medium"
+    topic: str = ""
+    tags: List[str] = Field(default_factory=list)
+    force_refresh: bool = False
+
+
+class CollectResponse(BaseModel):
+    scenario: Dict[str, Any]
+    cached: bool = False
+
+
+# ---------------------------------------------------------------------------
+# App setup
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logging.basicConfig(
+        level=getattr(logging, LOG_LEVEL.upper(), logging.INFO),
+        format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+    )
+    logger.info("InformationIntegrity env server starting on %s:%s", HOST, PORT)
+    yield
+    logger.info("Server shutting down")
+
+
+app = FastAPI(
+    title="InformationIntegrityEnv",
+    description=(
+        "OpenEnv-compatible deterministic benchmark environment for reasoning-based "
+        "content moderation.\n\n"
+        "Evaluation path: POST /reset with {\"difficulty\": \"easy|medium|hard\"} — "
+        "no DataCollector or Redis required.\n\n"
+        "Custom path: POST /collect then POST /reset with the returned scenario dict."
+    ),
+    version="1.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Exception handler
+# ---------------------------------------------------------------------------
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    logger.error("Unhandled exception: %s\n%s", exc, traceback.format_exc())
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={"detail": str(exc)},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/")
+async def root():
+    return RedirectResponse(url="/ui/")
+
+
+@app.get("/health")
+async def health():
+    return {"status": "healthy", "service": "InformationIntegrityEnv", "version": "1.1.0"}
+
+
+@app.get("/metadata")
+async def metadata():
+    return {
+        "name": "InformationIntegrityEnv",
+        "description": (
+            "A deterministic, benchmarkable content moderation environment where agents "
+            "verify claims, reason over pre-built evidence sources, and make explainable "
+            "moderation decisions (allow / flag / remove)."
+        ),
+        "version": "1.1.0",
+    }
+
+
+@app.get("/schema")
+async def schema():
+    return {
+        "action": Action.model_json_schema(),
+        "observation": Observation.model_json_schema(),
+        "state": {
+            "type": "object",
+            "description": "Full internal environment state (debug only)",
+            "properties": {
+                "episode_id": {"type": "string"},
+                "step_count": {"type": "integer"},
+                "difficulty": {"type": "string"},
+                "done": {"type": "boolean"},
+                "ground_truth": {"type": "string"},
+            },
+        },
+    }
+
+
+@app.post("/mcp")
+async def mcp(request: Request):
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+    req_id = body.get("id") if isinstance(body, dict) else None
+    return {
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "result": {
+            "tools": [],
+            "description": "Use /reset, /step, /state directly.",
+        },
+    }
+
+
+@app.get("/state")
+async def get_state_root():
+    """OpenAPI path discovery stub — returns empty state when no session specified."""
+    return {"status": "no_active_session"}
+
+
+@app.get("/tasks")
+async def list_tasks():
+    """List all available deterministic task datasets with grader metadata."""
+    from tasks.registry import TASKS
+    from tasks.graders import GraderFactory
+    result = []
+    for difficulty in ("easy", "medium", "hard"):
+        try:
+            task = TASKS[difficulty]
+            grader = GraderFactory.get(difficulty)
+            result.append({
+                "id": difficulty,
+                "difficulty": difficulty,
+                "description": (
+                    f"Content moderation — {difficulty} difficulty. "
+                    "Agent must verify claims, evaluate sources, and make a moderation decision."
+                ),
+                "n_scenarios": len(task),
+                "scenario_ids": [s["id"] for s in task.get_all_scenarios()],
+                "grader": {
+                    "enabled": True,
+                    "class": f"tasks.graders.{grader.__class__.__name__}",
+                    "method": "grade",
+                    "score_range": [0.0, 1.0]
+                },
+                "grader_weights": {
+                    "decision":   grader.W_DECISION,
+                    "evidence":   grader.W_EVIDENCE,
+                    "reasoning":  grader.W_REASONING,
+                    "efficiency": grader.W_EFFICIENCY,
+                },
+            })
+        except Exception as exc:
+            result.append({"id": difficulty, "error": str(exc)})
+    return result
+
+
+@app.post("/collect", response_model=CollectResponse)
+async def collect(req: CollectRequest):
+    """
+    Collect real-world evidence for a claim set and cache the scenario.
+    Returns the scenario dict which can be passed directly to /reset.
+    """
+    request = CollectionRequest(
+        content=req.content,
+        claims=req.claims,
+        difficulty=req.difficulty,
+        topic=req.topic,
+        tags=req.tags,
+        force_refresh=req.force_refresh,
+    )
+    scenario = _collector.collect(request)
+    return CollectResponse(scenario=scenario)
+
+
+@app.post("/reset", response_model=ResetResponse)
+async def reset(
+    req: Optional[ResetRequest] = Body(default=None),
+    difficulty: Optional[str] = Query(default=None),
+    scenario_id: Optional[str] = Query(default=None),
+):
+    # Default to easy if no body provided OR if body is empty {}
+    if req is None or (req.difficulty is None and req.scenario is None):
+        req = ResetRequest(difficulty=difficulty or "easy", scenario_id=scenario_id)
+    """
+    Start a new episode.
+
+    Query-parameter form (simplest — works with curl, browser, any HTTP client):
+      POST /reset?difficulty=easy
+      POST /reset?difficulty=medium&scenario_id=2
+      POST /reset?difficulty=hard&scenario_id=hard_001
+
+    JSON body form (same fields, body takes precedence):
+      POST /reset  {"difficulty": "easy"}
+      POST /reset  {"difficulty": "medium", "scenario_id": 2}
+      POST /reset  {"scenario": <dict from /collect>}   ← legacy / live-data path
+    """
+    # Query params fill in body fields when the body fields are absent
+    effective_difficulty  = req.difficulty  or difficulty
+    effective_scenario_id = req.scenario_id if req.scenario_id is not None else scenario_id
+
+    # Back-fill so the rest of the handler uses a single pair of variables
+    req.difficulty  = effective_difficulty
+    req.scenario_id = effective_scenario_id
+
+    # Validate: at least one of difficulty or scenario must be provided
+    if not req.difficulty and not req.scenario:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=(
+                "Provide either 'difficulty' ('easy'|'medium'|'hard') to load a "
+                "deterministic scenario, or 'scenario' (dict from POST /collect)."
+            ),
+        )
+
+    if req.difficulty and req.difficulty not in ("easy", "medium", "hard"):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Invalid difficulty '{req.difficulty}'. Must be easy, medium, or hard.",
+        )
+
+    session_id = str(uuid.uuid4())
+    try:
+        if req.scenario:
+            # Legacy path — caller supplies a pre-collected scenario dict
+            env = InformationIntegrityEnv(
+                scenario=req.scenario,
+                max_steps=req.max_steps,
+            )
+            obs = env.reset()
+        else:
+            # Eval path — load from static dataset (no DataCollector)
+            env = InformationIntegrityEnv.from_dataset(
+                difficulty=req.difficulty,
+                scenario_id=req.scenario_id,
+                max_steps=req.max_steps,
+            )
+            obs = env.reset()
+    except (KeyError, IndexError, FileNotFoundError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Scenario not found: {exc}",
+        )
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Failed to create environment: {exc}",
+        )
+
+    _sessions.set(session_id, env)
+    return ResetResponse(
+        session_id=session_id,
+        observation=obs.model_dump(),
+    )
+
+
+@app.post("/step", response_model=StepResponse)
+async def step(req: StepRequest):
+    """
+    Submit one action and advance the episode.
+    """
+    env = _sessions.get(req.session_id)
+    if env is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{req.session_id}' not found or expired.",
+        )
+
+    try:
+        action = Action(**req.action)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Invalid action: {exc}",
+        )
+
+    try:
+        obs, reward, done, info = env.step(action)
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        )
+
+    # Persist updated env
+    _sessions.set(req.session_id, env)
+    _sessions.touch(req.session_id)
+
+    # Build explanation and attach grader_score when episode ends
+    explanation: Optional[str] = None
+    if done:
+        # Compute grader score and attach to info so the platform can verify it
+        try:
+            ep_result = env.episode_result()
+            info["grader_score"] = ep_result.grader_score
+            info["episode_result"] = ep_result.model_dump()
+        except Exception as exc:
+            logger.warning("grader_score computation failed: %s", exc)
+            info.setdefault("grader_score", 0.005)
+
+        try:
+            decision = info.get("decision") or req.action.get("decision")
+            reasoning = build_reasoning_from_episode(
+                obs=obs,
+                decision=decision or "none",
+                episode_id=env._episode_id,
+                difficulty=env.scenario.difficulty,
+            )
+            explanation = _explainer.generate_explanation(reasoning)
+        except Exception as exc:
+            logger.warning("Explanation generation failed: %s", exc)
+
+    return StepResponse(
+        session_id=req.session_id,
+        observation=obs.model_dump(),
+        reward=reward.model_dump(),
+        done=done,
+        info=info,
+        explanation=explanation,
+    )
+
+
+@app.get("/state/{session_id}")
+async def get_state(session_id: str):
+    """Return full internal environment state (debug/audit endpoint)."""
+    env = _sessions.get(session_id)
+    if env is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return env.state()
+
+
+@app.get("/scenario/{session_id}")
+async def get_scenario(session_id: str):
+    """Return scenario metadata without ground truth (safe for agent use)."""
+    env = _sessions.get(session_id)
+    if env is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    sc = env.scenario
+    return {
+        "id":         sc.id,
+        "difficulty": sc.difficulty,
+        "topic":      sc.topic,
+        "tags":       sc.tags,
+        "content":    sc.content,
+        "n_claims":   len(sc.claims),
+        "n_sources":  len(sc.sources),
+        "claim_ids":  [c.id for c in sc.claims],
+        "source_ids": [s.id for s in sc.sources],
+    }
+
+
+@app.delete("/session/{session_id}")
+async def delete_session(session_id: str):
+    """Explicitly end a session and free memory."""
+    _sessions.delete(session_id)
+    return {"status": "deleted", "session_id": session_id}
+
+
+class GradeRequest(BaseModel):
+    """Request body for the /grade endpoint."""
+    task_id: str = Field(..., description="Task difficulty: easy, medium, or hard")
+    episode: Optional[dict] = Field(default=None, description="Episode data to grade")
+
+
+@app.post("/grade")
+async def grade_episode(req: GradeRequest):
+    """
+    Grade a completed episode for a specific task.
+    This endpoint allows the OpenEnv validator to test graders.
+    """
+    from tasks.graders import GraderFactory
+    
+    try:
+        grader = GraderFactory.get(req.task_id)
+        score = grader.grade(req.episode or {})
+        
+        return {
+            "task_id": req.task_id,
+            "score": score,
+            "score_range": [0.0, 1.0],
+            "grader": f"tasks.graders.{grader.__class__.__name__}"
+        }
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error("Grading failed: %s", traceback.format_exc())
+        raise HTTPException(status_code=500, detail=f"Grading failed: {str(e)}")
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "server:app",
+        host=HOST,
+        port=PORT,
+        log_level=LOG_LEVEL,
+        reload=False,
+    )

server/__init__.py

@@ -0,0 +1,22 @@
+"""
+server/__init__.py
+==================
+Makes `server` a package while still exposing the FastAPI `app`
+defined in the root-level server.py.
+
+We use importlib to load server.py by absolute path, avoiding the
+circular-name clash that would occur with a plain `import server`.
+"""
+
+import importlib.util
+import os
+
+_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_spec = importlib.util.spec_from_file_location(
+    "_server_root",
+    os.path.join(_root, "server.py"),
+)
+_mod = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_mod)
+
+app = _mod.app  # re-export for `from server import app`

server/app.py

@@ -0,0 +1,47 @@
+"""
+server/app.py
+=============
+Entry point for multi-mode deployment (uv run server / python -m server.app).
+
+Loads the FastAPI app from the root-level server.py via importlib so the
+`server` package name does not shadow the root module, and exposes a
+main() function for the [project.scripts] console script entry point.
+"""
+
+import importlib.util
+import os
+import sys
+
+import uvicorn
+
+# Load root server.py by absolute path to avoid circular package import
+_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_spec = importlib.util.spec_from_file_location(
+    "_server_root",
+    os.path.join(_root, "server.py"),
+)
+_mod = importlib.util.module_from_spec(_spec)
+# Ensure the root is on sys.path so root-level imports inside server.py work
+if _root not in sys.path:
+    sys.path.insert(0, _root)
+_spec.loader.exec_module(_mod)
+
+app = _mod.app  # re-export for ASGI runners (e.g. uvicorn server.app:app)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """Console script entry point: uv run server / python -m server.app."""
+    host = os.getenv("HOST", host)
+    port = int(os.getenv("PORT", port))
+    log_level = os.getenv("LOG_LEVEL", "info")
+    uvicorn.run(app, host=host, port=port, log_level=log_level)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(host=args.host, port=args.port)

stance_classifier.py

@@ -0,0 +1,610 @@
+"""
+stance_classifier.py
+====================
+Three-layer stance classification for source ↔ claim pairs.
+
+Layer 1 — Semantic Entailment Heuristics (always runs, zero cost)
+  Detects indirect contradictions and supports that keyword lists miss.
+  Example: "Earth is round" contradicts "Earth is flat" via antonym matching.
+
+Layer 2 — Expanded Keyword Matching (always runs, zero cost)
+  Larger keyword lists, threshold=1 for strong signals (false, debunked, etc.)
+  Falls back on Layer 1 result if ambiguous.
+
+Layer 3 — facebook/bart-large-mnli NLI (completely free, no API key needed)
+  Natural Language Inference: premise=source_text, hypothesis=claim.
+  ENTAILMENT  → SUPPORTS
+  CONTRADICTION → CONTRADICTS 
+  NEUTRAL     → NEUTRAL
+
+  Primary:  HF Inference API  (set HF_TOKEN in .env for higher rate limits;
+            works without token on public models — just slower)
+  Fallback: local `transformers` pipeline (pip install transformers torch)
+
+  Cached in-process — same (claim, source) pair never classified twice.
+
+Priority: NLI result > L1 result > L2 result > neutral
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from typing import Dict, Optional, Tuple
+
+logger = logging.getLogger("stance_classifier")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Layer 1 — Semantic Entailment Heuristics
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Pairs of (claim_pattern → contradicting_signal) for common flat-earth-style claims
+# Each entry: (regex that matches the CLAIM, regex that in the SOURCE indicates contradiction)
+_ENTAILMENT_CONTRA_RULES: list[tuple[str, str]] = [
+    # Shape / science denial
+    (r"\bflat\s+earth\b|\bearth\s+is\s+flat\b",
+     r"\bglobe\b|\bspherical\b|\bround\b|\borbits\b|\bnasa\b|\bscientists\b"),
+    # Vaccine safety
+    (r"\bvaccine.{0,20}(cause|causes|cause[sd]|causing).{0,20}(autism|dna|death|cancer|infertil)",
+     r"\bno\s+evidence\b|\bdebunked\b|\bsafe\b|\bclinical\s+trial\b|\bfda\s+approved\b"),
+    # 5G / radiation
+    (r"\b5g.{0,30}(spread|cause|transmit|covid|virus|cancer|radiation)",
+     r"\bno\s+link\b|\bno\s+evidence\b|\bdebunked\b|\bscientifically\b|\bimpossible\b"),
+    # Climate denial
+    (r"\bclimate\s+change\s+is\s+(fake|hoax|not\s+real)",
+     r"\bscientific\s+consensus\b|\bdata\s+shows\b|\bglobal\s+warming\b|\b97\s*%\b"),
+    # Election / fraud
+    (r"\belection.{0,20}(stolen|rigged|fraud|fake)",
+     r"\bno\s+evidence\b|\bcourts?\s+reject\b|\baudit\b.*\bno\s+fraud\b|\bofficial\s+results?\b"),
+    # General "X never happened"
+    (r"\b(never\s+happened|didn.t\s+happen|is\s+a\s+hoax|is\s+(fake|fabricated))",
+     r"\bconfirmed\b|\bverified\b|\bofficial\s+records?\b|\bdocumented\b"),
+]
+
+# claim_pattern → source_pattern for SUPPORTING signal
+_ENTAILMENT_SUPPORT_RULES: list[tuple[str, str]] = [
+    # Vaccine efficacy
+    (r"\bvaccine.{0,20}(effective|efficacy|prevent|protect)",
+     r"\bclinical\s+trial\b|\befficacy\b|\bphase\s+[23]\b|\bfda\b|\bwho\b"),
+    # Climate consensus
+    (r"\bclimate\s+change\s+is\s+real\b|\bglobal\s+warming\b",
+     r"\bscientific\s+consensus\b|\b97\s*%\b|\bipcc\b|\bnasa\b|\bnoaa\b"),
+    # Official announcements
+    (r"\b(government|ministry|official).{0,30}(announce|confirm|pass|enact)",
+     r"\bofficial\b|\bgovernment\b|\bministry\b|\bgazette\b|\bpib\b|\bofficial\s+statement\b"),
+]
+
+# Antonym pairs: if the claim contains word A and source contains word B (or vice versa)
+# in the same context window, it's likely a contradiction
+_ANTONYM_PAIRS: list[tuple[str, str]] = [
+    ("flat", "spherical"), ("flat", "globe"), ("flat", "round"),
+    ("cure", "no cure"), ("safe", "dangerous"), ("safe", "unsafe"),
+    ("effective", "ineffective"), ("effective", "no evidence"),
+    ("real", "fake"), ("real", "hoax"), ("true", "false"),
+    ("confirmed", "unconfirmed"), ("proven", "disproven"),
+    ("increases", "decreases"), ("causes", "does not cause"),
+    ("linked", "no link"), ("linked", "unrelated"),
+    ("harmful", "harmless"), ("harmful", "safe"),
+]
+
+
+class SemanticHeuristicLayer:
+    """
+    Pattern-matching entailment: catches indirect stances that keyword
+    lists miss because the source paraphrases rather than explicitly labels.
+    """
+
+    def classify(self, claim: str, source_text: str) -> Optional[str]:
+        """
+        Returns 'supporting' | 'contradicting' | None.
+        None means this layer has no signal — defer to next layer.
+        """
+        claim_low  = claim.lower()
+        source_low = source_text.lower()
+
+        # Check contradiction entailment rules
+        for claim_pat, source_pat in _ENTAILMENT_CONTRA_RULES:
+            if re.search(claim_pat, claim_low) and re.search(source_pat, source_low):
+                logger.debug("SemanticHeuristic CONTRA rule matched: claim_pat=%s", claim_pat[:40])
+                return "contradicting"
+
+        # Check support entailment rules
+        for claim_pat, source_pat in _ENTAILMENT_SUPPORT_RULES:
+            if re.search(claim_pat, claim_low) and re.search(source_pat, source_low):
+                logger.debug("SemanticHeuristic SUPPORT rule matched: claim_pat=%s", claim_pat[:40])
+                return "supporting"
+
+        # Antonym detection: extract key noun/adj from claim, look for antonym in source
+        for word_a, word_b in _ANTONYM_PAIRS:
+            if word_a in claim_low and word_b in source_low:
+                return "contradicting"
+            if word_b in claim_low and word_a in source_low:
+                return "contradicting"
+
+        return None   # no signal
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Layer 2 — Expanded Keyword Matching
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Strong single-hit contradicting signals (threshold=1)
+_STRONG_CONTRA = {
+    "false", "debunked", "disproven", "misinformation", "misleading",
+    "no evidence", "lacks evidence", "unfounded", "refuted", "myth",
+    "conspiracy theory", "fact-check", "factcheck", "incorrect",
+    "not true", "inaccurate", "unproven", "pseudoscience", "hoax",
+    "wrong", "fake", "fabricated", "baseless", "discredited",
+}
+
+# Weak contradicting signals (threshold=2 — need two hits)
+_WEAK_CONTRA = {
+    "disputed", "controversial", "unverified", "claims", "alleged",
+    "questioned", "skeptics", "critics", "challenged", "contradicts",
+    "refutes", "rejects", "warns against", "cautioned",
+}
+
+# Strong single-hit supporting signals (threshold=1)
+_STRONG_SUPPORT = {
+    "confirms", "confirmed", "verified", "validated", "proven",
+    "evidence shows", "data shows", "research shows", "study finds",
+    "scientists confirm", "officially announced", "official statement",
+    "press release", "gazette notification", "government confirms",
+    "approved", "endorsed", "supported by evidence",
+}
+
+# Weak supporting signals (threshold=2)
+_WEAK_SUPPORT = {
+    "suggests", "indicates", "shows", "demonstrates", "according to",
+    "reports", "states", "announced", "published", "found that",
+}
+
+
+class KeywordLayer:
+    """
+    Expanded keyword matching with differentiated strong/weak thresholds.
+    Threshold for strong signals = 1 (any single hit is decisive).
+    Threshold for weak signals   = 2 (need corroboration).
+    """
+
+    def classify(self, text: str) -> Tuple[str, float]:
+        """
+        Returns (stance, confidence).
+        stance     = 'supporting' | 'contradicting' | 'neutral'
+        confidence = 0.0–1.0 (how certain this layer is)
+        """
+        low = text.lower()
+
+        strong_contra = sum(1 for kw in _STRONG_CONTRA if kw in low)
+        weak_contra   = sum(1 for kw in _WEAK_CONTRA   if kw in low)
+        strong_supp   = sum(1 for kw in _STRONG_SUPPORT if kw in low)
+        weak_supp     = sum(1 for kw in _WEAK_SUPPORT   if kw in low)
+
+        contra_score = strong_contra * 2 + weak_contra
+        supp_score   = strong_supp * 2 + weak_supp
+
+        # Strong single signal is decisive
+        if strong_contra >= 1 and strong_contra >= strong_supp:
+            conf = min(1.0, 0.6 + 0.1 * strong_contra)
+            return "contradicting", conf
+
+        if strong_supp >= 1 and strong_supp >= strong_contra:
+            conf = min(1.0, 0.6 + 0.1 * strong_supp)
+            return "supporting", conf
+
+        # Weak signals need 2+
+        if contra_score >= 2 and contra_score > supp_score:
+            return "contradicting", 0.45
+
+        if supp_score >= 2 and supp_score > contra_score:
+            return "supporting", 0.45
+
+        return "neutral", 0.20
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Layer 3 — facebook/bart-large-mnli  (NLI, completely free)
+# ─────────────────────────────────────────────────────────────────────────────
+
+_HF_API_URL   = "https://router.huggingface.co/hf-inference/models/facebook/bart-large-mnli/v1/zero-shot-classification"
+_NLI_ENABLED  = os.getenv("STANCE_NLI_ENABLED", "true").lower() != "false"
+
+# Label mapping: HuggingFace returns "ENTAILMENT", "CONTRADICTION", "NEUTRAL"
+_NLI_LABEL_MAP = {
+    "entailment":   "supporting",
+    "contradiction": "contradicting",
+    "neutral":       "neutral",
+}
+
+
+def classify_stance(claim: str, evidence: str) -> dict:
+    """
+    Public NLI helper used by tests / external callers.
+
+    premise   = evidence  (the source text)
+    hypothesis = claim    (what we are verifying)
+
+    Returns:
+        {"stance": "SUPPORTS" | "CONTRADICTS" | "NEUTRAL", "confidence": float}
+    """
+    result = _bart_nli(claim=claim, text=evidence[:512], title="")
+    if result is None:
+        return {"stance": "NEUTRAL", "confidence": 0.20}
+    stance, confidence = result
+    return {
+        "stance": {
+            "supporting": "SUPPORTS",
+            "contradicting": "CONTRADICTS",
+            "neutral": "NEUTRAL",
+        }.get(stance, "NEUTRAL"),
+        "confidence": confidence,
+    }
+
+
+def _bart_nli(claim: str, title: str, text: str) -> Optional[Tuple[str, float]]:
+    """
+    Core NLI call.  Returns (stance_internal, confidence) or None on failure.
+    stance_internal = "supporting" | "contradicting" | "neutral"
+
+    Strategy
+    --------
+    1. Try HF Inference API  (zero-install, rate-limited but free)
+    2. Try local `transformers` pipeline  (no rate limit, needs torch)
+    3. Return None → caller falls back to keyword result
+    """
+    combined = f"{title} {text}".strip()[:512]
+    if not combined:
+        return None
+
+    # ── attempt 1: HF Inference API ──────────────────────────────────────────
+    result = _hf_api_nli(claim=claim, premise=combined)
+    if result is not None:
+        return result
+
+    # ── attempt 2: local transformers ────────────────────────────────────────
+    result = _local_nli(claim=claim, premise=combined)
+    return result   # None if both failed
+
+
+# ── HF Inference API ─────────────────────────────────────────────────────────
+
+def _hf_api_nli(claim: str, premise: str) -> Optional[Tuple[str, float]]:
+    """
+    Calls the HF router zero-shot classification endpoint.
+    Requires HF_TOKEN — set it in .env for free access.
+    Without a token, skips to local transformers.
+    Returns (stance, confidence) or None.
+    """
+    try:
+        import requests as _req
+    except ImportError:
+        return None
+
+    hf_token = os.getenv("HF_TOKEN", "")
+    if not hf_token or hf_token.startswith("your_"):
+        logger.debug("No HF_TOKEN set — skipping HF router API, using local transformers")
+        return None
+
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {hf_token}",
+    }
+
+    # router.huggingface.co zero-shot-classification format:
+    # inputs = the text to classify (premise)
+    # parameters.candidate_labels = the hypothesis options
+    # multi_label=False → softmax across labels (NLI-style)
+    nli_payload = {
+        "inputs": premise,
+        "parameters": {
+            "candidate_labels": ["supports the claim", "contradicts the claim", "unrelated to the claim"],
+            "hypothesis_template": "{}.",
+            "multi_label": False,
+        },
+    }
+
+    try:
+        resp = _req.post(_HF_API_URL, headers=headers, json=nli_payload, timeout=15)
+        if resp.status_code in (503, 502):
+            # Model loading — skip silently, fall through to local
+            logger.debug("HF API: model loading (%s), falling back to local", resp.status_code)
+            return None
+        if not resp.ok:
+            logger.debug("HF API error %s: %s", resp.status_code, resp.text[:120])
+            return None
+
+        data = resp.json()
+        return _parse_hf_router_response(data)
+
+    except Exception as exc:
+        logger.debug("HF API NLI call failed: %s", exc)
+        return None
+
+
+def _parse_hf_router_response(data) -> Optional[Tuple[str, float]]:
+    """
+    Parse the HuggingFace router zero-shot-classification response.
+
+    Expected shape:
+      {
+        "sequence": "...",
+        "labels": ["supports the claim", "contradicts the claim", "unrelated to the claim"],
+        "scores": [0.85, 0.10, 0.05]
+      }
+    """
+    if not data or not isinstance(data, dict):
+        return None
+
+    labels = data.get("labels", [])
+    scores = data.get("scores", [])
+    if not labels or not scores or len(labels) != len(scores):
+        logger.debug("HF router NLI: unexpected response shape: %s", str(data)[:120])
+        return None
+
+    # Map back to internal stance labels
+    label_to_stance = {
+        "supports the claim":     "supporting",
+        "contradicts the claim":  "contradicting",
+        "unrelated to the claim": "neutral",
+    }
+
+    # Pick the highest-scoring label
+    best_idx = scores.index(max(scores))
+    best_label = labels[best_idx].lower()
+    best_score = float(scores[best_idx])
+
+    stance = label_to_stance.get(best_label, "neutral")
+    logger.debug("HF router NLI: '%s' → %s (%.2f)", best_label, stance, best_score)
+    return stance, best_score
+
+
+def _parse_hf_nli_response(data) -> Optional[Tuple[str, float]]:
+    """
+    Legacy parser kept for reference — not called by current code.
+
+    Two possible shapes from old api-inference.huggingface.co:
+      A) List of {"label": "ENTAILMENT", "score": 0.97} dicts
+      B) Nested list from zero-shot endpoint
+    """
+    if not data:
+        return None
+
+    # Shape A: direct label list
+    if isinstance(data, list) and isinstance(data[0], dict) and "label" in data[0]:
+        best = max(data, key=lambda x: x.get("score", 0))
+        label = best["label"].lower()
+        score = float(best.get("score", 0.5))
+        stance = _NLI_LABEL_MAP.get(label, "neutral")
+        logger.debug("HF NLI API: %s → %s (%.2f)", label, stance, score)
+        return stance, score
+
+    # Shape B: nested list [[{label, score}, ...]]
+    if isinstance(data, list) and isinstance(data[0], list):
+        flat = data[0]
+        best = max(flat, key=lambda x: x.get("score", 0))
+        label = best["label"].lower()
+        score = float(best.get("score", 0.5))
+        stance = _NLI_LABEL_MAP.get(label, "neutral")
+        logger.debug("HF NLI API (nested): %s → %s (%.2f)", label, stance, score)
+        return stance, score
+
+    logger.debug("HF NLI: unexpected response shape: %s", str(data)[:120])
+    return None
+
+
+# ── Local transformers pipeline ───────────────────────────────────────────────
+
+_LOCAL_NLI_PIPE = None          # cached pipeline instance
+_LOCAL_NLI_TRIED = False        # avoid retrying failed imports
+
+
+def _local_nli(claim: str, premise: str) -> Optional[Tuple[str, float]]:
+    """
+    Local BART-large-MNLI via the `transformers` library.
+    Returns (stance, confidence) or None.
+    First call downloads ~1.6 GB model; subsequent calls are fast.
+    """
+    global _LOCAL_NLI_PIPE, _LOCAL_NLI_TRIED
+    if _LOCAL_NLI_TRIED and _LOCAL_NLI_PIPE is None:
+        return None    # already failed once — skip
+
+    if _LOCAL_NLI_PIPE is None:
+        _LOCAL_NLI_TRIED = True
+        try:
+            from transformers import pipeline as hf_pipeline
+            logger.info("Loading facebook/bart-large-mnli locally (first call downloads ~1.6 GB)…")
+            _LOCAL_NLI_PIPE = hf_pipeline(
+                "zero-shot-classification",
+                model="facebook/bart-large-mnli",
+                device=-1,       # CPU; set device=0 for GPU
+            )
+            logger.info("BART-MNLI local pipeline ready.")
+        except Exception as exc:
+            logger.warning(
+                "transformers import or model load failed: %s. "
+                "Install with: pip install transformers torch", exc
+            )
+            _LOCAL_NLI_PIPE = None
+            return None
+
+    try:
+        # zero-shot-classification with a three-way NLI hypothesis template
+        # We use claim as the candidate_label so BART tests:
+        #   premise ENTAILS claim / CONTRADICTS claim / NEUTRAL
+        out = _LOCAL_NLI_PIPE(
+            premise,
+            candidate_labels=["true", "false", "unrelated"],
+            hypothesis_template=f"This text {{}} the following: {claim[:200]}",
+        )
+        # out = {"labels": [...], "scores": [...]}
+        label_map = {"true": "supporting", "false": "contradicting", "unrelated": "neutral"}
+        top_label = out["labels"][0].lower()
+        top_score = float(out["scores"][0])
+        stance = label_map.get(top_label, "neutral")
+        logger.debug("Local BART NLI: '%s' → %s (%.2f)", premise[:40], stance, top_score)
+        return stance, top_score
+
+    except Exception as exc:
+        logger.warning("Local BART NLI inference failed: %s", exc)
+        return None
+
+
+# ── In-process NLI result cache ───────────────────────────────────────────────
+
+_NLI_CACHE: Dict[str, Tuple[str, float]] = {}
+
+
+class NLIStanceLayer:
+    """
+    Layer 3: facebook/bart-large-mnli NLI stance classifier.
+
+    Completely free — no API key required for public HF models.
+    Optionally set HF_TOKEN in .env for higher Inference API rate limits.
+
+    Usage is identical to the old LLMStanceLayer interface so the
+    orchestrator (StanceClassifier) needs no changes.
+    """
+
+    def __init__(self) -> None:
+        self._enabled = _NLI_ENABLED
+        if self._enabled:
+            logger.info(
+                "NLI stance layer enabled (facebook/bart-large-mnli). "
+                "Primary: HF Inference API. Fallback: local transformers."
+            )
+        else:
+            logger.info("NLI stance layer disabled via STANCE_NLI_ENABLED=false")
+
+    def available(self) -> bool:
+        return self._enabled
+
+    def classify(self, claim: str, title: str, text: str) -> Optional[str]:
+        """
+        Returns 'supporting' | 'contradicting' | 'neutral' | None.
+        None = both API and local inference failed; caller uses keyword result.
+        """
+        if not self._enabled:
+            return None
+
+        cache_key = hashlib.md5(
+            f"{claim[:120]}||{title[:80]}||{text[:300]}".encode()
+        ).hexdigest()
+        if cache_key in _NLI_CACHE:
+            cached_stance, _ = _NLI_CACHE[cache_key]
+            return cached_stance
+
+        result = _bart_nli(claim=claim, title=title, text=text)
+        if result is None:
+            return None
+
+        stance, confidence = result
+        _NLI_CACHE[cache_key] = (stance, confidence)
+        logger.debug("NLI layer: '%s…' → %s (%.2f)", claim[:40], stance, confidence)
+        return stance
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Orchestrator — combines all three layers
+# ─────────────────────────────────────────────────────────────────────────────
+
+class StanceClassifier:
+    """
+    Three-layer stance classifier for source ↔ claim pairs.
+
+    Priority cascade:
+      1. Semantic heuristics  (pattern matching, no cost)
+      2. Keyword layer        (expanded lists, no cost)
+      3. Claude LLM           (only when uncertain + high-reliability source)
+
+    Usage (drop-in replacement for the old StanceClassifier)
+    ---------------------------------------------------------
+        classifier = StanceClassifier()
+        stance = classifier.classify(text=source_text, claim=claim_text)
+        # returns: "supporting" | "contradicting" | "neutral"
+
+    Advanced (with confidence + layer attribution)
+    ----------------------------------------------
+        stance, confidence, layer = classifier.classify_detailed(
+            title=source_title, text=source_text, claim=claim_text,
+            source_reliability=0.85,
+        )
+    """
+
+    # Minimum reliability a source needs to trigger LLM call when uncertain
+    _LLM_MIN_RELIABILITY = float(os.getenv("STANCE_LLM_MIN_REL", "0.40"))
+
+    def __init__(self) -> None:
+        self._heuristic = SemanticHeuristicLayer()
+        self._keywords  = KeywordLayer()
+        self._llm       = NLIStanceLayer()
+
+    # ------------------------------------------------------------------
+    # Drop-in API (matches old StanceClassifier.classify signature)
+    # ------------------------------------------------------------------
+
+    def classify(self, text: str, claim: str) -> str:
+        """
+        Backward-compatible interface: returns stance string only.
+        title defaults to first 80 chars of text.
+        """
+        title = text[:80]
+        stance, _, _ = self.classify_detailed(
+            title=title, text=text, claim=claim, source_reliability=0.50
+        )
+        return stance
+
+    # ------------------------------------------------------------------
+    # Full API
+    # ------------------------------------------------------------------
+
+    def classify_detailed(
+        self,
+        title: str,
+        text: str,
+        claim: str,
+        source_reliability: float = 0.50,
+    ) -> Tuple[str, float, str]:
+        """
+        Returns (stance, confidence, winning_layer).
+
+        stance          = "supporting" | "contradicting" | "neutral"
+        confidence      = 0.0–1.0
+        winning_layer   = "heuristic" | "keyword" | "llm" | "default"
+        """
+        combined_text = (title + " " + text).strip()
+
+        # ── Layer 1: Semantic heuristics ─────────────────────────────────
+        h_stance = self._heuristic.classify(claim, combined_text)
+        if h_stance is not None:
+            return h_stance, 0.75, "heuristic"
+
+        # ── Layer 2: Keywords ─────────────────────────────────────────────
+        kw_stance, kw_conf = self._keywords.classify(combined_text)
+
+        # If keyword layer is confident, use it
+        if kw_conf >= 0.55:
+            return kw_stance, kw_conf, "keyword"
+
+        # ── Layer 3: NLI (BART-MNLI) — only for uncertain + credible sources ─
+        if (
+            self._llm.available()
+            and source_reliability >= self._LLM_MIN_RELIABILITY
+        ):
+            llm_stance = self._llm.classify(claim, title, text)
+            if llm_stance is not None:
+                return llm_stance, 0.90, "nli"
+
+        # ── Fallback: use whatever keyword layer found ──────────��─────────
+        return kw_stance, kw_conf, "keyword"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Backwards-compat shim: old code did StanceClassifier(scorer)
+# New code supports both StanceClassifier() and StanceClassifier(scorer)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def build_stance_classifier(scorer=None) -> StanceClassifier:
+    """Factory that accepts an optional DomainReliabilityScorer (ignored — kept for compat)."""
+    return StanceClassifier()

tasks/__init__.py

@@ -0,0 +1,5 @@
+# tasks/__init__.py
+from tasks.graders import EasyGrader, MediumGrader, HardGrader, GraderFactory
+from tasks.registry import TASKS, Task
+
+__all__ = ["EasyGrader", "MediumGrader", "HardGrader", "GraderFactory", "TASKS", "Task"]

tasks/easy/scenarios.json

@@ -0,0 +1,313 @@
+[
+  {
+    "id": "easy_001",
+    "difficulty": "easy",
+    "topic": "health_misinformation",
+    "tags": ["covid", "bleach", "health"],
+    "content": "BREAKING: Medical insiders confirm that drinking diluted bleach neutralises COVID-19 within minutes. Share to save lives!",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Drinking bleach cures or neutralises COVID-19",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.99
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "WHO: Do not consume bleach or disinfectants — they are fatal",
+        "text": "The World Health Organization warns that ingesting bleach or disinfectants is extremely dangerous and can be fatal. There is absolutely no evidence that bleach consumption treats or prevents COVID-19.",
+        "url": "https://www.who.int/emergencies/diseases/novel-coronavirus-2019/advice-for-public/myth-busters",
+        "stance": "contradicting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "FDA Safety Alert: Toxic bleach consumption claims circulating online",
+        "text": "The FDA issues a safety alert warning consumers about dangerous online claims promoting bleach ingestion as a COVID-19 cure. Bleach contains sodium hypochlorite which causes severe chemical burns and organ failure when ingested.",
+        "url": "https://www.fda.gov/consumers/consumer-updates/why-you-should-not-use-ivermectin-prevent-or-treat-covid-19",
+        "stance": "contradicting",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_003",
+        "title": "CDC: Household cleaning products are not COVID treatments",
+        "text": "The Centers for Disease Control and Prevention explicitly states that household disinfectants including bleach are not treatments for COVID-19. Consuming these products causes severe poisoning.",
+        "url": "https://www.cdc.gov/coronavirus/2019-ncov/prevent-getting-sick/prevention.html",
+        "stance": "contradicting",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_004",
+        "title": "Anonymous health blog: Natural detox claims",
+        "text": "Some alternative practitioners suggest diluted solutions may help cleanse the body, though mainstream medicine disagrees strongly.",
+        "url": "https://example-health-blog.invalid/detox-claims",
+        "stance": "supporting",
+        "reliability": 0.05,
+        "source_type": "blog",
+        "verification_weight": 0.1
+      },
+      {
+        "id": "src_005",
+        "title": "Poison Control Center: Bleach ingestion emergencies spiked during pandemic",
+        "text": "National Poison Control Centers reported a significant increase in bleach ingestion calls during 2020, directly correlating with social media misinformation about bleach as a COVID cure.",
+        "url": "https://www.poison.org/articles/covid-19-and-cleaning-products",
+        "stance": "contradicting",
+        "reliability": 0.95,
+        "source_type": "official",
+        "verification_weight": 0.95
+      }
+    ],
+    "ground_truth": "remove",
+    "explanation_hint": "Dangerous health misinformation with strong contradicting evidence from multiple authoritative sources. Should be removed."
+  },
+  {
+    "id": "easy_002",
+    "difficulty": "easy",
+    "topic": "science_denial",
+    "tags": ["climate", "nasa", "science"],
+    "content": "NASA scientists ADMIT climate change data has been fabricated for 30 years. The whole global warming scam is exposed!",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "NASA scientists admitted climate change data is fabricated",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.99
+      },
+      {
+        "id": "claim_002",
+        "text": "Global warming is a scam",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.97
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "NASA: 97% of Climate Scientists Agree on Human-Caused Warming",
+        "text": "NASA's official position, supported by multiple independent data sets, confirms that global average temperatures have risen by approximately 1.1°C since the late 19th century, driven by human activities. No NASA scientist has made such admissions.",
+        "url": "https://climate.nasa.gov/scientific-consensus/",
+        "stance": "contradicting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "NOAA Global Surface Temperature Data — Independent Verification",
+        "text": "NOAA's independently verified global temperature records, cross-checked against satellite data, show consistent warming trends consistent with NASA measurements. Data is openly available for third-party verification.",
+        "url": "https://www.noaa.gov/climate",
+        "stance": "contradicting",
+        "reliability": 0.98,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_003",
+        "title": "Climate conspiracy blog post",
+        "text": "An unnamed source claims a NASA whistleblower revealed data manipulation. No names, documents or evidence are provided.",
+        "url": "https://climateskeptic-blog.invalid/nasa-expose",
+        "stance": "supporting",
+        "reliability": 0.04,
+        "source_type": "blog",
+        "verification_weight": 0.05
+      },
+      {
+        "id": "src_004",
+        "title": "Reuters Fact Check: No NASA admission of fabricated climate data",
+        "text": "Reuters fact-checkers found no credible evidence of any NASA admission about fabricated climate data. The claim originates from known misinformation networks.",
+        "url": "https://www.reuters.com/fact-check",
+        "stance": "contradicting",
+        "reliability": 0.92,
+        "source_type": "news",
+        "verification_weight": 0.95
+      },
+      {
+        "id": "src_005",
+        "title": "IPCC Sixth Assessment Report: Unequivocal Evidence of Climate Change",
+        "text": "The Intergovernmental Panel on Climate Change, drawing on thousands of peer-reviewed studies, concluded it is unequivocal that human influence has warmed the atmosphere, ocean and land.",
+        "url": "https://www.ipcc.ch/assessment-report/ar6/",
+        "stance": "contradicting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      }
+    ],
+    "ground_truth": "remove",
+    "explanation_hint": "Both claims are clearly false, contradicted by multiple top-tier scientific authorities. Content should be removed."
+  },
+  {
+    "id": "easy_003",
+    "difficulty": "easy",
+    "topic": "vaccine_safety",
+    "tags": ["vaccine", "mrna", "dna"],
+    "content": "WARNING: mRNA vaccines permanently alter your DNA. Scientists confirm irreversible genetic changes in vaccinated individuals.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "mRNA vaccines permanently alter human DNA",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.99
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "CDC: mRNA vaccines do not alter DNA — here is how they work",
+        "text": "mRNA vaccines work by giving cells instructions to build the spike protein. The mRNA never enters the cell nucleus where DNA is stored and is degraded within a few days. It cannot alter DNA.",
+        "url": "https://www.cdc.gov/coronavirus/2019-ncov/vaccines/different-vaccines/mrna.html",
+        "stance": "contradicting",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "Johns Hopkins Medicine: The science behind mRNA vaccines",
+        "text": "mRNA is messenger RNA, a short-lived molecule that cannot be converted back to DNA under normal biological conditions. Human cells lack the reverse transcriptase enzyme required to integrate mRNA into the genome.",
+        "url": "https://www.hopkinsmedicine.org/health/conditions-and-diseases/coronavirus/is-the-covid19-vaccine-safe",
+        "stance": "contradicting",
+        "reliability": 0.96,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_003",
+        "title": "Anti-vaccine forum post claiming DNA alteration",
+        "text": "Forum user 'TruthSeeker' claims to have seen documents proving DNA alteration. No scientific references provided.",
+        "url": "https://antivax-forum.invalid/dna-alteration",
+        "stance": "supporting",
+        "reliability": 0.03,
+        "source_type": "social",
+        "verification_weight": 0.05
+      },
+      {
+        "id": "src_004",
+        "title": "Nature: mRNA vaccine mechanism — peer-reviewed overview",
+        "text": "Peer-reviewed analysis in Nature confirms mRNA vaccines deliver transient genetic instructions that degrade rapidly. Integration into host DNA would require enzymatic machinery absent in normal human somatic cells.",
+        "url": "https://www.nature.com/articles/s41586-021-03290-1",
+        "stance": "contradicting",
+        "reliability": 0.98,
+        "source_type": "academic",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_005",
+        "title": "WHO Vaccine Safety FAQ",
+        "text": "WHO confirms mRNA vaccines do not interact with or alter an individual's genetic makeup. The mRNA from the vaccine is broken down quickly by the body.",
+        "url": "https://www.who.int/news-room/questions-and-answers/item/coronavirus-disease-(covid-19)-vaccines",
+        "stance": "contradicting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      }
+    ],
+    "ground_truth": "remove",
+    "explanation_hint": "Clear health misinformation contradicted by CDC, WHO, Johns Hopkins, and peer-reviewed science."
+  },
+  {
+    "id": "easy_004",
+    "difficulty": "easy",
+    "topic": "factual_accuracy",
+    "tags": ["geography", "capitals"],
+    "content": "Fun fact: Australia's capital city is Sydney — the largest and most famous city in the country!",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Sydney is the capital city of Australia",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 1.0
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "Australian Government: Canberra is Australia's capital",
+        "text": "The Australian capital is Canberra, located in the Australian Capital Territory. It became the capital in 1913 as a compromise between Sydney and Melbourne. Sydney is the largest city but not the capital.",
+        "url": "https://www.australia.gov.au/about-australia/our-country/our-capital-city",
+        "stance": "contradicting",
+        "reliability": 1.0,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "Encyclopedia Britannica: Canberra — capital of Australia",
+        "text": "Canberra, city and capital of Australia. Canberra is located at the northern end of the Australian Capital Territory and is Australia's only inland city among the major cities.",
+        "url": "https://www.britannica.com/place/Canberra",
+        "stance": "contradicting",
+        "reliability": 0.95,
+        "source_type": "academic",
+        "verification_weight": 0.95
+      },
+      {
+        "id": "src_003",
+        "title": "Travel blog: Sydney — Australia's iconic city",
+        "text": "Many tourists assume Sydney is the capital because of its size and fame, but the actual capital is Canberra.",
+        "url": "https://travel-australia.example/sydney",
+        "stance": "contradicting",
+        "reliability": 0.70,
+        "source_type": "blog",
+        "verification_weight": 0.7
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "Factually incorrect but not dangerous misinformation. Flag rather than remove — it's a common geographic misconception, not a harmful claim."
+  },
+  {
+    "id": "easy_005",
+    "difficulty": "easy",
+    "topic": "legitimate_news",
+    "tags": ["science", "space", "nasa"],
+    "content": "NASA's James Webb Space Telescope has captured images of galaxies from over 13 billion years ago, providing unprecedented views of the early universe.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "James Webb Space Telescope has imaged galaxies from over 13 billion years ago",
+        "ground_truth_status": "true",
+        "ground_truth_confidence": 0.95
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "NASA Webb Telescope: First Deep Field images released",
+        "text": "NASA's James Webb Space Telescope has produced the deepest and sharpest infrared image of the distant universe to date. The image shows the galaxy cluster SMACS 0723 and includes some of the faintest objects ever observed, some dating back over 13 billion years.",
+        "url": "https://www.nasa.gov/image-feature/goddard/2022/nasa-s-webb-delivers-deepest-infrared-image-of-universe-yet",
+        "stance": "supporting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "Nature Astronomy: Webb observations confirm early universe galaxies",
+        "text": "Peer-reviewed analysis confirms JWST has detected light from galaxies with redshifts exceeding z=13, corresponding to approximately 320 million years after the Big Bang — over 13.4 billion years ago.",
+        "url": "https://www.nature.com/articles/s41550-023-02046-1",
+        "stance": "supporting",
+        "reliability": 0.98,
+        "source_type": "academic",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_003",
+        "title": "BBC Science: What Webb has shown us about the early universe",
+        "text": "The James Webb Space Telescope has revolutionised our understanding of the early universe, detecting galaxies from a time when the universe was less than 500 million years old.",
+        "url": "https://www.bbc.co.uk/news/science-environment-62225696",
+        "stance": "supporting",
+        "reliability": 0.88,
+        "source_type": "news",
+        "verification_weight": 0.9
+      }
+    ],
+    "ground_truth": "allow",
+    "explanation_hint": "Factually accurate scientific news supported by NASA and peer-reviewed sources. Allow."
+  }
+]

tasks/graders.py

@@ -0,0 +1,305 @@
+"""
+tasks/graders.py
+================
+Deterministic graders for easy / medium / hard task difficulties.
+
+Each grader scores a completed episode on a 0.0–1.0 scale using four
+independent sub-scores:
+
+  1. decision_score     (0–0.40) — correctness of the final moderation call
+  2. evidence_score     (0–0.30) — how well the agent used available sources
+  3. reasoning_score    (0–0.20) — depth of claim verification
+  4. efficiency_score   (0–0.10) — did the agent avoid unnecessary steps?
+
+Weights differ per difficulty to reflect what matters most:
+  Easy   → decision is paramount; evidence and reasoning are straightforward
+  Medium → evidence quality and reasoning depth matter more
+  Hard   → all four dimensions matter roughly equally; efficiency penalised less
+
+Usage
+-----
+    from tasks.graders import GraderFactory
+
+    grader = GraderFactory.get("medium")
+    score  = grader.score(
+        decision="flag",
+        ground_truth="flag",
+        sources_checked=["src_001", "src_002", "src_003"],
+        claims_verified=["claim_001", "claim_002"],
+        step_count=8,
+        all_source_ids=["src_001", ..., "src_006"],
+        all_claim_ids=["claim_001", "claim_002"],
+    )
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List
+
+
+# ---------------------------------------------------------------------------
+# Partial-credit adjacency for decisions
+# ---------------------------------------------------------------------------
+# (predicted, ground_truth) → credit (0–1)
+_DECISION_CREDIT = {
+    # Exact match
+    ("allow",  "allow"):  1.0,
+    ("flag",   "flag"):   1.0,
+    ("remove", "remove"): 1.0,
+    # One step away
+    ("flag",   "remove"): 0.5,
+    ("remove", "flag"):   0.5,
+    ("flag",   "allow"):  0.5,
+    ("allow",  "flag"):   0.5,
+    # Far apart
+    ("allow",  "remove"): 0.0,
+    ("remove", "allow"):  0.0,
+    ("none",   "allow"):  0.0,
+    ("none",   "flag"):   0.0,
+    ("none",   "remove"): 0.0,
+}
+
+
+# ---------------------------------------------------------------------------
+# Base grader
+# ---------------------------------------------------------------------------
+
+class BaseGrader(ABC):
+
+    # Subclasses set these weights (must sum to 1.0)
+    W_DECISION  : float = 0.40
+    W_EVIDENCE  : float = 0.30
+    W_REASONING : float = 0.20
+    W_EFFICIENCY: float = 0.10
+
+    # Subclasses set these thresholds
+    IDEAL_MAX_STEPS : int   = 10
+    MIN_SOURCE_FRAC : float = 0.40   # fraction of all sources that should be checked
+    MIN_CLAIM_FRAC  : float = 0.50   # fraction of all claims that should be verified
+
+    def grade(self, episode: dict) -> float:
+        """
+        OpenEnv-standard grader interface.
+        Accepts a completed episode dict and returns a score in (0, 1).
+        """
+        return self.score(
+            decision=episode.get("final_decision") or episode.get("decision") or "none",
+            ground_truth=episode.get("ground_truth") or episode.get("correct_decision") or "none",
+            sources_checked=episode.get("sources_checked") or [],
+            claims_verified=episode.get("claims_verified") or [],
+            step_count=int(episode.get("step_count") or 0),
+            all_source_ids=episode.get("all_source_ids") or [],
+            all_claim_ids=episode.get("all_claim_ids") or [],
+        )
+
+    def score(
+        self,
+        decision: str,
+        ground_truth: str,
+        sources_checked: List[str],
+        claims_verified: List[str],
+        step_count: int,
+        all_source_ids: List[str],
+        all_claim_ids: List[str],
+    ) -> float:
+        """Return a normalised score strictly in (0, 1)."""
+        d = self._decision_score(decision, ground_truth)
+        e = self._evidence_score(sources_checked, all_source_ids)
+        r = self._reasoning_score(claims_verified, all_claim_ids)
+        f = self._efficiency_score(step_count)
+
+        raw = (
+            self.W_DECISION   * d
+            + self.W_EVIDENCE   * e
+            + self.W_REASONING  * r
+            + self.W_EFFICIENCY * f
+        )
+        # Clamp strictly inside (0, 1) — validator requires scores never equal 0.0 or 1.0
+        return round(max(0.005, min(0.995, raw)), 4)
+
+    def score_breakdown(
+        self,
+        decision: str,
+        ground_truth: str,
+        sources_checked: List[str],
+        claims_verified: List[str],
+        step_count: int,
+        all_source_ids: List[str],
+        all_claim_ids: List[str],
+    ) -> dict:
+        """Return full breakdown for audit / dashboards."""
+        d = self._decision_score(decision, ground_truth)
+        e = self._evidence_score(sources_checked, all_source_ids)
+        r = self._reasoning_score(claims_verified, all_claim_ids)
+        f = self._efficiency_score(step_count)
+        total = self.W_DECISION*d + self.W_EVIDENCE*e + self.W_REASONING*r + self.W_EFFICIENCY*f
+        return {
+            "decision_sub_score":    round(d, 4),
+            "evidence_sub_score":    round(e, 4),
+            "reasoning_sub_score":   round(r, 4),
+            "efficiency_sub_score":  round(f, 4),
+            "weights": {
+                "decision":    self.W_DECISION,
+                "evidence":    self.W_EVIDENCE,
+                "reasoning":   self.W_REASONING,
+                "efficiency":  self.W_EFFICIENCY,
+            },
+            "total": round(max(0.005, min(0.995, total)), 4),
+        }
+
+    # ------------------------------------------------------------------
+    # Sub-score methods (shared; can be overridden per difficulty)
+    # ------------------------------------------------------------------
+
+    def _decision_score(self, decision: str, ground_truth: str) -> float:
+        key = (decision.lower(), ground_truth.lower())
+        return _DECISION_CREDIT.get(key, 0.0)
+
+    def _evidence_score(
+        self, sources_checked: List[str], all_source_ids: List[str]
+    ) -> float:
+        if not all_source_ids:
+            return 1.0
+        frac = len(set(sources_checked)) / len(all_source_ids)
+        # Reward checking at least MIN_SOURCE_FRAC of available sources
+        if frac >= 1.0:
+            return 1.0
+        if frac >= self.MIN_SOURCE_FRAC:
+            # Scale linearly from MIN_SOURCE_FRAC→1 mapping to 0.5→1.0
+            slope = 0.5 / (1.0 - self.MIN_SOURCE_FRAC)
+            return 0.5 + slope * (frac - self.MIN_SOURCE_FRAC)
+        # Below minimum — partial credit only
+        return frac / self.MIN_SOURCE_FRAC * 0.5
+
+    def _reasoning_score(
+        self, claims_verified: List[str], all_claim_ids: List[str]
+    ) -> float:
+        if not all_claim_ids:
+            return 1.0
+        frac = len(set(claims_verified)) / len(all_claim_ids)
+        if frac >= self.MIN_CLAIM_FRAC:
+            return min(1.0, 0.6 + 0.4 * (frac - self.MIN_CLAIM_FRAC) / (1.0 - self.MIN_CLAIM_FRAC + 1e-9))
+        return frac / self.MIN_CLAIM_FRAC * 0.6
+
+    def _efficiency_score(self, step_count: int) -> float:
+        if step_count <= 0:
+            return 0.0
+        if step_count <= self.IDEAL_MAX_STEPS:
+            return 1.0
+        # Linear decay past ideal; floor at 0
+        overage = step_count - self.IDEAL_MAX_STEPS
+        return max(0.0, 1.0 - 0.1 * overage)
+
+    @property
+    @abstractmethod
+    def difficulty(self) -> str: ...
+
+
+# ---------------------------------------------------------------------------
+# Difficulty-specific graders
+# ---------------------------------------------------------------------------
+
+class EasyGrader(BaseGrader):
+    """
+    Easy scenarios have clear-cut answers.
+    Decision correctness dominates; efficiency is important.
+    """
+    difficulty = "easy"
+    W_DECISION   = 0.50
+    W_EVIDENCE   = 0.25
+    W_REASONING  = 0.15
+    W_EFFICIENCY = 0.10
+
+    IDEAL_MAX_STEPS = 8
+    MIN_SOURCE_FRAC = 0.33   # at least 1/3 of sources
+    MIN_CLAIM_FRAC  = 0.50
+
+
+class MediumGrader(BaseGrader):
+    """
+    Medium scenarios are partially true / misleading.
+    Evidence quality and reasoning depth matter more.
+    """
+    difficulty = "medium"
+    W_DECISION   = 0.35
+    W_EVIDENCE   = 0.35
+    W_REASONING  = 0.20
+    W_EFFICIENCY = 0.10
+
+    IDEAL_MAX_STEPS = 12
+    MIN_SOURCE_FRAC = 0.50
+    MIN_CLAIM_FRAC  = 0.75
+
+    def _evidence_score(
+        self, sources_checked: List[str], all_source_ids: List[str]
+    ) -> float:
+        """Medium: penalise lightly for checking < 50%, harshly for < 33%."""
+        if not all_source_ids:
+            return 1.0
+        frac = len(set(sources_checked)) / len(all_source_ids)
+        if frac >= 0.75:
+            return 1.0
+        if frac >= 0.50:
+            return 0.6 + 0.4 * (frac - 0.50) / 0.25
+        if frac >= 0.33:
+            return 0.3 + 0.3 * (frac - 0.33) / 0.17
+        return frac / 0.33 * 0.3
+
+
+class HardGrader(BaseGrader):
+    """
+    Hard scenarios have conflicting evidence and require nuanced reasoning.
+    All four dimensions count equally; efficiency is barely penalised.
+    """
+    difficulty = "hard"
+    W_DECISION   = 0.30
+    W_EVIDENCE   = 0.30
+    W_REASONING  = 0.30
+    W_EFFICIENCY = 0.10
+
+    IDEAL_MAX_STEPS = 18
+    MIN_SOURCE_FRAC = 0.60
+    MIN_CLAIM_FRAC  = 1.00   # all claims must be verified for full credit
+
+    def _decision_score(self, decision: str, ground_truth: str) -> float:
+        """Hard: never give 0 for a flag/remove swap — these are genuinely ambiguous."""
+        base = super()._decision_score(decision, ground_truth)
+        # Give 0.25 minimum for any non-trivially wrong answer
+        if base == 0.0 and decision in ("flag", "remove"):
+            return 0.25
+        return base
+
+    def _efficiency_score(self, step_count: int) -> float:
+        """Hard: efficiency barely matters — thorough exploration is rewarded."""
+        if step_count <= self.IDEAL_MAX_STEPS:
+            return 1.0
+        overage = step_count - self.IDEAL_MAX_STEPS
+        return max(0.0, 1.0 - 0.05 * overage)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+class GraderFactory:
+    _REGISTRY = {
+        "easy":   EasyGrader,
+        "medium": MediumGrader,
+        "hard":   HardGrader,
+    }
+
+    @classmethod
+    def get(cls, difficulty: str) -> BaseGrader:
+        key = difficulty.lower().strip()
+        if key not in cls._REGISTRY:
+            raise ValueError(
+                f"Unknown difficulty '{difficulty}'. "
+                f"Valid options: {list(cls._REGISTRY.keys())}"
+            )
+        return cls._REGISTRY[key]()
+
+    @classmethod
+    def register(cls, difficulty: str, grader_cls: type) -> None:
+        """Allow enterprise teams to plug in custom graders."""
+        cls._REGISTRY[difficulty.lower()] = grader_cls

tasks/hard/scenarios.json

@@ -0,0 +1,481 @@
+[
+  {
+    "id": "hard_001",
+    "difficulty": "hard",
+    "topic": "geopolitics",
+    "tags": ["ukraine", "nato", "war", "conflict"],
+    "content": "NATO provoked Russia into invading Ukraine by promising Ukraine membership, violating agreements made at the end of the Cold War. Russia's invasion was a defensive response to Western aggression.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "NATO promised Russia that Ukraine would never become a member",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.60
+      },
+      {
+        "id": "claim_002",
+        "text": "Russia's invasion was a defensive response to NATO expansion",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.65
+      },
+      {
+        "id": "claim_003",
+        "text": "NATO violated formal written agreements with Russia",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.75
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "National Security Archive: What NATO leaders said about expansion in 1990",
+        "text": "Declassified documents show Western leaders gave verbal assurances in 1990 about NATO not expanding eastward, but these were never codified in a binding treaty. The NATO-Russia Founding Act of 1997 does not prohibit membership for former Soviet states.",
+        "url": "https://nsarchive.gwu.edu/briefing-book/russia-programs/2017-12-12/nato-expansion-what-gorbachev-heard",
+        "stance": "neutral",
+        "reliability": 0.92,
+        "source_type": "academic",
+        "verification_weight": 0.92
+      },
+      {
+        "id": "src_002",
+        "title": "Brookings Institution: Did the West break its promise to Russia?",
+        "text": "Analysis finds Western leaders did give informal assurances to Gorbachev in 1990, but these were oral statements not reflected in any signed treaty. NATO membership is an open-door policy codified in the Washington Treaty. No binding promise was broken.",
+        "url": "https://www.brookings.edu/blog/order-from-chaos/2022/02/28/did-the-west-break-its-promise-to-moscow-not-to-expand-nato/",
+        "stance": "contradicting",
+        "reliability": 0.88,
+        "source_type": "academic",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_003",
+        "title": "Mearsheimer: Why the West is principally responsible for the Ukraine crisis",
+        "text": "Offensive realism scholar John Mearsheimer argues that NATO expansion posed an existential threat in Russia's strategic calculus, making conflict inevitable. He contends the West provoked the crisis through a policy of integrating Ukraine.",
+        "url": "https://www.foreignaffairs.com/ukraine/why-west-principally-responsible-ukraine-crisis",
+        "stance": "supporting",
+        "reliability": 0.80,
+        "source_type": "academic",
+        "verification_weight": 0.75
+      },
+      {
+        "id": "src_004",
+        "title": "UN General Assembly Resolution ES-11/1: Condemning Russia's aggression",
+        "text": "141 UN member states voted to condemn Russia's invasion of Ukraine as a violation of the UN Charter. The resolution demands Russia's immediate withdrawal and rejects the framing of the invasion as defensive.",
+        "url": "https://undocs.org/en/A/RES/ES-11/1",
+        "stance": "contradicting",
+        "reliability": 0.96,
+        "source_type": "official",
+        "verification_weight": 0.95
+      },
+      {
+        "id": "src_005",
+        "title": "Carnegie Endowment: Roots of the Ukraine war — multiple causes",
+        "text": "Carnegie analysis identifies multiple contributing factors to the conflict including NATO expansion, Crimea 2014, Donbas conflict, and Russian domestic politics. Framing the invasion as purely defensive ignores Russia's maximalist territorial ambitions.",
+        "url": "https://carnegieendowment.org/2022/06/13/roots-of-ukraine-war-keeping-country-together-pub-87171",
+        "stance": "contradicting",
+        "reliability": 0.87,
+        "source_type": "academic",
+        "verification_weight": 0.87
+      },
+      {
+        "id": "src_006",
+        "title": "RT (Russia Today): Russia's justified response to NATO aggression",
+        "text": "Russian state media presents the invasion as a special military operation to de-Nazify Ukraine and protect Russian speakers, and a necessary response to years of NATO encirclement.",
+        "url": "https://www.rt.com/russia/ukraine-nato-expansion/",
+        "stance": "supporting",
+        "reliability": 0.15,
+        "source_type": "news",
+        "verification_weight": 0.1
+      },
+      {
+        "id": "src_007",
+        "title": "Budapest Memorandum 1994: What was actually signed",
+        "text": "The Budapest Memorandum gave Ukraine security assurances (not guarantees) in exchange for giving up nuclear weapons. Russia, the US, and UK signed it. Russia's violation of Ukrainian sovereignty directly contravenes its own commitments in this document.",
+        "url": "https://www.un.org/en/sc/repertoire/96-99/Chapter%208/EUROPE/96-99_8-2-24-UKRAINE.pdf",
+        "stance": "contradicting",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 1.0
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "Highly contested geopolitical narrative. Claim 1 has partial basis (informal assurances existed). Claims 2-3 are mostly false (no binding agreements broken, invasion not legally defensive). Complex enough to flag rather than remove — the debate has legitimate academic dimensions."
+  },
+  {
+    "id": "hard_002",
+    "difficulty": "hard",
+    "topic": "public_health_policy",
+    "tags": ["lockdown", "covid", "policy", "deaths"],
+    "content": "COVID lockdowns killed more people than COVID itself. The economic devastation, mental health crisis, and delayed medical treatments caused excess deaths exceeding the pandemic toll.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Lockdowns caused excess deaths exceeding COVID's direct death toll",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.65
+      },
+      {
+        "id": "claim_002",
+        "text": "Lockdowns caused significant excess mortality from delayed treatments and mental health",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.72
+      },
+      {
+        "id": "claim_003",
+        "text": "Lockdowns caused economic devastation with major mortality consequences",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.60
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "The Lancet: Excess mortality during COVID-19 pandemic — global estimates",
+        "text": "Lancet analysis estimated 18.2 million excess deaths attributable directly or indirectly to COVID-19 in 2020-2021. The vast majority were directly caused by SARS-CoV-2, not lockdown policies.",
+        "url": "https://www.thelancet.com/journals/lancet/article/PIIS0140-6736(21)02796-3/fulltext",
+        "stance": "contradicting",
+        "reliability": 0.97,
+        "source_type": "academic",
+        "verification_weight": 0.97
+      },
+      {
+        "id": "src_002",
+        "title": "Johns Hopkins Carey: A literature review and meta-analysis of the effects of lockdowns",
+        "text": "A meta-analysis found lockdowns had a modest direct effect on COVID mortality (reducing it by approximately 3.2%). The study argued costs may have outweighed benefits but did not claim lockdowns killed more than the disease.",
+        "url": "https://sites.krieger.jhu.edu/iae/files/2022/01/A-Literature-Review-and-Meta-Analysis-of-the-Effects-of-Lockdowns-on-COVID-19-Mortality.pdf",
+        "stance": "neutral",
+        "reliability": 0.84,
+        "source_type": "academic",
+        "verification_weight": 0.82
+      },
+      {
+        "id": "src_003",
+        "title": "BMJ: Cancer screening dropped 89% during first lockdown in UK",
+        "text": "BMJ analysis found cancer screening attendance collapsed during lockdowns, with modelling suggesting 3,500 additional cancer deaths in England expected due to diagnostic delays.",
+        "url": "https://www.bmj.com/content/372/bmj.n421",
+        "stance": "supporting",
+        "reliability": 0.94,
+        "source_type": "academic",
+        "verification_weight": 0.93
+      },
+      {
+        "id": "src_004",
+        "title": "WHO: Mental health crisis during pandemic",
+        "text": "WHO reported a 25% increase in anxiety and depression globally during the first year of COVID-19. Isolation, economic stress, and grief contributed, though attributing mortality to lockdowns specifically versus pandemic stress broadly is methodologically difficult.",
+        "url": "https://www.who.int/news/item/02-03-2022-covid-19-pandemic-triggers-25-increase-in-prevalence-of-anxiety-and-depression-worldwide",
+        "stance": "neutral",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 0.95
+      },
+      {
+        "id": "src_005",
+        "title": "NBER: Economic costs of the pandemic — lockdowns vs disease",
+        "text": "National Bureau of Economic Research analysis found voluntary social distancing and fear of infection were larger drivers of economic contraction than government mandates. Disentangling lockdown effects from pandemic effects is methodologically challenging.",
+        "url": "https://www.nber.org/papers/w27431",
+        "stance": "neutral",
+        "reliability": 0.91,
+        "source_type": "academic",
+        "verification_weight": 0.91
+      },
+      {
+        "id": "src_006",
+        "title": "Great Barrington Declaration — lockdowns cause more harm than good",
+        "text": "Signed by epidemiologists and public health scientists, the declaration argued focused protection for vulnerable groups while allowing low-risk groups to live normally was preferable to blanket lockdowns, citing mental health, economic and healthcare harms.",
+        "url": "https://gbdeclaration.org/",
+        "stance": "supporting",
+        "reliability": 0.72,
+        "source_type": "academic",
+        "verification_weight": 0.65
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "The strong claim (lockdowns killed MORE than COVID) is contradicted by excess mortality data. But the underlying concerns about lockdown harms are legitimate and backed by peer-reviewed evidence. Flag as misleading in its absolute framing."
+  },
+  {
+    "id": "hard_003",
+    "difficulty": "hard",
+    "topic": "financial",
+    "tags": ["cryptocurrency", "sec", "regulation", "fraud"],
+    "content": "The SEC's crackdown on crypto is not about investor protection — it's coordinated suppression of decentralised finance by traditional banking interests who are terrified of losing control of the financial system.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "SEC crypto enforcement is primarily driven by banking industry influence",
+        "ground_truth_status": "unknown",
+        "ground_truth_confidence": 0.50
+      },
+      {
+        "id": "claim_002",
+        "text": "SEC crypto actions are not genuinely aimed at investor protection",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.65
+      },
+      {
+        "id": "claim_003",
+        "text": "Traditional banking interests are coordinating to suppress decentralised finance",
+        "ground_truth_status": "unknown",
+        "ground_truth_confidence": 0.45
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "SEC v. Ripple, SEC v. Coinbase, SEC v. Binance — legal filings",
+        "text": "SEC enforcement actions against major crypto firms allege specific securities law violations, fraud, and unregistered securities offerings. Court filings cite concrete investor harm rather than systemic suppression of crypto.",
+        "url": "https://www.sec.gov/litigation/litreleases/2023/lr25680.htm",
+        "stance": "contradicting",
+        "reliability": 0.96,
+        "source_type": "official",
+        "verification_weight": 0.96
+      },
+      {
+        "id": "src_002",
+        "title": "Revolving door: Former financial regulators at crypto and banking firms",
+        "text": "A ProPublica investigation found significant movement of personnel between SEC leadership, Goldman Sachs, JP Morgan, and crypto firms including Coinbase and FTX, raising questions about regulatory capture.",
+        "url": "https://www.propublica.org/article/revolving-door-sec-fintech",
+        "stance": "supporting",
+        "reliability": 0.82,
+        "source_type": "news",
+        "verification_weight": 0.78
+      },
+      {
+        "id": "src_003",
+        "title": "Congressional Research Service: SEC authority over digital assets",
+        "text": "CRS analysis finds the SEC's application of securities law to crypto is legally contested but not inherently illegitimate. Courts have ruled against the SEC in some cases (XRP) and in its favour in others.",
+        "url": "https://crsreports.congress.gov/product/pdf/R/R47283",
+        "stance": "neutral",
+        "reliability": 0.94,
+        "source_type": "official",
+        "verification_weight": 0.94
+      },
+      {
+        "id": "src_004",
+        "title": "FTX collapse: Investor losses from inadequate crypto regulation",
+        "text": "The collapse of FTX resulted in an estimated $8 billion of customer losses. Post-collapse investigations found fraud, misuse of customer funds, and the absence of basic financial controls that regulated firms must maintain.",
+        "url": "https://www.wsj.com/articles/ftx-collapse-what-happened-11668093732",
+        "stance": "contradicting",
+        "reliability": 0.89,
+        "source_type": "news",
+        "verification_weight": 0.89
+      },
+      {
+        "id": "src_005",
+        "title": "American Bankers Association lobbying disclosures on crypto regulation",
+        "text": "Lobbying disclosures show the ABA and JPMorgan spent millions lobbying for crypto regulation, arguing both for stricter rules on crypto competitors and against CBDC development that could threaten deposit bases.",
+        "url": "https://lda.senate.gov/system/public/",
+        "stance": "supporting",
+        "reliability": 0.85,
+        "source_type": "official",
+        "verification_weight": 0.82
+      },
+      {
+        "id": "src_006",
+        "title": "Crypto critic: Gary Gensler worked at Goldman Sachs",
+        "text": "Commentators note SEC Chair Gary Gensler spent years at Goldman Sachs before government service. While he taught blockchain at MIT, his enforcement approach is seen by some as selectively applied.",
+        "url": "https://cryptoskeptic.invalid/gensler-goldman",
+        "stance": "supporting",
+        "reliability": 0.20,
+        "source_type": "blog",
+        "verification_weight": 0.15
+      },
+      {
+        "id": "src_007",
+        "title": "BIS: Regulatory challenges of crypto assets — official cross-border analysis",
+        "text": "Bank for International Settlements analysis argues crypto requires regulation for financial stability and investor protection, and notes significant regulatory arbitrage risks if jurisdictions fail to coordinate. This is not characterised as suppression.",
+        "url": "https://www.bis.org/publ/arpdf/ar2022e3.htm",
+        "stance": "contradicting",
+        "reliability": 0.95,
+        "source_type": "official",
+        "verification_weight": 0.95
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "The conspiracy framing (coordinated suppression) is unsupported, but legitimate regulatory capture concerns and industry lobbying are documented. Investor harm from lax crypto regulation is also well-evidenced. The content oversimplifies a genuinely complex regulatory debate — flag."
+  },
+  {
+    "id": "hard_004",
+    "difficulty": "hard",
+    "topic": "ai_safety",
+    "tags": ["ai", "existential_risk", "agi", "safety"],
+    "content": "Leading AI researchers have signed open letters warning that AI poses an extinction-level risk to humanity. We should immediately halt all AI development before it is too late.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Leading AI researchers have warned AI poses extinction-level risk",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.75
+      },
+      {
+        "id": "claim_002",
+        "text": "AI development should be immediately halted to prevent extinction",
+        "ground_truth_status": "unknown",
+        "ground_truth_confidence": 0.50
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "Center for AI Safety: Statement on AI risk signed by Hinton, Bengio, Altman",
+        "text": "A statement signed by prominent AI researchers including Geoffrey Hinton, Yoshua Bengio, and Sam Altman states: 'Mitigating the risk of extinction from AI should be a global priority alongside other societal-scale risks.' Over 350 AI researchers signed.",
+        "url": "https://www.safe.ai/statement-on-ai-risk",
+        "stance": "supporting",
+        "reliability": 0.90,
+        "source_type": "academic",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_002",
+        "title": "FLI Open Letter: Pause Giant AI Experiments",
+        "text": "The Future of Life Institute letter (signed by Elon Musk, Steve Wozniak, and others) called for a 6-month pause on AI training above GPT-4 capability level. Not all signatories believed extinction was imminent — concerns ranged from misuse to existential risk.",
+        "url": "https://futureoflife.org/open-letter/pause-giant-ai-experiments/",
+        "stance": "supporting",
+        "reliability": 0.83,
+        "source_type": "official",
+        "verification_weight": 0.80
+      },
+      {
+        "id": "src_003",
+        "title": "Andrew Ng, Yann LeCun: AI doomsday claims are overblown",
+        "text": "Several prominent AI researchers including Andrew Ng and Yann LeCun (Meta) have strongly criticised existential risk framings, arguing current AI systems are far from the capabilities required for existential threat and that halting development would harm beneficial applications.",
+        "url": "https://www.wired.com/story/openai-microsoft-google-ai-safety-drama/",
+        "stance": "contradicting",
+        "reliability": 0.85,
+        "source_type": "news",
+        "verification_weight": 0.83
+      },
+      {
+        "id": "src_004",
+        "title": "UK AI Safety Institute: State of AI safety research 2023",
+        "text": "The UK's AI Safety Institute notes that risks from AI are serious and warrant dedicated research, but that expert opinion on probability and timeline of existential risk is genuinely divided. Immediate halt is not the consensus recommendation.",
+        "url": "https://www.gov.uk/government/publications/ai-safety-institute-overview",
+        "stance": "neutral",
+        "reliability": 0.93,
+        "source_type": "official",
+        "verification_weight": 0.93
+      },
+      {
+        "id": "src_005",
+        "title": "RAND: Do AI risks justify a halt? Policy analysis",
+        "text": "RAND analysis finds halting AI development unilaterally is likely infeasible and would cede advantage to less safety-conscious actors. The report recommends international safety coordination rather than unilateral pause.",
+        "url": "https://www.rand.org/pubs/research_reports/RRA2680-1.html",
+        "stance": "contradicting",
+        "reliability": 0.88,
+        "source_type": "official",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_006",
+        "title": "Geoffrey Hinton resignation interview: I genuinely worry about AI risk",
+        "text": "Geoffrey Hinton, upon leaving Google, stated he regrets his life's work and is genuinely worried AI could become a major risk to humanity, citing potential for misuse and long-term control problems.",
+        "url": "https://www.nytimes.com/2023/05/01/technology/ai-google-chatbot-engineer-quits-hinton.html",
+        "stance": "supporting",
+        "reliability": 0.88,
+        "source_type": "news",
+        "verification_weight": 0.87
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "First claim is supported but the 'extinction-level' framing overstates the open letter language (which says 'should be a priority', not 'is imminent'). The halt recommendation is a contested policy position, not scientific consensus. Flag for misleading framing of a real debate."
+  },
+  {
+    "id": "hard_005",
+    "difficulty": "hard",
+    "topic": "historical_revisionism",
+    "tags": ["history", "colonialism", "reparations"],
+    "content": "British colonialism was actually net beneficial for India — the railways, legal system, and education infrastructure built by the British gave India the foundations for becoming a modern democracy.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "British colonialism built railways and infrastructure in India",
+        "ground_truth_status": "true",
+        "ground_truth_confidence": 0.95
+      },
+      {
+        "id": "claim_002",
+        "text": "British colonialism was net beneficial for India",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.65
+      },
+      {
+        "id": "claim_003",
+        "text": "British rule gave India the foundations for becoming a modern democracy",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.55
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "Utsa Patnaik: Britain drained $45 trillion from India between 1765 and 1938",
+        "text": "Columbia University-published research by economist Utsa Patnaik estimates Britain extracted approximately $45 trillion in current prices from India through taxation, trade manipulation, and forced labour over 173 years of colonial rule.",
+        "url": "https://www.columbia.edu/~lmb4/patnaik.pdf",
+        "stance": "contradicting",
+        "reliability": 0.83,
+        "source_type": "academic",
+        "verification_weight": 0.80
+      },
+      {
+        "id": "src_002",
+        "title": "Shashi Tharoor: Inglorious Empire — what the British did to India",
+        "text": "Former UN Under-Secretary General and Indian MP Shashi Tharoor argues that British-built railways were designed for resource extraction and troop movement, not Indian development. India's share of global GDP fell from 23% to 4% under British rule.",
+        "url": "https://www.theguardian.com/world/2017/mar/08/british-empire-india-shashi-tharoor",
+        "stance": "contradicting",
+        "reliability": 0.80,
+        "source_type": "news",
+        "verification_weight": 0.78
+      },
+      {
+        "id": "src_003",
+        "title": "Niall Ferguson: Colonialism had positive institutional legacies",
+        "text": "Historian Niall Ferguson argues British colonialism transferred institutional knowledge — common law, property rights, parliamentary democracy — that provided governance foundations still visible in India, Singapore, and Australia.",
+        "url": "https://www.nytimes.com/2003/04/27/books/chapters/empire.html",
+        "stance": "supporting",
+        "reliability": 0.75,
+        "source_type": "academic",
+        "verification_weight": 0.70
+      },
+      {
+        "id": "src_004",
+        "title": "Economic History Review: Did colonialism hold back India's industrialisation?",
+        "text": "Peer-reviewed economic history finds India's textile industry was deliberately suppressed by British tariff policy to protect Lancashire mills. The evidence for net economic benefit is contested; most historians find colonial extraction outweighed infrastructure investment.",
+        "url": "https://onlinelibrary.wiley.com/journal/14680289",
+        "stance": "contradicting",
+        "reliability": 0.88,
+        "source_type": "academic",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_005",
+        "title": "Bengal Famine 1943: Churchill's role in wartime food policy",
+        "text": "Historical records show the 1943 Bengal Famine killed 2-3 million people. Churchill's war cabinet rejected food import requests and diverted food supplies from Bengal. Colonial governance is directly implicated in the death toll.",
+        "url": "https://www.theguardian.com/world/2019/sep/17/winston-churchill-and-the-making-of-the-bengal-famine",
+        "stance": "contradicting",
+        "reliability": 0.85,
+        "source_type": "news",
+        "verification_weight": 0.85
+      },
+      {
+        "id": "src_006",
+        "title": "YouGov poll: 44% of British people proud of the Empire",
+        "text": "A YouGov poll found significant British public support for Empire legacy, reflecting a popular revisionist view of colonialism as a civilising mission, though historians note this contradicts dominant scholarly consensus.",
+        "url": "https://yougov.co.uk/topics/politics/articles-reports/2020/03/11/how-unique-are-british-attitudes-empire",
+        "stance": "supporting",
+        "reliability": 0.75,
+        "source_type": "news",
+        "verification_weight": 0.65
+      },
+      {
+        "id": "src_007",
+        "title": "Harvard Growth Lab: Does colonial legacy explain development outcomes?",
+        "text": "Comparative analysis finds countries with British common law traditions have some governance advantages, but this does not imply net colonial benefit — the counterfactual of independent development is impossible to measure and likely favourable given India's pre-colonial economic position.",
+        "url": "https://growthlab.hks.harvard.edu/publications/does-colonial-legacy-explain-development-outcomes",
+        "stance": "neutral",
+        "reliability": 0.89,
+        "source_type": "academic",
+        "verification_weight": 0.89
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "Claim 1 is factually true. Claim 2 is contested — most academic consensus finds net harm, but the debate has legitimate scholarly dimensions. Claim 3 is partially true (institutional transfer occurred) but incomplete. Flag as revisionist framing rather than remove — historical interpretation is legitimately debated."
+  }
+]

tasks/medium/scenarios.json

@@ -0,0 +1,387 @@
+[
+  {
+    "id": "medium_001",
+    "difficulty": "medium",
+    "topic": "nutrition_science",
+    "tags": ["diet", "sugar", "health"],
+    "content": "New study reveals sugar is more addictive than cocaine. Researchers at Princeton found that sugar consumption activates the same brain pathways as hard drugs, confirming what health experts have long suspected.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Sugar is more addictive than cocaine",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.70
+      },
+      {
+        "id": "claim_002",
+        "text": "Princeton researchers confirmed sugar activates the same brain pathways as hard drugs",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.65
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "Neuroscience & Biobehavioral Reviews: Sugar and addiction — a critical review",
+        "text": "Animal studies show sugar can produce dopamine release and some withdrawal-like symptoms, but direct comparisons to cocaine addiction in humans are not scientifically established. The Princeton rat studies showed binge-like eating behaviour, not addiction equivalent to hard drugs.",
+        "url": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2235907/",
+        "stance": "neutral",
+        "reliability": 0.90,
+        "source_type": "academic",
+        "verification_weight": 0.9
+      },
+      {
+        "id": "src_002",
+        "title": "Princeton Press Release: Sugar bingeing in rats",
+        "text": "Dr Hoebel's Princeton lab did find that rats with intermittent access to sugar showed dopamine surges and withdrawal-like behaviours. The phrase 'more addictive than cocaine' was not in the original paper — it was a media extrapolation.",
+        "url": "https://www.princeton.edu/news/2008/12/10/sugar-can-be-addictive-princeton-scientist-says",
+        "stance": "neutral",
+        "reliability": 0.93,
+        "source_type": "official",
+        "verification_weight": 0.95
+      },
+      {
+        "id": "src_003",
+        "title": "Harvard Health: Is sugar addictive?",
+        "text": "While sugar does trigger reward pathways, calling it 'more addictive than cocaine' overstates current evidence. The comparison originated from rat studies and does not directly translate to human addiction medicine.",
+        "url": "https://www.health.harvard.edu/blog/is-sugar-addictive-2019052916627",
+        "stance": "contradicting",
+        "reliability": 0.91,
+        "source_type": "official",
+        "verification_weight": 0.9
+      },
+      {
+        "id": "src_004",
+        "title": "Health magazine: Sugar is the new cocaine",
+        "text": "Multiple health experts have linked excessive sugar consumption to compulsive eating behaviours similar to substance addiction, with some calling for sugar to be regulated like alcohol.",
+        "url": "https://health-magazine.example/sugar-addiction",
+        "stance": "supporting",
+        "reliability": 0.55,
+        "source_type": "news",
+        "verification_weight": 0.5
+      },
+      {
+        "id": "src_005",
+        "title": "Frontiers in Psychiatry: Behavioural vs substance addiction — the sugar debate",
+        "text": "The scientific community is divided. While some researchers classify binge eating of sugar-laden foods as a behavioural addiction with neurological overlap with drug use, direct equivalence to cocaine addiction is not established.",
+        "url": "https://www.frontiersin.org/articles/10.3389/fpsyt.2018.00080/full",
+        "stance": "neutral",
+        "reliability": 0.88,
+        "source_type": "academic",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_006",
+        "title": "Viral social post: Sugar more addictive than cocaine confirmed",
+        "text": "Mainstream media is hiding how addictive sugar is. Leaked studies show it's worse than heroin. Big Sugar controls the narrative.",
+        "url": "https://social.example/sugar-conspiracy",
+        "stance": "supporting",
+        "reliability": 0.05,
+        "source_type": "social",
+        "verification_weight": 0.05
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "The core science has a basis (dopamine activation) but the 'more addictive than cocaine' claim is a significant overstatement. Mixed evidence — flag as misleading rather than remove."
+  },
+  {
+    "id": "medium_002",
+    "difficulty": "medium",
+    "topic": "economic_statistics",
+    "tags": ["unemployment", "economy", "statistics"],
+    "content": "The government's unemployment figures are a lie. Real unemployment is over 20% when you count all the people who gave up looking for work.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Official unemployment figures exclude discouraged workers",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.80
+      },
+      {
+        "id": "claim_002",
+        "text": "Real unemployment is over 20%",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.75
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "Bureau of Labor Statistics: How unemployment is measured (U-3 vs U-6)",
+        "text": "The BLS publishes multiple unemployment measures. U-3 (headline) excludes marginally attached workers. U-6 (broadest) includes discouraged workers and those working part-time for economic reasons. U-6 is typically 1.5-2x higher than U-3 but has historically remained below 20% except during peak recessions.",
+        "url": "https://www.bls.gov/cps/cps_htgm.htm",
+        "stance": "neutral",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "Federal Reserve Economic Data: U-6 unemployment rate historical",
+        "text": "U-6 unemployment peaked at 17.2% during the 2008-09 recession and briefly hit 22.9% in April 2020 during COVID lockdowns. Outside those events it has typically ranged from 7-15%.",
+        "url": "https://fred.stlouisfed.org/series/U6RATE",
+        "stance": "contradicting",
+        "reliability": 0.98,
+        "source_type": "official",
+        "verification_weight": 0.98
+      },
+      {
+        "id": "src_003",
+        "title": "Economic Policy Institute: Shadow unemployment analysis",
+        "text": "Some economists argue that U-6 still understates labour market slack by excluding workers who want work but haven't searched recently. However, most estimates place true slack well below 20% in normal economic conditions.",
+        "url": "https://www.epi.org/publication/unemployment-understated/",
+        "stance": "supporting",
+        "reliability": 0.82,
+        "source_type": "academic",
+        "verification_weight": 0.8
+      },
+      {
+        "id": "src_004",
+        "title": "Political blog: The 20%+ unemployment truth",
+        "text": "Alternative calculations by independent economists suggest real unemployment has exceeded 20% for years. The government manipulates the numbers.",
+        "url": "https://economy-truth.invalid/real-unemployment",
+        "stance": "supporting",
+        "reliability": 0.15,
+        "source_type": "blog",
+        "verification_weight": 0.1
+      },
+      {
+        "id": "src_005",
+        "title": "IMF: US Labour Market Assessment 2023",
+        "text": "The IMF's assessment of US labour markets finds the BLS methodology broadly sound and comparable to international standards. The broadest unemployment measures remain well below 20% in non-crisis periods.",
+        "url": "https://www.imf.org/en/News/Articles/2023/07/24/us-article-iv-2023",
+        "stance": "contradicting",
+        "reliability": 0.95,
+        "source_type": "official",
+        "verification_weight": 0.95
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "First claim (exclusion of discouraged workers) is technically correct. Second claim (20%+ always) is false. Mixed truth warrants flagging as misleading."
+  },
+  {
+    "id": "medium_003",
+    "difficulty": "medium",
+    "topic": "technology",
+    "tags": ["ai", "job_displacement", "automation"],
+    "content": "AI will eliminate 85 million jobs by 2025 according to the World Economic Forum, causing the worst unemployment crisis in human history.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "WEF predicted AI will eliminate 85 million jobs by 2025",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.75
+      },
+      {
+        "id": "claim_002",
+        "text": "This will cause the worst unemployment crisis in human history",
+        "ground_truth_status": "false",
+        "ground_truth_confidence": 0.80
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "WEF Future of Jobs Report 2020: The actual finding",
+        "text": "The WEF's 2020 Future of Jobs Report projected that automation may displace 85 million jobs by 2025, but also create 97 million new roles — a net positive of 12 million jobs. The report was about transformation, not mass unemployment.",
+        "url": "https://www.weforum.org/reports/the-future-of-jobs-report-2020",
+        "stance": "neutral",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "MIT Work of the Future: Technology and jobs — nuanced picture",
+        "text": "Research from MIT's Work of the Future task force suggests automation creates worker displacement but also new job categories. Historical evidence shows technology creates more jobs than it destroys over the medium term.",
+        "url": "https://workofthefuture.mit.edu/",
+        "stance": "contradicting",
+        "reliability": 0.93,
+        "source_type": "academic",
+        "verification_weight": 0.93
+      },
+      {
+        "id": "src_003",
+        "title": "McKinsey Global Institute: Jobs lost, jobs gained",
+        "text": "McKinsey estimates 400-800 million people globally could be displaced by automation by 2030, but predicts most will find new employment. Net job growth historically follows technological revolutions.",
+        "url": "https://www.mckinsey.com/featured-insights/future-of-work/jobs-lost-jobs-gained-what-the-future-of-work-will-mean-for-jobs-skills-and-wages",
+        "stance": "neutral",
+        "reliability": 0.88,
+        "source_type": "academic",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_004",
+        "title": "Viral article: AI will destroy all jobs",
+        "text": "WEF confirms 85 million jobs gone by 2025. Economists warn this is just the beginning. The end of human employment is near.",
+        "url": "https://doomscroll.invalid/ai-jobs-apocalypse",
+        "stance": "supporting",
+        "reliability": 0.10,
+        "source_type": "blog",
+        "verification_weight": 0.1
+      },
+      {
+        "id": "src_005",
+        "title": "OECD: Employment Outlook — Automation and the future of work",
+        "text": "OECD research indicates approximately 14% of jobs face high automation risk, while 32% face significant changes. This does not constitute a worst-ever unemployment crisis historically speaking.",
+        "url": "https://www.oecd.org/employment/Employment-Outlook-2019-Highlight-EN.pdf",
+        "stance": "contradicting",
+        "reliability": 0.95,
+        "source_type": "official",
+        "verification_weight": 0.95
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "First claim misrepresents WEF (omits the 97M new jobs). Second claim is false (not worst crisis). Selective citation of a real report — flag as misleading."
+  },
+  {
+    "id": "medium_004",
+    "difficulty": "medium",
+    "topic": "pharmaceutical",
+    "tags": ["medication", "opioids", "addiction"],
+    "content": "Pharmaceutical companies knew OxyContin was highly addictive before launching it, and deliberately misled doctors about addiction risks.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Pharmaceutical companies knew OxyContin was highly addictive before launch",
+        "ground_truth_status": "true",
+        "ground_truth_confidence": 0.92
+      },
+      {
+        "id": "claim_002",
+        "text": "They deliberately misled doctors about addiction risks",
+        "ground_truth_status": "true",
+        "ground_truth_confidence": 0.88
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "DOJ: Purdue Pharma guilty plea for misleading marketing",
+        "text": "Purdue Pharma in 2020 pleaded guilty to federal charges of misleading doctors and the public about OxyContin's addiction risks, including making false statements to the DEA. The company admitted deceptive marketing practices.",
+        "url": "https://www.justice.gov/opa/pr/justice-department-announces-global-resolution-criminal-and-civil-investigations-opioid",
+        "stance": "supporting",
+        "reliability": 0.99,
+        "source_type": "official",
+        "verification_weight": 1.0
+      },
+      {
+        "id": "src_002",
+        "title": "New England Journal of Medicine: The OxyContin crisis — documented deception",
+        "text": "Peer-reviewed investigation found Purdue Pharma's marketing downplayed addiction risk. Internal documents showed awareness of abuse potential that was not disclosed to prescribers.",
+        "url": "https://www.nejm.org/doi/full/10.1056/NEJMsa1706290",
+        "stance": "supporting",
+        "reliability": 0.97,
+        "source_type": "academic",
+        "verification_weight": 0.97
+      },
+      {
+        "id": "src_003",
+        "title": "Pharma industry response: OxyContin was approved by FDA",
+        "text": "Industry representatives point out that OxyContin received FDA approval and that prescribing guidelines were followed. Some critics argue the FDA also bears responsibility for the approval process.",
+        "url": "https://phrma.example/oxycontin-response",
+        "stance": "contradicting",
+        "reliability": 0.40,
+        "source_type": "official",
+        "verification_weight": 0.3
+      },
+      {
+        "id": "src_004",
+        "title": "Reuters: Massachusetts AG lawsuit — Sackler family knew of addiction risks in 1996",
+        "text": "Court documents show Purdue Pharma executives had internal assessments of OxyContin's addiction potential as early as 1996, a year before the drug's launch.",
+        "url": "https://www.reuters.com/article/us-purdue-pharma-lawsuit",
+        "stance": "supporting",
+        "reliability": 0.91,
+        "source_type": "news",
+        "verification_weight": 0.92
+      },
+      {
+        "id": "src_005",
+        "title": "Congressional Investigation: Purdue Pharma and opioid epidemic",
+        "text": "A bipartisan congressional investigation found systemic deception in Purdue Pharma's marketing, including providing false information to state medical boards to increase OxyContin prescriptions.",
+        "url": "https://www.congress.gov/committee-report/116th-congress/senate-report/69",
+        "stance": "supporting",
+        "reliability": 0.97,
+        "source_type": "official",
+        "verification_weight": 0.97
+      }
+    ],
+    "ground_truth": "allow",
+    "explanation_hint": "Both claims are well-documented facts backed by DOJ guilty plea, Congressional investigation, and peer-reviewed evidence. Accurate journalism — allow."
+  },
+  {
+    "id": "medium_005",
+    "difficulty": "medium",
+    "topic": "social_media",
+    "tags": ["facebook", "teen_mental_health", "social_media"],
+    "content": "Facebook's own internal research proves Instagram is destroying teenagers' mental health and the company hid this evidence from the public.",
+    "claims": [
+      {
+        "id": "claim_001",
+        "text": "Facebook's internal research showed Instagram harms teenagers' mental health",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.80
+      },
+      {
+        "id": "claim_002",
+        "text": "Facebook deliberately hid this evidence from the public",
+        "ground_truth_status": "partially_true",
+        "ground_truth_confidence": 0.70
+      }
+    ],
+    "sources": [
+      {
+        "id": "src_001",
+        "title": "WSJ: Facebook Knows Instagram Is Toxic for Teen Girls, Company Documents Show",
+        "text": "Internal Facebook presentations from 2019 and 2020 showed Instagram worsened body image issues in one-third of teen girls surveyed. The company was aware of negative mental health correlations.",
+        "url": "https://www.wsj.com/articles/facebook-knows-instagram-is-toxic-for-teen-girls-company-documents-show-11631620739",
+        "stance": "supporting",
+        "reliability": 0.88,
+        "source_type": "news",
+        "verification_weight": 0.88
+      },
+      {
+        "id": "src_002",
+        "title": "Meta's response to WSJ investigation",
+        "text": "Meta stated the WSJ characterisation misrepresented their research, which they said showed mixed results. They argued internal research is preliminary and does not establish causation.",
+        "url": "https://about.fb.com/news/2021/09/research-teen-girls-and-instagram/",
+        "stance": "contradicting",
+        "reliability": 0.70,
+        "source_type": "official",
+        "verification_weight": 0.6
+      },
+      {
+        "id": "src_003",
+        "title": "Senate Commerce Committee: Internal Facebook documents on youth harm",
+        "text": "A Senate subcommittee review of internal Facebook documents confirmed the company conducted research linking Instagram to mental health issues in teens and did not make this research publicly available.",
+        "url": "https://www.commerce.senate.gov/2021/9/blumenthal-blackburn-investigate-facebook-s-research-on-children-and-instagram",
+        "stance": "supporting",
+        "reliability": 0.94,
+        "source_type": "official",
+        "verification_weight": 0.94
+      },
+      {
+        "id": "src_004",
+        "title": "Journal of Youth and Adolescence: Systematic review of social media and mental health",
+        "text": "A systematic review found small to moderate associations between social media use and depression/anxiety in adolescents, but noted causation vs correlation is difficult to establish. Effects vary significantly by usage patterns.",
+        "url": "https://link.springer.com/journal/10964",
+        "stance": "neutral",
+        "reliability": 0.90,
+        "source_type": "academic",
+        "verification_weight": 0.9
+      },
+      {
+        "id": "src_005",
+        "title": "Antigone Davis (Meta VP): Congressional testimony on teen safety",
+        "text": "In congressional testimony, Meta's Global Head of Safety confirmed internal research existed but characterised it as exploratory and noted the company invested significantly in teen safety features.",
+        "url": "https://www.commerce.senate.gov/2021/9/protecting-kids-online-facebook-instagram-and-mental-health-harms",
+        "stance": "neutral",
+        "reliability": 0.88,
+        "source_type": "official",
+        "verification_weight": 0.85
+      }
+    ],
+    "ground_truth": "flag",
+    "explanation_hint": "The core claim is backed by real documents but 'destroying' overstates the research findings, and 'hid' vs 'did not publish' is contested. Flag as partially misleading framing of real events."
+  }
+]

tasks/registry.py

@@ -0,0 +1,156 @@
+"""
+tasks/registry.py
+=================
+Deterministic task registry for InformationIntegrityEnv.
+
+Loads pre-built scenario datasets from tasks/{difficulty}/scenarios.json.
+NO external API calls — all scenarios are static and reproducible.
+
+Usage
+-----
+    from tasks.registry import TASKS
+
+    task     = TASKS["easy"]
+    scenario = task.get_scenario(0)          # by index
+    scenario = task.get_scenario("easy_001") # by id
+    all_sc   = task.get_all_scenarios()
+
+    # Random selection (seeded for reproducibility)
+    import random
+    rng      = random.Random(42)
+    scenario = task.sample(rng)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+from typing import Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+_TASKS_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def _load_scenarios(difficulty: str) -> List[dict]:
+    path = os.path.join(_TASKS_DIR, difficulty, "scenarios.json")
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"Scenario dataset not found: {path}\n"
+            f"Run data_collector.py to build datasets, or check tasks/{difficulty}/scenarios.json"
+        )
+    with open(path, "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, list) or not data:
+        raise ValueError(f"scenarios.json for '{difficulty}' must be a non-empty JSON array")
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Task class
+# ---------------------------------------------------------------------------
+
+class Task:
+    """
+    Wraps one difficulty-level dataset.
+
+    Parameters
+    ----------
+    difficulty : str
+        One of 'easy', 'medium', 'hard'.
+    """
+
+    def __init__(self, difficulty: str) -> None:
+        self.difficulty = difficulty
+        self._scenarios: List[dict] = _load_scenarios(difficulty)
+        self._index_by_id: Dict[str, dict] = {s["id"]: s for s in self._scenarios}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_scenario(self, scenario_id: str | int) -> dict:
+        """
+        Return a scenario by index (int) or scenario id (str).
+        Returns a fresh copy so the env cannot mutate the dataset.
+        """
+        if isinstance(scenario_id, int):
+            if scenario_id < 0 or scenario_id >= len(self._scenarios):
+                raise IndexError(
+                    f"Scenario index {scenario_id} out of range "
+                    f"(dataset has {len(self._scenarios)} scenarios)"
+                )
+            return dict(self._scenarios[scenario_id])
+        # String id lookup
+        if scenario_id not in self._index_by_id:
+            raise KeyError(
+                f"Scenario id '{scenario_id}' not found in {self.difficulty} dataset. "
+                f"Available ids: {list(self._index_by_id.keys())}"
+            )
+        return dict(self._index_by_id[scenario_id])
+
+    def get_all_scenarios(self) -> List[dict]:
+        """Return all scenarios as a list of dicts (copies)."""
+        return [dict(s) for s in self._scenarios]
+
+    def sample(self, rng: Optional[random.Random] = None) -> dict:
+        """Return a uniformly random scenario (optionally seeded)."""
+        rng = rng or random.Random()
+        return dict(rng.choice(self._scenarios))
+
+    def __len__(self) -> int:
+        return len(self._scenarios)
+
+    def __repr__(self) -> str:
+        return f"Task(difficulty={self.difficulty!r}, n_scenarios={len(self)})"
+
+
+# ---------------------------------------------------------------------------
+# Lazy-loaded registry singleton
+# ---------------------------------------------------------------------------
+
+class _TaskRegistry:
+    """
+    Lazy-loading registry.  Datasets are only read from disk on first access,
+    so importing this module does not cause IO at import time.
+    """
+
+    _cache: Dict[str, Task] = {}
+
+    _SUPPORTED = ("easy", "medium", "hard")
+
+    def __getitem__(self, difficulty: str) -> Task:
+        key = difficulty.lower().strip()
+        if key not in self._SUPPORTED:
+            raise KeyError(
+                f"Unknown difficulty '{difficulty}'. "
+                f"Supported values: {list(self._SUPPORTED)}"
+            )
+        if key not in self._cache:
+            self._cache[key] = Task(key)
+        return self._cache[key]
+
+    def __contains__(self, difficulty: str) -> bool:
+        return difficulty.lower().strip() in self._SUPPORTED
+
+    def keys(self):
+        return self._SUPPORTED
+
+    def items(self):
+        return [(d, self[d]) for d in self._SUPPORTED]
+
+    def reload(self) -> None:
+        """Force reload all datasets from disk (useful for tests)."""
+        self._cache.clear()
+
+    def __repr__(self) -> str:
+        loaded = list(self._cache.keys())
+        return f"TaskRegistry(supported={list(self._SUPPORTED)}, loaded={loaded})"
+
+
+# Singleton — import and use directly:  from tasks.registry import TASKS
+TASKS = _TaskRegistry()

test_enhanced_stance_system.py

@@ -0,0 +1,478 @@
+"""
+test_enhanced_stance_system.py
+==============================
+Comprehensive test suite for the enhanced stance classification system.
+
+This script tests all the improvements made to the stance classification system:
+1. Enhanced text preprocessing
+2. Multi-template NLI layer
+3. Domain-specific semantic rules
+4. Quality-weighted aggregation
+5. Confidence-based decision making
+"""
+
+import logging
+import time
+from typing import List, Dict, Any
+import json
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s"
+)
+logger = logging.getLogger("test_enhanced_stance")
+
+def test_enhanced_stance_classifier():
+    """Test the enhanced stance classifier with various claim types."""
+    print("=" * 60)
+    print("TESTING ENHANCED STANCE CLASSIFIER")
+    print("=" * 60)
+    
+    try:
+        from enhanced_stance_classifier import EnhancedStanceClassifier
+        classifier = EnhancedStanceClassifier()
+        
+        # Test cases covering different domains
+        test_cases = [
+            {
+                "claim": "COVID-19 vaccines cause autism",
+                "title": "CDC Study on Vaccine Safety",
+                "text": "A comprehensive study by the CDC involving over 95,000 children found no evidence linking COVID-19 vaccines to autism. The research, published in a peer-reviewed journal, debunked claims about vaccine-autism connections. Clinical trials and post-market surveillance data consistently show vaccines are safe and effective.",
+                "source_reliability": 0.9,
+                "expected_stance": "contradicting",
+                "domain": "health"
+            },
+            {
+                "claim": "5G towers spread coronavirus",
+                "title": "WHO Statement on 5G and COVID-19",
+                "text": "The World Health Organization has stated that there is no link between 5G networks and COVID-19 transmission. Viruses cannot spread through radio waves or mobile networks. COVID-19 has spread in many countries that do not have 5G networks. Scientists confirm this is scientifically impossible.",
+                "source_reliability": 0.95,
+                "expected_stance": "contradicting",
+                "domain": "technology"
+            },
+            {
+                "claim": "Climate change is a natural phenomenon",
+                "title": "IPCC Climate Report 2023",
+                "text": "The Intergovernmental Panel on Climate Change confirms that current climate change is primarily driven by human activities. Scientific consensus shows 97% of climate scientists agree that human activities are the main cause of recent climate change. Temperature records and data analysis support this conclusion.",
+                "source_reliability": 0.92,
+                "expected_stance": "contradicting",
+                "domain": "climate"
+            },
+            {
+                "claim": "Government announces new healthcare policy",
+                "title": "Official Government Press Release",
+                "text": "The Ministry of Health officially announced a new healthcare policy today. The press release from the government website confirms the implementation of universal healthcare coverage. Official statement from the health minister validates this policy change.",
+                "source_reliability": 0.88,
+                "expected_stance": "supporting",
+                "domain": "politics"
+            },
+            {
+                "claim": "New study shows coffee reduces heart disease risk",
+                "title": "Harvard Medical School Research",
+                "text": "A peer-reviewed study published in the Journal of the American Heart Association found that moderate coffee consumption is associated with reduced risk of heart disease. The research involved 500,000 participants over 10 years. Clinical evidence shows coffee's antioxidants may protect cardiovascular health.",
+                "source_reliability": 0.85,
+                "expected_stance": "supporting",
+                "domain": "health"
+            }
+        ]
+        
+        results = []
+        for i, test_case in enumerate(test_cases, 1):
+            print(f"\nTest Case {i}: {test_case['domain'].upper()} DOMAIN")
+            print(f"Claim: {test_case['claim']}")
+            print(f"Expected: {test_case['expected_stance']}")
+            
+            start_time = time.time()
+            stance, confidence, layer = classifier.classify_detailed(
+                title=test_case['title'],
+                text=test_case['text'],
+                claim=test_case['claim'],
+                source_reliability=test_case['source_reliability']
+            )
+            end_time = time.time()
+            
+            correct = stance == test_case['expected_stance']
+            results.append({
+                "test_case": i,
+                "domain": test_case['domain'],
+                "stance": stance,
+                "confidence": confidence,
+                "layer": layer,
+                "expected": test_case['expected_stance'],
+                "correct": correct,
+                "processing_time": end_time - start_time
+            })
+            
+            print(f"Result: {stance} (confidence: {confidence:.3f}, layer: {layer})")
+            print(f"Correct: {'✓' if correct else '✗'}")
+            print(f"Processing time: {end_time - start_time:.3f}s")
+        
+        # Summary
+        correct_count = sum(1 for r in results if r['correct'])
+        total_count = len(results)
+        accuracy = correct_count / total_count
+        avg_confidence = sum(r['confidence'] for r in results) / total_count
+        avg_time = sum(r['processing_time'] for r in results) / total_count
+        
+        print(f"\n{'='*40}")
+        print("ENHANCED STANCE CLASSIFIER RESULTS")
+        print(f"{'='*40}")
+        print(f"Accuracy: {correct_count}/{total_count} ({accuracy:.1%})")
+        print(f"Average Confidence: {avg_confidence:.3f}")
+        print(f"Average Processing Time: {avg_time:.3f}s")
+        
+        # Layer usage statistics
+        layer_usage = {}
+        for result in results:
+            layer = result['layer']
+            layer_usage[layer] = layer_usage.get(layer, 0) + 1
+        
+        print(f"\nLayer Usage:")
+        for layer, count in layer_usage.items():
+            print(f"  {layer}: {count} ({count/total_count:.1%})")
+        
+        return results
+        
+    except ImportError as e:
+        print(f"Enhanced stance classifier not available: {e}")
+        return []
+
+def test_quality_weighted_aggregator():
+    """Test the quality-weighted aggregation system."""
+    print("\n" + "=" * 60)
+    print("TESTING QUALITY-WEIGHTED AGGREGATOR")
+    print("=" * 60)
+    
+    try:
+        from quality_weighted_aggregator import (
+            QualityWeightedAggregator, 
+            StanceEvidence, 
+            AggregationStrategy
+        )
+        
+        # Create test evidence
+        evidence_list = [
+            StanceEvidence(
+                stance="contradicting",
+                confidence=0.9,
+                source_reliability=0.95,
+                source_type="official",
+                method="semantic",
+                text_length=500,
+                claim_relevance=0.95
+            ),
+            StanceEvidence(
+                stance="contradicting",
+                confidence=0.8,
+                source_reliability=0.85,
+                source_type="academic",
+                method="nli",
+                text_length=800,
+                claim_relevance=0.9
+            ),
+            StanceEvidence(
+                stance="supporting",
+                confidence=0.6,
+                source_reliability=0.4,
+                source_type="blog",
+                method="keyword",
+                text_length=200,
+                claim_relevance=0.7
+            ),
+            StanceEvidence(
+                stance="neutral",
+                confidence=0.5,
+                source_reliability=0.6,
+                source_type="news",
+                method="fallback",
+                text_length=300,
+                claim_relevance=0.8
+            )
+        ]
+        
+        # Test different aggregation strategies
+        strategies = [
+            AggregationStrategy.WEIGHTED_MAJORITY,
+            AggregationStrategy.CONFIDENCE_THRESHOLD,
+            AggregationStrategy.RELIABILITY_WEIGHTED,
+            AggregationStrategy.BAYESIAN_UPDATE,
+            AggregationStrategy.ENSEMBLE
+        ]
+        
+        results = {}
+        for strategy in strategies:
+            aggregator = QualityWeightedAggregator(strategy=strategy)
+            
+            start_time = time.time()
+            stance, confidence, metadata = aggregator.aggregate_stance_evidence(
+                evidence_list, 
+                claim_text="Test claim about vaccine safety"
+            )
+            end_time = time.time()
+            
+            # Assess uncertainty
+            uncertainty = aggregator.assess_uncertainty(evidence_list)
+            
+            results[strategy.value] = {
+                "stance": stance,
+                "confidence": confidence,
+                "metadata": metadata,
+                "uncertainty": uncertainty,
+                "processing_time": end_time - start_time
+            }
+            
+            print(f"\n{strategy.value.upper()}:")
+            print(f"  Stance: {stance}")
+            print(f"  Confidence: {confidence:.3f}")
+            print(f"  High Uncertainty: {uncertainty['high_uncertainty']}")
+            print(f"  Processing Time: {end_time - start_time:.4f}s")
+        
+        # Compare results
+        print(f"\n{'='*40}")
+        print("AGGREGATION STRATEGY COMPARISON")
+        print(f"{'='*40}")
+        
+        for strategy_name, result in results.items():
+            print(f"{strategy_name:20} | {result['stance']:12} | {result['confidence']:.3f} | {result['processing_time']:.4f}s")
+        
+        return results
+        
+    except ImportError as e:
+        print(f"Quality-weighted aggregator not available: {e}")
+        return {}
+
+def test_text_processing():
+    """Test the enhanced text processing capabilities."""
+    print("\n" + "=" * 60)
+    print("TESTING ENHANCED TEXT PROCESSING")
+    print("=" * 60)
+    
+    try:
+        from enhanced_stance_classifier import TextProcessor
+        processor = TextProcessor()
+        
+        # Test text with various noise patterns
+        noisy_text = """
+        This is a test article about vaccines. [Editor's note: This is important] 
+        You can read more at https://example.com/article. @DrSmith says vaccines are safe.
+        #VaccinesSafe #HealthNews. The study (published in 2023) shows clear evidence.
+        
+        Multiple    spaces    and    formatting    issues    here.
+        
+        This is another sentence. And another one! What about questions?
+        """
+        
+        print("Original text:")
+        print(repr(noisy_text[:200] + "..."))
+        
+        # Test cleaning
+        cleaned = processor.clean_text(noisy_text)
+        print(f"\nCleaned text:")
+        print(repr(cleaned[:200] + "..."))
+        
+        # Test intelligent chunking
+        long_text = "This is a sentence. " * 50  # Create long text
+        chunks = processor.intelligent_chunk(long_text, max_length=100, overlap=20)
+        
+        print(f"\nChunking test:")
+        print(f"Original length: {len(long_text)} characters")
+        print(f"Number of chunks: {len(chunks)}")
+        print(f"Chunk lengths: {[len(chunk) for chunk in chunks]}")
+        
+        # Test entity extraction
+        entity_text = "Dr. John Smith from Harvard Medical School published a study showing 95% effectiveness. The FDA approved this treatment in 2023."
+        entities = processor.extract_key_entities(entity_text)
+        
+        print(f"\nEntity extraction test:")
+        print(f"Text: {entity_text}")
+        print(f"Entities: {entities}")
+        
+        return {
+            "cleaned_length": len(cleaned),
+            "original_length": len(noisy_text),
+            "chunk_count": len(chunks),
+            "entities_found": len(entities)
+        }
+        
+    except ImportError as e:
+        print(f"Text processor not available: {e}")
+        return {}
+
+def test_data_collector_integration():
+    """Test the integration with the enhanced data collector."""
+    print("\n" + "=" * 60)
+    print("TESTING DATA COLLECTOR INTEGRATION")
+    print("=" * 60)
+    
+    try:
+        from data_collector import DataCollector, CollectionRequest
+        
+        # Create a simple test request
+        request = CollectionRequest(
+            content="A post claiming that vaccines cause autism",
+            claims=["Vaccines cause autism"],
+            difficulty="medium"
+        )
+        
+        collector = DataCollector()
+        
+        print("Testing data collector with enhanced stance classification...")
+        print(f"Claim: {request.claims[0]}")
+        print(f"Available backends: {[b.name for b in collector._backends]}")
+        
+        # Note: This would require API keys to actually collect data
+        # For testing purposes, we'll just verify the collector is properly configured
+        print(f"Stance classifier type: {type(collector._stancer).__name__}")
+        print(f"Has classify_detailed method: {hasattr(collector._stancer, 'classify_detailed')}")
+        
+        return {
+            "collector_configured": True,
+            "enhanced_classifier": hasattr(collector._stancer, 'classify_detailed'),
+            "backend_count": len(collector._backends)
+        }
+        
+    except ImportError as e:
+        print(f"Data collector not available: {e}")
+        return {}
+
+def run_performance_benchmark():
+    """Run performance benchmarks on the enhanced system."""
+    print("\n" + "=" * 60)
+    print("PERFORMANCE BENCHMARK")
+    print("=" * 60)
+    
+    try:
+        from enhanced_stance_classifier import EnhancedStanceClassifier
+        
+        classifier = EnhancedStanceClassifier()
+        
+        # Benchmark data
+        benchmark_cases = [
+            ("Short claim", "Vaccines are safe", "Short text about vaccine safety from CDC", 0.8),
+            ("Medium claim", "Climate change is caused by human activities and poses significant risks", 
+             "A comprehensive study by climate scientists shows overwhelming evidence that human activities, particularly greenhouse gas emissions, are the primary driver of current climate change. The research, published in multiple peer-reviewed journals, demonstrates clear correlations between industrial activity and global temperature rise." * 2, 0.9),
+            ("Long claim", "The effectiveness of various COVID-19 vaccines in preventing severe illness and hospitalization", 
+             "Multiple large-scale clinical trials and real-world studies have demonstrated the effectiveness of COVID-19 vaccines in preventing severe illness, hospitalization, and death. Data from health agencies worldwide consistently show that vaccinated individuals have significantly lower rates of severe COVID-19 outcomes compared to unvaccinated individuals. The vaccines have undergone rigorous testing and continue to be monitored for safety and efficacy." * 5, 0.85)
+        ]
+        
+        results = []
+        for case_name, claim, text, reliability in benchmark_cases:
+            times = []
+            for _ in range(5):  # Run each test 5 times
+                start_time = time.time()
+                stance, confidence, layer = classifier.classify_detailed(
+                    title="Test Title",
+                    text=text,
+                    claim=claim,
+                    source_reliability=reliability
+                )
+                end_time = time.time()
+                times.append(end_time - start_time)
+            
+            avg_time = sum(times) / len(times)
+            min_time = min(times)
+            max_time = max(times)
+            
+            results.append({
+                "case": case_name,
+                "claim_length": len(claim),
+                "text_length": len(text),
+                "avg_time": avg_time,
+                "min_time": min_time,
+                "max_time": max_time,
+                "stance": stance,
+                "confidence": confidence,
+                "layer": layer
+            })
+            
+            print(f"{case_name}:")
+            print(f"  Claim length: {len(claim)} chars")
+            print(f"  Text length: {len(text)} chars")
+            print(f"  Avg time: {avg_time:.4f}s")
+            print(f"  Range: {min_time:.4f}s - {max_time:.4f}s")
+            print(f"  Result: {stance} ({confidence:.3f}, {layer})")
+            print()
+        
+        return results
+        
+    except ImportError as e:
+        print(f"Performance benchmark not available: {e}")
+        return []
+
+def main():
+    """Run all tests and generate a comprehensive report."""
+    print("ENHANCED STANCE CLASSIFICATION SYSTEM TEST SUITE")
+    print("=" * 60)
+    print(f"Test started at: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    # Run all tests
+    test_results = {}
+    
+    # Test 1: Enhanced Stance Classifier
+    test_results['stance_classifier'] = test_enhanced_stance_classifier()
+    
+    # Test 2: Quality-Weighted Aggregator
+    test_results['aggregator'] = test_quality_weighted_aggregator()
+    
+    # Test 3: Text Processing
+    test_results['text_processing'] = test_text_processing()
+    
+    # Test 4: Data Collector Integration
+    test_results['data_collector'] = test_data_collector_integration()
+    
+    # Test 5: Performance Benchmark
+    test_results['performance'] = run_performance_benchmark()
+    
+    # Generate summary report
+    print("\n" + "=" * 60)
+    print("COMPREHENSIVE TEST SUMMARY")
+    print("=" * 60)
+    
+    if test_results['stance_classifier']:
+        stance_results = test_results['stance_classifier']
+        accuracy = sum(1 for r in stance_results if r['correct']) / len(stance_results)
+        avg_confidence = sum(r['confidence'] for r in stance_results) / len(stance_results)
+        print(f"✓ Enhanced Stance Classifier: {accuracy:.1%} accuracy, {avg_confidence:.3f} avg confidence")
+    else:
+        print("✗ Enhanced Stance Classifier: Not available")
+    
+    if test_results['aggregator']:
+        print("✓ Quality-Weighted Aggregator: All strategies tested successfully")
+    else:
+        print("✗ Quality-Weighted Aggregator: Not available")
+    
+    if test_results['text_processing']:
+        tp_results = test_results['text_processing']
+        print(f"✓ Text Processing: {tp_results.get('chunk_count', 0)} chunks, {tp_results.get('entities_found', 0)} entities extracted")
+    else:
+        print("✗ Text Processing: Not available")
+    
+    if test_results['data_collector']:
+        dc_results = test_results['data_collector']
+        enhanced = "Enhanced" if dc_results.get('enhanced_classifier') else "Basic"
+        print(f"✓ Data Collector Integration: {enhanced} classifier, {dc_results.get('backend_count', 0)} backends")
+    else:
+        print("✗ Data Collector Integration: Not available")
+    
+    if test_results['performance']:
+        perf_results = test_results['performance']
+        avg_time = sum(r['avg_time'] for r in perf_results) / len(perf_results)
+        print(f"✓ Performance Benchmark: {avg_time:.4f}s average processing time")
+    else:
+        print("✗ Performance Benchmark: Not available")
+    
+    print(f"\nTest completed at: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    # Save detailed results to file
+    try:
+        with open('test_results.json', 'w') as f:
+            json.dump(test_results, f, indent=2, default=str)
+        print("Detailed results saved to test_results.json")
+    except Exception as e:
+        print(f"Could not save results: {e}")
+    
+    return test_results
+
+if __name__ == "__main__":
+    main()

ui.py

@@ -0,0 +1,683 @@
+"""
+ui.py  —  Information Integrity Analyzer
+One input. Automatic pipeline. Rich verdict output.
+"""
+
+# Load .env first so all API keys are available before any module reads os.getenv()
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+import re
+import time
+from typing import Generator
+
+import gradio as gr
+
+from data_collector import CollectionRequest, DataCollector
+from environment import InformationIntegrityEnv
+from explainability import ExplainabilityEngine, build_reasoning_from_episode
+from models import Action
+from tasks.graders import GraderFactory
+
+try:
+    from reasoning import DeterministicReasoningEngine, reason_over_claims
+    from retrieval import RetrievalPipeline
+    from decision_engine import make_moderation_decisions
+    _REASONING_AVAILABLE = True
+except Exception:
+    _REASONING_AVAILABLE = False
+
+collector = DataCollector()
+explainer = ExplainabilityEngine()
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Claim extractor
+# ─────────────────────────────────────────────────────────────────────────────
+_SIGNALS = re.compile(
+    r"\b(confirm|prove|show|reveal|say|claim|report|find|cause|lead to|linked to|"
+    r"associated with|increase|decrease|never|always|all|every|none|proven|fact|"
+    r"truth|confirmed|vaccine|virus|cancer|disease|drug|radiation|5g|covid|"
+    r"lockdown|percent|%|study|research|scientist|doctor|expert|government|"
+    r"permanently|alter|spread|hide|secret|conspiracy|banned|cure|prevent)\b",
+    re.IGNORECASE,
+)
+_SKIP = re.compile(
+    r"^(share|follow|click|subscribe|watch|read|download|buy|sign up|please|"
+    r"thank you|breaking:|update:|alert:|warning:)",
+    re.IGNORECASE,
+)
+
+
+def extract_claims(text: str) -> list[str]:
+    sentences = re.split(r"(?<=[.!?])\s+|\s*[|•–—]\s*", text.strip())
+    claims, seen = [], set()
+    for s in sentences:
+        s = s.strip().strip("\"'.,!?")
+        if len(s) < 12 or len(s) > 280:
+            continue
+        if _SKIP.match(s):
+            continue
+        if _SIGNALS.search(s) and s.lower() not in seen:
+            seen.add(s.lower())
+            claims.append(s)
+    if not claims:
+        claims = [s.strip() for s in sentences if len(s.strip()) >= 15][:3]
+    return claims[:6]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HTML card builders
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _progress_html(stage: str, pct: int, msg: str) -> str:
+    stages = ["Extracting claims", "Searching sources", "Running analysis", "Complete"]
+    dots = "".join(
+        f'<span style="display:inline-block;width:10px;height:10px;border-radius:50%;'
+        f'margin:0 4px;background:{"#4f8ef7" if i <= stages.index(stage) else "#dde3ee"}'
+        f'"></span>'
+        for i, s in enumerate(stages)
+        if (i <= stages.index(stage)) or True
+    )
+    return f"""
+    <div style="font-family:'Inter',sans-serif;padding:28px 32px;background:#f8faff;
+                border-radius:16px;border:1px solid #e0e7ff;">
+      <div style="font-size:15px;color:#5c6bc0;margin-bottom:14px;font-weight:600;">
+        {stage}… &nbsp; <span style="font-weight:400;color:#8e99c5">{msg}</span>
+      </div>
+      <div style="background:#e8edf8;border-radius:8px;height:8px;overflow:hidden;">
+        <div style="background:linear-gradient(90deg,#4f8ef7,#7c6af7);height:100%;
+                    width:{pct}%;transition:width 0.4s ease;border-radius:8px;"></div>
+      </div>
+    </div>"""
+
+
+def _verdict_color(decision: str) -> tuple[str, str, str]:
+    """Returns (bg_gradient, text_color, icon)."""
+    return {
+        "remove": ("linear-gradient(135deg,#ff4444,#d32f2f)", "#fff", "🚫"),
+        "flag":   ("linear-gradient(135deg,#ff9800,#e65100)", "#fff", "⚠️"),
+        "allow":  ("linear-gradient(135deg,#43a047,#1b5e20)", "#fff", "✅"),
+    }.get(decision, ("linear-gradient(135deg,#607d8b,#37474f)", "#fff", "❓"))
+
+
+def _reliability_bar(score: float) -> str:
+    filled = int(score * 12)
+    color  = "#e53935" if score < 0.4 else "#fb8c00" if score < 0.7 else "#43a047"
+    bar    = f'<span style="color:{color}">{"█"*filled}</span>' \
+             f'<span style="color:#e0e0e0">{"█"*(12-filled)}</span>'
+    return f'<span style="font-family:monospace;font-size:12px">{bar}</span> ' \
+           f'<span style="font-size:12px;color:#666">{score:.2f}</span>'
+
+
+def _stance_badge(stance: str) -> str:
+    cfg = {
+        "contradicting": ("#fdecea", "#c62828", "✗ Contradicts"),
+        "supporting":    ("#e8f5e9", "#2e7d32", "✓ Supports"),
+        "neutral":       ("#f3f4f6", "#555",    "· Neutral"),
+    }.get(stance, ("#f3f4f6", "#555", stance))
+    bg, fg, label = cfg
+    return (f'<span style="background:{bg};color:{fg};padding:2px 8px;'
+            f'border-radius:12px;font-size:12px;font-weight:600">{label}</span>')
+
+
+def _claim_badge(status: str) -> str:
+    cfg = {
+        "false":          ("#fdecea", "#c62828", "FALSE"),
+        "true":           ("#e8f5e9", "#2e7d32", "TRUE"),
+        "partially_true": ("#fff8e1", "#e65100", "PARTIAL"),
+        "unknown":        ("#f3f4f6", "#555",    "UNKNOWN"),
+        "unverified":     ("#f3f4f6", "#9e9e9e", "UNVERIFIED"),
+    }.get(status.lower() if isinstance(status, str) else "unverified",
+          ("#f3f4f6", "#555", status))
+    bg, fg, label = cfg
+    return (f'<span style="background:{bg};color:{fg};padding:3px 10px;'
+            f'border-radius:12px;font-size:11px;font-weight:700;'
+            f'letter-spacing:.5px">{label}</span>')
+
+
+def build_result_html(statement: str, scenario: dict, obs, result, explanation: str,
+                      per_claim_reasoning: dict | None = None) -> str:
+    decision = result.decision or "unknown"
+    grad, txt_col, icon = _verdict_color(decision)
+    correct_badge = (
+        '<span style="background:#e8f5e9;color:#2e7d32;padding:3px 10px;'
+        'border-radius:12px;font-size:12px;font-weight:600">✓ Correct</span>'
+        if result.correct else
+        '<span style="background:#fdecea;color:#c62828;padding:3px 10px;'
+        'border-radius:12px;font-size:12px;font-weight:600">✗ Incorrect</span>'
+    )
+
+    # ── Claims section
+    claims_html = ""
+    for c in obs.claims:
+        status = c.verification_status
+        if hasattr(status, "value"):
+            status = status.value
+        conf_pct = int(c.confidence * 100)
+        claims_html += f"""
+        <div style="display:flex;align-items:flex-start;gap:12px;padding:12px 0;
+                    border-bottom:1px solid #f0f0f0;">
+          <div style="flex:1;font-size:14px;color:#333;line-height:1.5">{c.text}</div>
+          <div style="display:flex;flex-direction:column;align-items:flex-end;gap:4px;
+                      white-space:nowrap">
+            {_claim_badge(status)}
+            <span style="font-size:11px;color:#999">conf {conf_pct}%</span>
+          </div>
+        </div>"""
+
+    # ── Sources section (top 6 by reliability)
+    sources = sorted(scenario["sources"], key=lambda s: -s["reliability"])[:6]
+    sources_html = ""
+    for s in sources:
+        domain = re.sub(r"https?://(www\.)?", "", s["url"]).split("/")[0]
+        sources_html += f"""
+        <div style="padding:12px;border-radius:10px;background:#fafafa;
+                    border:1px solid #eee;margin-bottom:8px">
+          <div style="display:flex;justify-content:space-between;align-items:center;
+                      flex-wrap:wrap;gap:6px">
+            <span style="font-size:13px;font-weight:600;color:#333">{s['title'][:65]}</span>
+            {_stance_badge(s['stance'])}
+          </div>
+          <div style="font-size:12px;color:#888;margin:4px 0">{domain} · {s['source_type']}</div>
+          <div style="font-size:12px;color:#555;line-height:1.5;margin:6px 0">
+            {s['text'][:180]}{'…' if len(s['text'])>180 else ''}
+          </div>
+          <div>Reliability: {_reliability_bar(s['reliability'])}</div>
+        </div>"""
+
+    if not sources_html:
+        sources_html = '<p style="color:#999;font-style:italic">No sources fetched — try adding API keys for richer results.</p>'
+
+    # ── Reward breakdown
+    bd = result.reward_breakdown
+    reward_rows = ""
+    for label, val in [
+        ("Claim verification", bd.verify_claim_reward),
+        ("Source checks",      bd.check_source_reward),
+        ("Multi-source bonus", bd.multi_source_bonus),
+        ("Decision accuracy",  bd.decision_reward),
+        ("Premature penalty",  bd.premature_penalty),
+        ("Redundancy penalty", bd.redundant_penalty),
+        ("Inefficiency",       bd.inefficiency_penalty),
+        ("Over-aggression",    bd.aggression_penalty),
+    ]:
+        if val == 0:
+            continue
+        color = "#2e7d32" if val > 0 else "#c62828"
+        reward_rows += f"""
+        <div style="display:flex;justify-content:space-between;padding:5px 0;
+                    border-bottom:1px solid #f5f5f5;font-size:13px">
+          <span style="color:#555">{label}</span>
+          <span style="color:{color};font-weight:600">{val:+.2f}</span>
+        </div>"""
+
+    # ── Grader sub-scores
+    grader = GraderFactory.get(scenario["difficulty"])
+    gbd = grader.score_breakdown(
+        decision        = result.decision or "none",
+        ground_truth    = result.ground_truth,
+        sources_checked = list(range(result.sources_checked)),
+        claims_verified = list(range(result.claims_verified)),
+        step_count      = result.steps_taken,
+        all_source_ids  = [s["id"] for s in scenario["sources"]],
+        all_claim_ids   = [c["id"] for c in scenario["claims"]],
+    )
+    grader_bars = ""
+    for sub_label, sub_val in [
+        ("Decision",   gbd["decision_sub_score"]),
+        ("Evidence",   gbd["evidence_sub_score"]),
+        ("Reasoning",  gbd["reasoning_sub_score"]),
+        ("Efficiency", gbd["efficiency_sub_score"]),
+    ]:
+        pct  = int(sub_val * 100)
+        colr = "#e53935" if pct < 50 else "#fb8c00" if pct < 75 else "#43a047"
+        grader_bars += f"""
+        <div style="margin-bottom:8px">
+          <div style="display:flex;justify-content:space-between;font-size:12px;
+                      color:#555;margin-bottom:3px">
+            <span>{sub_label}</span><span style="color:{colr};font-weight:600">{pct}%</span>
+          </div>
+          <div style="background:#eee;border-radius:4px;height:6px">
+            <div style="background:{colr};width:{pct}%;height:100%;border-radius:4px"></div>
+          </div>
+        </div>"""
+
+    # ── Deterministic Reasoning breakdown (new)
+    reasoning_html = ""
+    if per_claim_reasoning:
+        reasoning_html = """
+      <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                  padding:20px 24px;margin-bottom:20px">
+        <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                    text-transform:uppercase;margin-bottom:14px">
+          🧠 Deterministic Reasoning Engine
+        </div>"""
+        for claim_text, r in per_claim_reasoning.items():
+            score   = r["evidence_score"]
+            conf    = r["confidence"]
+            dec     = r["decision"]
+            n_sup   = r["n_supporting"]
+            n_con   = r["n_contradicting"]
+            n_neu   = r["n_neutral"]
+            dec_col = {"allow": "#2e7d32", "flag": "#e65100", "remove": "#c62828"}.get(dec, "#555")
+            score_col = "#c62828" if score < -0.3 else "#2e7d32" if score > 0.3 else "#e65100"
+            reasoning_html += f"""
+        <div style="background:#f8faff;border-radius:10px;padding:14px 18px;margin-bottom:12px;
+                    border-left:4px solid {dec_col}">
+          <div style="font-size:13px;color:#444;font-style:italic;margin-bottom:8px">
+            "{claim_text[:100]}{'…' if len(claim_text)>100 else ''}"
+          </div>
+          <div style="display:flex;gap:12px;flex-wrap:wrap;margin-bottom:8px">
+            <span style="background:{dec_col};color:#fff;padding:2px 10px;border-radius:10px;
+                         font-size:12px;font-weight:700;text-transform:uppercase">{dec}</span>
+            <span style="font-size:12px;color:{score_col};font-weight:600">
+              Score: {score:+.3f}</span>
+            <span style="font-size:12px;color:#888">Confidence: {conf}</span>
+            <span style="font-size:12px;color:#2e7d32">▲ {n_sup} supporting</span>
+            <span style="font-size:12px;color:#c62828">▼ {n_con} contradicting</span>
+            <span style="font-size:12px;color:#888">· {n_neu} neutral</span>
+          </div>"""
+            # Safety rules fired
+            if r.get("safety_rules_fired"):
+                for rule in r["safety_rules_fired"]:
+                    rule_name = rule.split(":")[0]
+                    rule_desc = rule[len(rule_name)+1:].strip()
+                    reasoning_html += f"""
+          <div style="font-size:11px;color:#e65100;background:#fff8e1;padding:4px 10px;
+                      border-radius:6px;margin-bottom:4px">
+            ⚠ <b>{rule_name}</b>: {rule_desc}
+          </div>"""
+            # Source breakdown (top 4)
+            sb = r.get("source_breakdown", [])[:4]
+            if sb:
+                reasoning_html += '<div style="margin-top:8px">'
+                for src in sb:
+                    contrib = src["contribution"]
+                    c_col   = "#c62828" if contrib < 0 else "#2e7d32" if contrib > 0 else "#888"
+                    reasoning_html += f"""
+            <div style="display:flex;justify-content:space-between;font-size:11px;
+                        color:#555;padding:2px 0;border-bottom:1px solid #eee">
+              <span style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
+                           max-width:420px">{src['title'][:70]}</span>
+              <span style="margin:0 8px">{_stance_badge(src['stance'])}</span>
+              <span style="font-weight:600;color:{c_col};white-space:nowrap">
+                {contrib:+.3f}</span>
+            </div>"""
+                reasoning_html += "</div>"
+            reasoning_html += "</div>"
+        reasoning_html += "</div>"
+
+    # ── Explanation (pre-formatted)
+    expl_lines = explanation.replace("<", "&lt;").replace(">", "&gt;")
+    expl_html  = f'<pre style="font-family:inherit;font-size:13px;line-height:1.7;' \
+                 f'white-space:pre-wrap;margin:0;color:#333">{expl_lines}</pre>'
+
+    return f"""
+    <div style="font-family:'Inter',system-ui,sans-serif;max-width:960px;margin:0 auto">
+
+      <!-- VERDICT BANNER -->
+      <div style="background:{grad};border-radius:16px;padding:28px 32px;
+                  margin-bottom:24px;display:flex;align-items:center;gap:20px">
+        <div style="font-size:52px">{icon}</div>
+        <div>
+          <div style="color:rgba(255,255,255,.75);font-size:13px;
+                      font-weight:600;letter-spacing:1px;text-transform:uppercase">
+            Moderation Verdict
+          </div>
+          <div style="color:{txt_col};font-size:36px;font-weight:800;
+                      line-height:1.1;text-transform:uppercase">{decision}</div>
+          <div style="color:rgba(255,255,255,.85);font-size:13px;margin-top:4px">
+            Difficulty: <b>{scenario['difficulty']}</b> &nbsp;·&nbsp;
+            Steps: <b>{result.steps_taken}</b> &nbsp;·&nbsp;
+            Reward: <b>{result.total_reward:+.2f}</b> &nbsp;·&nbsp;
+            Grader: <b>{result.grader_score:.0%}</b>
+            &nbsp;&nbsp;{correct_badge}
+          </div>
+        </div>
+      </div>
+
+      <!-- STATEMENT -->
+      <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                  padding:20px 24px;margin-bottom:20px">
+        <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                    text-transform:uppercase;margin-bottom:8px">Statement Reviewed</div>
+        <div style="font-size:15px;color:#1f2937;line-height:1.6;
+                    font-style:italic">"{statement}"</div>
+      </div>
+
+      <!-- CLAIMS + SOURCES (two col) -->
+      <div style="display:grid;grid-template-columns:1fr 1fr;gap:20px;margin-bottom:20px">
+
+        <!-- Claims -->
+        <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                    padding:20px 24px">
+          <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                      text-transform:uppercase;margin-bottom:12px">
+            Claims Verified ({len(obs.claims)})
+          </div>
+          {claims_html}
+        </div>
+
+        <!-- Scores -->
+        <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                    padding:20px 24px">
+          <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                      text-transform:uppercase;margin-bottom:14px">Grader Score Breakdown</div>
+          {grader_bars}
+          <div style="border-top:1px solid #eee;padding-top:12px;margin-top:4px">
+            <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                        text-transform:uppercase;margin-bottom:8px">Reward Breakdown</div>
+            {reward_rows}
+            <div style="display:flex;justify-content:space-between;padding:8px 0;
+                        font-size:14px;font-weight:700">
+              <span>Total Reward</span>
+              <span style="color:{'#2e7d32' if result.total_reward>0 else '#c62828'}">
+                {result.total_reward:+.2f}
+              </span>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- SOURCES -->
+      <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                  padding:20px 24px;margin-bottom:20px">
+        <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                    text-transform:uppercase;margin-bottom:14px">
+          Evidence Sources ({len(scenario['sources'])} found)
+        </div>
+        {sources_html}
+      </div>
+
+      {reasoning_html}
+
+      <!-- EXPLANATION -->
+      <div style="background:#fff;border-radius:14px;border:1px solid #e8ecf4;
+                  padding:20px 24px">
+        <div style="font-size:11px;font-weight:700;color:#9ca3af;letter-spacing:1px;
+                    text-transform:uppercase;margin-bottom:14px">
+          📋 Full Reasoning & Explanation
+        </div>
+        <div style="background:#f8faff;border-radius:10px;padding:16px 20px">
+          {expl_html}
+        </div>
+      </div>
+
+    </div>
+    """
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main pipeline (streaming generator)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def analyze(statement: str) -> Generator:
+    """
+    Difficulty is NOT a UI input.
+    The UI is a demo tool; evaluation difficulty is controlled exclusively
+    by the backend API (/reset?difficulty=...) and inference.py.
+    DataCollector always uses 'medium' here — it only affects evidence
+    retrieval depth, not grading.
+    """
+    statement = statement.strip()
+    if not statement:
+        yield "<p style='color:#c62828;padding:20px'>⚠️ Please enter a statement to analyze.</p>"
+        return
+
+    # Stage 1 — Extract claims
+    yield _progress_html("Extracting claims", 10, "detecting verifiable assertions…")
+    claims = extract_claims(statement)
+    if not claims:
+        claims = [statement]
+    claim_list = "  •  ".join(f"<em>{c[:60]}</em>" for c in claims)
+    yield _progress_html("Searching sources", 30,
+                         f"found {len(claims)} claim(s): {claim_list[:120]}…")
+
+    # Stage 2 — Collect evidence
+    # Difficulty is fixed to "medium" here — the UI does NOT control evaluation logic.
+    # To run a proper benchmark, use: python inference.py --benchmark
+    try:
+        req      = CollectionRequest(content=statement, claims=claims,
+                                     difficulty="medium")
+        scenario = collector.collect(req)
+    except Exception as e:
+        yield f"<p style='color:#c62828;padding:20px'>❌ Evidence collection failed: {e}</p>"
+        return
+
+    n_src = len(scenario["sources"])
+    yield _progress_html("Running analysis", 65,
+                         f"fetched {n_src} source(s) — running moderation episode…")
+
+    # Stage 3 — Run episode
+    env = InformationIntegrityEnv(scenario=scenario, max_steps=20)
+    obs = env.reset()
+    per_claim_reasoning = None  # populated by reasoning engine at decide step
+
+    # Auto-agent: verify all claims → check all sources → decide
+    for claim in obs.claims:
+        try:
+            obs, _, done, _ = env.step(
+                Action(type="verify_claim", claim_id=claim.id,
+                       reasoning="auto-verify"))
+            if done:
+                break
+        except Exception:
+            pass
+
+    if not env.done:
+        for src in obs.available_sources:
+            try:
+                obs, _, done, _ = env.step(
+                    Action(type="check_source", source_id=src.id,
+                           reasoning="auto-check"))
+                if done:
+                    break
+            except Exception:
+                pass
+
+    if not env.done:
+        # Use DeterministicReasoningEngine if available, else weighted fallback
+        if _REASONING_AVAILABLE:
+            try:
+                pipeline = RetrievalPipeline()
+                engine   = DeterministicReasoningEngine()
+                raw_sources = [
+                    {
+                        "id": s.id, "title": s.title, "text": s.text,
+                        "url": s.url, "stance": s.stance,
+                        "reliability": s.reliability, "source_type": s.source_type,
+                    }
+                    for s in obs.available_sources
+                ]
+                claim_texts = [c.text for c in obs.claims]
+                claim_results_map = pipeline.retrieve_for_all_claims(claim_texts, raw_sources)
+                agg_decision, per_claim_reasoning = reason_over_claims(claim_results_map, engine)
+                # Convert StructuredReasoning objects → dicts for the HTML builder
+                per_claim_reasoning = {ct: r.to_dict() for ct, r in per_claim_reasoning.items()}
+
+                # ── decision_engine: recalibrate each claim's confidence & decision ──
+                de_inputs = []
+                for ct, r in per_claim_reasoning.items():
+                    src_list = claim_results_map.get(ct, [])
+                    de_inputs.append({
+                        "claim":                  ct,
+                        "status":                 "FALSE" if r["decision"] == "remove"
+                                                  else "TRUE" if r["decision"] == "allow"
+                                                  else "UNKNOWN",
+                        "confidence":             r.get("evidence_score", 0.0),
+                        "supporting_sources":     r["n_supporting"],
+                        "contradicting_sources":  r["n_contradicting"],
+                        "neutral_sources":        r["n_neutral"],
+                        "avg_source_reliability": (
+                            sum(s.reliability for s in src_list) / len(src_list)
+                            if src_list else 0.5
+                        ),
+                    })
+                de_result = make_moderation_decisions(de_inputs)
+
+                # Map content decision back to env decision format
+                _de_map = {"AUTO_REMOVE": "remove", "ALLOW": "allow", "FLAG_FOR_REVIEW": "flag"}
+                decision = _de_map.get(de_result["content_decision"], agg_decision)
+
+                # Inject decision_engine output into per_claim_reasoning for display
+                for entry in de_result["per_claim"]:
+                    ct = entry["claim"]
+                    if ct in per_claim_reasoning:
+                        per_claim_reasoning[ct]["de_decision"]   = entry["decision"]
+                        per_claim_reasoning[ct]["de_confidence"] = entry["final_confidence"]
+                        per_claim_reasoning[ct]["de_reason"]     = entry["reason"]
+                        per_claim_reasoning[ct]["de_pattern"]    = entry.get("pattern_matched")
+
+            except Exception:
+                per_claim_reasoning = None
+                # Fallback to weighted ratio
+                contra = sum(s.reliability for s in obs.available_sources if s.stance == "contradicting")
+                supp   = sum(s.reliability for s in obs.available_sources if s.stance == "supporting")
+                total  = contra + supp or 1.0
+                ratio  = supp / total
+                decision = "remove" if ratio < 0.25 else "flag" if ratio < 0.60 else "allow"
+        else:
+            per_claim_reasoning = None
+            contra = sum(s.reliability for s in obs.available_sources if s.stance == "contradicting")
+            supp   = sum(s.reliability for s in obs.available_sources if s.stance == "supporting")
+            total  = contra + supp or 1.0
+            ratio  = supp / total
+            decision = "remove" if ratio < 0.25 else "flag" if ratio < 0.60 else "allow"
+
+        try:
+            obs, _, _, _ = env.step(
+                Action(type="decide", decision=decision,
+                       reasoning="deterministic engine decision"))
+        except Exception:
+            pass
+    else:
+        per_claim_reasoning = None
+
+    yield _progress_html("Complete", 95, "generating explanation…")
+
+    # Stage 4 — Build result
+    result   = env.episode_result()
+    reasoning = build_reasoning_from_episode(
+        obs=obs,
+        decision=result.decision or "unknown",
+        episode_id=env._episode_id,
+        difficulty=scenario["difficulty"],
+    )
+    explanation = explainer.generate_explanation(reasoning)
+
+    # Use engine's per_claim_reasoning if captured, else env's cached reasoning
+    if per_claim_reasoning is None and env._last_reasoning:
+        per_claim_reasoning = {
+            ct: r.to_dict() for ct, r in env._last_reasoning.items()
+        }
+
+    yield build_result_html(statement, scenario, obs, result, explanation,
+                            per_claim_reasoning=per_claim_reasoning)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UI Layout
+# ─────────────────────────────────────────────────────────────────────────────
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap');
+body, .gradio-container { font-family: 'Inter', system-ui, sans-serif !important; background: #f0f4ff !important; }
+.gr-button-primary { background: linear-gradient(135deg,#4f8ef7,#7c6af7) !important;
+                     border:none !important; font-weight:700 !important;
+                     font-size:16px !important; padding:14px 36px !important;
+                     border-radius:12px !important; color:white !important; }
+.gr-button-primary:hover { opacity:.9 !important; transform:translateY(-1px); }
+textarea { font-size:15px !important; border-radius:12px !important;
+           border:2px solid #e0e7ff !important; padding:14px !important; }
+textarea:focus { border-color:#4f8ef7 !important; box-shadow:0 0 0 3px rgba(79,142,247,.15) !important; }
+.gr-form { background:transparent !important; }
+.gr-box { background:transparent !important; border:none !important; box-shadow:none !important; }
+#component-0 { background: #f0f4ff !important; }
+"""
+
+EXAMPLES = [
+    "5G towers confirmed to spread COVID-19. Scientists reveal radiation activates coronavirus. Governments hiding the truth.",
+    "Doctors confirm: drinking 3 cups of coffee daily prevents Alzheimer's in 100% of patients with zero side effects.",
+    "New government report proves immigration increases violent crime by 40% in all affected regions. Multiple studies confirm.",
+    "mRNA vaccines permanently alter human DNA and cause infertility according to multiple top doctors and researchers.",
+    "There will be a national lockdown starting next week. Government sources confirmed mandatory quarantine for all cities.",
+    "Eating chocolate every day reduces heart attack risk by 50% — scientists confirm in landmark study.",
+]
+
+with gr.Blocks(title="Information Integrity Analyzer") as demo:
+
+    gr.HTML("""
+    <div style="text-align:center;padding:40px 20px 20px;font-family:'Inter',sans-serif">
+      <div style="font-size:36px;margin-bottom:8px">🛡️</div>
+      <h1 style="font-size:28px;font-weight:800;color:#1e2a4a;margin:0 0 8px">
+        Information Integrity Analyzer
+      </h1>
+      <p style="color:#6b7280;font-size:15px;max-width:520px;margin:0 auto">
+        Paste any statement or claim. The system automatically extracts assertions,
+        searches real evidence sources, and delivers a moderation verdict with full explanation.
+      </p>
+      <p style="color:#9ca3af;font-size:12px;margin-top:8px">
+        Demo mode — for benchmarking across difficulty tiers run:
+        <code>python inference.py --benchmark</code>
+      </p>
+    </div>
+    """)
+
+    with gr.Row(elem_id="main-row"):
+        with gr.Column(scale=1, min_width=640):
+
+            statement_box = gr.Textbox(
+                label="",
+                placeholder=(
+                    "Paste any statement, post, or claim here…\n\n"
+                    "e.g. \"5G towers confirmed to spread COVID-19. "
+                    "Governments hiding the truth.\""
+                ),
+                lines=4,
+                max_lines=8,
+                show_label=False,
+            )
+
+            analyze_btn = gr.Button(
+                "🔍  Analyze Statement",
+                variant="primary",
+            )
+
+            gr.HTML("<div style='margin:8px 0 4px;font-size:12px;color:#9ca3af;font-weight:600;letter-spacing:.5px;text-transform:uppercase'>Try an example</div>")
+
+            with gr.Row():
+                for ex_text in EXAMPLES[:3]:
+                    btn = gr.Button(ex_text[:45] + "…", size="sm", scale=1)
+                    btn.click(fn=lambda t=ex_text: t, outputs=[statement_box])
+            with gr.Row():
+                for ex_text in EXAMPLES[3:]:
+                    btn = gr.Button(ex_text[:45] + "…", size="sm", scale=1)
+                    btn.click(fn=lambda t=ex_text: t, outputs=[statement_box])
+
+    result_html = gr.HTML(
+        value="<div style='padding:32px;text-align:center;color:#9ca3af;font-size:15px'>"
+              "Results will appear here after analysis.</div>"
+    )
+
+    analyze_btn.click(
+        fn=analyze,
+        inputs=[statement_box],
+        outputs=[result_html],
+    )
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+        css=CSS,
+        theme=gr.themes.Soft(
+            primary_hue="indigo",
+            secondary_hue="purple",
+            neutral_hue="slate",
+            font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
+        ),
+    )