tru8-mcp 1.0.0__tar.gz

tru8_mcp-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.env

tru8_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tru8
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tru8_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tru8-mcp
+Version: 1.0.0
+Summary: Tru8 Evidence Research MCP server — structured evidence research tools for AI agents
+Project-URL: Homepage, https://www.trueight.com/developers
+Project-URL: Repository, https://github.com/SamYatesSmith/tru8-mcp
+Project-URL: Documentation, https://www.trueight.com/developers
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,evidence,fact-check,mcp,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# tru8-mcp
+
+MCP server for [Tru8 Evidence Research](https://www.trueight.com) — structured evidence research tools for AI agents.
+
+Submit a claim or URL, get back source-traced evidence organized by tier (primary/reporting/commentary) and type (data/official/news/analysis/opinion/academic), with element decomposition and relationship mapping.
+
+## Quick Start
+
+```bash
+pip install tru8-mcp
+```
+
+Or run without installing:
+
+```bash
+uvx tru8-mcp
+```
+
+Set your API key:
+
+```bash
+export TRU8_API_KEY=tru8_sk_...
+```
+
+Create an API key at your [Tru8 dashboard](https://www.trueight.com/dashboard/settings) under Settings > Developer.
+
+## Configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tru8": {
+      "command": "tru8-mcp",
+      "env": {
+        "TRU8_API_KEY": "tru8_sk_..."
+      }
+    }
+  }
+}
+```
+
+### Cline / Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "tru8": {
+      "command": "uvx",
+      "args": ["tru8-mcp"],
+      "env": {
+        "TRU8_API_KEY": "tru8_sk_..."
+      }
+    }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/tru8-evidence/tru8-mcp.git
+cd tru8-mcp
+pip install -e .
+tru8-mcp
+```
+
+## Tools
+
+| Tool | Description | Typical time |
+|------|-------------|-------------|
+| `tru8_check` | Evidence research for a claim or article URL | 15-120s |
+| `tru8_get_result` | Retrieve completed check with computed analytics | <1s |
+| `tru8_get_result_raw` | Retrieve raw check data without computed analytics | <1s |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TRU8_API_KEY` | Yes | API key (`tru8_sk_...`). Create at dashboard > Settings > Developer. |
+| `TRU8_API_URL` | No | API base URL. Default: `https://api.trueight.com` |
+
+## Security
+
+Store API keys in environment variables or a secrets manager. Never hardcode keys in source code. If a key is compromised, revoke it immediately at your dashboard.

tru8_mcp-1.0.0/README.md

@@ -0,0 +1,90 @@
+# tru8-mcp
+
+MCP server for [Tru8 Evidence Research](https://www.trueight.com) — structured evidence research tools for AI agents.
+
+Submit a claim or URL, get back source-traced evidence organized by tier (primary/reporting/commentary) and type (data/official/news/analysis/opinion/academic), with element decomposition and relationship mapping.
+
+## Quick Start
+
+```bash
+pip install tru8-mcp
+```
+
+Or run without installing:
+
+```bash
+uvx tru8-mcp
+```
+
+Set your API key:
+
+```bash
+export TRU8_API_KEY=tru8_sk_...
+```
+
+Create an API key at your [Tru8 dashboard](https://www.trueight.com/dashboard/settings) under Settings > Developer.
+
+## Configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tru8": {
+      "command": "tru8-mcp",
+      "env": {
+        "TRU8_API_KEY": "tru8_sk_..."
+      }
+    }
+  }
+}
+```
+
+### Cline / Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "tru8": {
+      "command": "uvx",
+      "args": ["tru8-mcp"],
+      "env": {
+        "TRU8_API_KEY": "tru8_sk_..."
+      }
+    }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/tru8-evidence/tru8-mcp.git
+cd tru8-mcp
+pip install -e .
+tru8-mcp
+```
+
+## Tools
+
+| Tool | Description | Typical time |
+|------|-------------|-------------|
+| `tru8_check` | Evidence research for a claim or article URL | 15-120s |
+| `tru8_get_result` | Retrieve completed check with computed analytics | <1s |
+| `tru8_get_result_raw` | Retrieve raw check data without computed analytics | <1s |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TRU8_API_KEY` | Yes | API key (`tru8_sk_...`). Create at dashboard > Settings > Developer. |
+| `TRU8_API_URL` | No | API base URL. Default: `https://api.trueight.com` |
+
+## Security
+
+Store API keys in environment variables or a secrets manager. Never hardcode keys in source code. If a key is compromised, revoke it immediately at your dashboard.

tru8_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tru8-mcp"
+version = "1.0.0"
+description = "Tru8 Evidence Research MCP server — structured evidence research tools for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["mcp", "evidence", "fact-check", "ai-agent", "research"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://www.trueight.com/developers"
+Repository = "https://github.com/SamYatesSmith/tru8-mcp"
+Documentation = "https://www.trueight.com/developers"
+
+[project.scripts]
+tru8-mcp = "tru8_mcp.server:main"

tru8_mcp-1.0.0/server.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.tru8/mcp-server",
+  "title": "Tru8 Evidence Research",
+  "description": "Structured evidence research for AI agents. Ground factual claims in source-traced evidence organized by tier (primary data / news reporting / commentary) and type (data / official / news / analysis / opinion / academic). Returns element decomposition with relationship mapping (supports / challenges / context).",
+  "version": "1.0.0",
+  "websiteUrl": "https://www.trueight.com/developers",
+  "repository": {
+    "url": "https://github.com/SamYatesSmith/tru8-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "_note_package": "Publish to PyPI before submitting to MCP Registry",
+      "registryType": "pip",
+      "identifier": "tru8-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [],
+      "environmentVariables": [
+        {
+          "name": "TRU8_API_KEY",
+          "isRequired": true,
+          "isSecret": true,
+          "description": "Tru8 API key (tru8_sk_...). Create at dashboard Settings > Developer. Store in env vars, never hardcode."
+        },
+        {
+          "name": "TRU8_API_URL",
+          "isRequired": false,
+          "isSecret": false,
+          "description": "API base URL. Default: https://api.trueight.com"
+        }
+      ],
+      "runtimeHint": "python -m tru8_mcp"
+    }
+  ],
+  "tools": [
+    {
+      "name": "tru8_check",
+      "description": "Evidence research for any claim or URL. Accepts max_tier (lookup/quick/full) to control depth and cost. Tier fallback: lookup → quick → full. Returns structured evidence landscape with element decomposition, source classification, and _meta (executedTier, chargedPence)."
+    },
+    {
+      "name": "tru8_get_result",
+      "description": "Retrieve a completed check with pre-computed analytics: tier/type distributions, corroboration groups, diagnostic values, timeline, per-claim dispositions."
+    },
+    {
+      "name": "tru8_get_result_raw",
+      "description": "Retrieve raw check data without computed analytics. Smaller payload for custom post-processing."
+    }
+  ]
+}

tru8_mcp-1.0.0/smithery.yaml

@@ -0,0 +1,23 @@
+# Smithery configuration — https://smithery.ai/docs/config
+# Tru8 MCP server: structured evidence research for AI agents
+
+build:
+  dockerBuildPath: .
+
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required:
+      - apiKey
+    properties:
+      apiKey:
+        type: string
+        description: "Tru8 API key (tru8_sk_...). Create at dashboard → Settings → Developer."
+      apiUrl:
+        type: string
+        description: "API base URL. Default: https://api.trueight.com"
+        default: "https://api.trueight.com"
+  commandFunction:
+    |-
+    (config) => ({ command: 'python', args: ['-m', 'tru8_mcp'], env: { TRU8_API_KEY: config.apiKey, TRU8_API_URL: config.apiUrl || 'https://api.trueight.com' } })

tru8_mcp-1.0.0/tru8_mcp/__init__.py

@@ -0,0 +1 @@
+"""Tru8 MCP server — structured evidence research tools for AI agents."""

tru8_mcp-1.0.0/tru8_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m tru8_mcp`."""
+
+from .server import main
+
+main()

tru8_mcp-1.0.0/tru8_mcp/server.py

@@ -0,0 +1,149 @@
+"""Tru8 MCP server — structured evidence research tools for AI agents.
+
+Run standalone:
+    python -m tru8_mcp
+
+Configure for Claude Desktop (claude_desktop_config.json):
+    {
+        "mcpServers": {
+            "tru8": {
+                "command": "python",
+                "args": ["-m", "tru8_mcp"],
+                "env": {"TRU8_API_KEY": "tru8_sk_..."}
+            }
+        }
+    }
+
+Environment variables:
+    TRU8_API_KEY  — Required. Create at dashboard → Settings → Developer.
+                    Store in env vars or a secrets manager — never hardcode in source.
+    TRU8_API_URL  — Optional. Default: https://api.trueight.com
+"""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from .tools import Tru8APIClient
+
+mcp = FastMCP(
+    "tru8",
+    instructions=(
+        "Structured evidence research. Submit a factual claim or article URL. "
+        "Evidence is organised by source tier (primary/reporting/commentary) "
+        "and type (data/official/news/analysis/opinion/academic), with element "
+        "decomposition and relationship mapping (supports/challenges/context)."
+    ),
+)
+
+_client: Tru8APIClient | None = None
+
+
+def _get_client() -> Tru8APIClient:
+    """Lazy-initialize the API client (reads env vars on first call)."""
+    global _client
+    if _client is None:
+        _client = Tru8APIClient()
+    return _client
+
+
+def _format(data: dict) -> str:
+    """Serialize API response as indented JSON for agent consumption."""
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def tru8_check(
+    claim: str,
+    max_tier: str = "quick",
+    max_age_hours: int | None = None,
+    compact: bool = False,
+) -> str:
+    """Evidence research for a factual claim or article URL.
+
+    Submit a claim as text or paste an article URL. URLs are auto-detected
+    and trigger article mode: the pipeline extracts claims from the page
+    and auto-selects up to 5 for evidence research.
+
+    Tiers (in fallback order):
+    - lookup    (~£0.02, instant) — cached prior analysis
+    - consensus (~£0.03, instant) — cross-user aggregate landscape (k≥3 checks)
+    - quick     (~£0.07, ~15s) — web search + heuristic classification
+    - full      (~£0.15, ~60-90s) — 30+ sources, LLM classification, coverage recovery
+
+    Charges based on tier actually executed, not tier requested.
+    Set max_tier to control maximum spend per call.
+
+    Output structure:
+    - claims[].claimMap.elements[] — verifiable sub-claims with state
+      (supported/disputed/unresolved)
+    - claims[].claimMap.elements[].evidenceRefs[] — evidence mapped to elements
+      with relationship (supports/challenges/context) and reasoning
+    - claims[].evidence[] — sources classified by tier (primary/reporting/
+      commentary) and type (data/official/news/analysis/opinion/academic)
+    - claims[].claimMap.orientation — mechanical summary from element states
+    - _meta — execution metadata: executedTier, chargedPence, limitations
+
+    Args:
+        claim: A factual claim ("The Earth's average temperature rose 1.1°C
+               since 1880") or an article URL (https://example.com/article).
+               URLs are auto-detected and the pipeline extracts claims from
+               the page content.
+        max_tier: Maximum tier to attempt — "lookup", "consensus", "quick" (default), or "full".
+        max_age_hours: Skip cache hits older than this many hours. If set,
+                       lookup hits that are stale will be discarded and the
+                       pipeline re-runs at the next tier up to max_tier.
+        compact: If True, strip full evidence arrays from response (smaller payload).
+    """
+    client = _get_client()
+    result = await client.submit_with_fallback(
+        claim,
+        max_tier=max_tier,
+        max_age_hours=max_age_hours,
+        compact=compact,
+    )
+    return _format(result)
+
+
+@mcp.tool()
+async def tru8_get_result(check_id: str) -> str:
+    """Retrieve a previously submitted check with pre-computed analytics.
+
+    Returns the full result including a _computed block with tier/type
+    distributions, corroboration groups, diagnostic values, timeline
+    analysis, element state summaries, and per-claim dispositions.
+
+    Use this over tru8_get_result_raw when you want structured analytics
+    ready for summarisation or comparison without post-processing.
+
+    Args:
+        check_id: UUID returned by tru8_check.
+    """
+    client = _get_client()
+    result = await client.get_check(check_id, computed=True)
+    return _format(result)
+
+
+@mcp.tool()
+async def tru8_get_result_raw(check_id: str) -> str:
+    """Retrieve a previously submitted check without computed analytics.
+
+    Returns claims, elements, evidence, and claim maps only. No _computed
+    block. Smaller response payload. Use this when you will compute your
+    own aggregations or only need specific fields from the raw data.
+
+    Args:
+        check_id: UUID returned by tru8_check.
+    """
+    client = _get_client()
+    result = await client.get_check(check_id, computed=False)
+    return _format(result)
+
+
+def main():
+    """Entry point for `python -m tru8_mcp`."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

tru8_mcp-1.0.0/tru8_mcp/tools.py

@@ -0,0 +1,389 @@
+"""Tru8 API client for MCP tool implementations.
+
+Wraps the Tru8 REST API with methods for submitting checks via the
+synchronous /run endpoint (preferred) or agent tier endpoints (L-08).
+"""
+
+import asyncio
+import json
+import logging
+import os
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Pipeline timeouts (seconds)
+PIPELINE_TIMEOUT = 180.0
+GET_TIMEOUT = 30.0
+POLL_INTERVAL = 3.0
+MAX_POLL_DURATION = 300.0
+
+# Tier timeouts — quick is faster, so shorter HTTP timeout
+TIER_TIMEOUTS = {
+    "lookup": 15.0,
+    "consensus": 15.0,
+    "quick": 60.0,
+    "full": PIPELINE_TIMEOUT + 30.0,
+}
+
+# Tier order for fallback
+TIER_ORDER = ["lookup", "consensus", "quick", "full"]
+
+
+class Tru8APIClient:
+    """HTTP client wrapping the Tru8 Evidence Research API.
+
+    Authenticates via API key (X-API-Key header). Supports both the legacy
+    /checks/run endpoint and the agent tier endpoints (/agent/lookup, /quick, /full).
+    """
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ):
+        self.base_url = (
+            api_url or os.environ.get("TRU8_API_URL", "https://api.trueight.com")
+        ).rstrip("/")
+        self.api_key = api_key or os.environ.get("TRU8_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "TRU8_API_KEY environment variable required. "
+                "Create one at your Tru8 dashboard → Settings → Developer."
+            )
+
+    def _headers(self) -> dict:
+        return {"X-API-Key": self.api_key, "Accept": "application/json"}
+
+    @staticmethod
+    def _detect_input_type(claim: str) -> Optional[str]:
+        """Return "url" if claim looks like a URL, else None (server auto-detects)."""
+        if claim.strip().startswith(("http://", "https://")):
+            return "url"
+        return None
+
+    async def submit_tier(
+        self,
+        claim: str,
+        tier: str,
+        compact: bool = False,
+    ) -> dict:
+        """Submit a claim or URL to a specific agent tier endpoint.
+
+        Args:
+            claim: The claim text or article URL to analyse.
+            tier: "lookup", "quick", or "full".
+            compact: If True, strip evidence arrays from response.
+
+        Returns:
+            The tier endpoint response dict (includes _meta block).
+        """
+        timeout = TIER_TIMEOUTS.get(tier, PIPELINE_TIMEOUT)
+        payload: dict = {"claim": claim, "compact": compact}
+        input_type = self._detect_input_type(claim)
+        if input_type:
+            payload["input_type"] = input_type
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout, connect=10.0)
+        ) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/agent/{tier}",
+                json=payload,
+                headers=self._headers(),
+            )
+            if resp.status_code == 402:
+                raise InsufficientBalanceError(f"Insufficient balance for {tier} tier")
+            if resp.status_code not in (200, 201):
+                raise RuntimeError(f"API error {resp.status_code}: {resp.text}")
+            return resp.json()
+
+    async def submit_smart(
+        self,
+        claim: str,
+        max_tier: str = "quick",
+        max_age_hours: Optional[int] = None,
+        compact: bool = False,
+    ) -> dict:
+        """Submit via smart endpoint with server-side fallback (M-03).
+
+        Args:
+            claim: The claim text or article URL to analyse.
+            max_tier: Maximum tier to attempt ("lookup", "quick", or "full").
+            max_age_hours: Skip cache hits older than this many hours.
+            compact: If True, strip evidence arrays from response.
+
+        Returns:
+            The smart endpoint response dict.
+        """
+        timeout = TIER_TIMEOUTS.get(max_tier, PIPELINE_TIMEOUT)
+        payload: dict = {"claim": claim, "max_tier": max_tier, "compact": compact}
+        input_type = self._detect_input_type(claim)
+        if input_type:
+            payload["input_type"] = input_type
+        if max_age_hours:
+            payload["max_age_hours"] = max_age_hours
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout, connect=10.0)
+        ) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/agent/check",
+                json=payload,
+                headers=self._headers(),
+            )
+            if resp.status_code == 402:
+                raise InsufficientBalanceError(
+                    f"Insufficient balance for {max_tier} tier"
+                )
+            if resp.status_code not in (200, 201):
+                raise RuntimeError(f"API error {resp.status_code}: {resp.text}")
+            return resp.json()
+
+    async def submit_with_fallback(
+        self,
+        claim: str,
+        max_tier: str = "quick",
+        max_age_hours: Optional[int] = None,
+        compact: bool = False,
+    ) -> dict:
+        """Submit a claim with tier fallback: lookup → quick → full (up to max_tier).
+
+        Prefers the smart endpoint (M-03). Falls back to client-side tier
+        escalation if the server returns 404 (backward compat with older servers).
+
+        Args:
+            claim: The claim text to analyse.
+            max_tier: Maximum tier to attempt ("lookup", "quick", or "full").
+            max_age_hours: Skip cache hits older than this many hours.
+            compact: If True, strip evidence arrays from response.
+
+        Returns:
+            The response dict from whichever tier succeeded.
+        """
+        # Try smart endpoint first (M-03)
+        try:
+            return await self.submit_smart(
+                claim, max_tier=max_tier, max_age_hours=max_age_hours, compact=compact
+            )
+        except RuntimeError as e:
+            if "404" in str(e):
+                logger.info(
+                    "Smart endpoint not available, falling back to client-side escalation"
+                )
+            else:
+                raise
+
+        # Client-side fallback for older servers
+        max_rank = TIER_ORDER.index(max_tier) if max_tier in TIER_ORDER else 1
+
+        # Always try lookup first
+        try:
+            result = await self.submit_tier(claim, "lookup", compact=compact)
+            if result.get("hit"):
+                return result
+            # Lookup miss — escalate if allowed
+        except InsufficientBalanceError:
+            raise
+        except Exception as e:
+            logger.warning(f"Lookup failed: {e}")
+
+        # Escalate to quick if allowed
+        if max_rank >= TIER_ORDER.index("quick"):
+            try:
+                return await self.submit_tier(claim, "quick", compact=compact)
+            except InsufficientBalanceError:
+                raise
+            except Exception as e:
+                if max_rank >= TIER_ORDER.index("full"):
+                    logger.warning(f"Quick failed, escalating to full: {e}")
+                else:
+                    raise
+
+        # Escalate to full if allowed
+        if max_rank >= TIER_ORDER.index("full"):
+            return await self.submit_tier(claim, "full", compact=compact)
+
+        raise RuntimeError(f"No tier up to {max_tier} returned a result")
+
+    async def submit_check_sync(self, text: str) -> dict:
+        """Submit content via the synchronous /run endpoint and return the full result.
+
+        Backward-compatible alias. For new code, prefer submit_with_fallback().
+        """
+        input_type = (
+            "url" if text.strip().startswith(("http://", "https://")) else "text"
+        )
+        payload = {"input_type": input_type}
+        if input_type == "url":
+            payload["url"] = text.strip()
+        else:
+            payload["content"] = text.strip()
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(PIPELINE_TIMEOUT + 30.0, connect=10.0)
+        ) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/checks/run",
+                json=payload,
+                headers=self._headers(),
+            )
+            if resp.status_code != 200:
+                raise RuntimeError(f"API error {resp.status_code}: {resp.text}")
+            return resp.json()
+
+    async def submit_check_sse(self, text: str) -> str:
+        """Submit content for evidence research and wait for completion.
+
+        Consumes the SSE stream from POST /stream. For URL inputs that pause
+        for claim selection, auto-selects all extracted claims (up to 5) and
+        polls until Phase 2 completes.
+
+        Returns:
+            The completed check ID.
+        """
+        input_type = (
+            "url" if text.strip().startswith(("http://", "https://")) else "text"
+        )
+        payload = {"input_type": input_type}
+        if input_type == "url":
+            payload["url"] = text.strip()
+        else:
+            payload["content"] = text.strip()
+
+        timeout = PIPELINE_TIMEOUT
+        check_id = None
+        awaiting_selection = False
+        claim_positions = []
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout, connect=10.0)
+        ) as client:
+            async with client.stream(
+                "POST",
+                f"{self.base_url}/api/v1/checks/stream",
+                json=payload,
+                headers={**self._headers(), "Accept": "text/event-stream"},
+            ) as response:
+                if response.status_code != 200:
+                    body = await response.aread()
+                    raise RuntimeError(
+                        f"API error {response.status_code}: {body.decode()}"
+                    )
+
+                check_id = response.headers.get("x-check-id")
+
+                async for line in response.aiter_lines():
+                    line = line.strip()
+                    if not line or not line.startswith("data:"):
+                        continue
+                    try:
+                        data = json.loads(line[5:].strip())
+                    except json.JSONDecodeError:
+                        continue
+
+                    event_type = data.get("type")
+
+                    if event_type == "completed":
+                        check_id = check_id or data.get("checkId")
+                        return check_id
+
+                    elif event_type == "error":
+                        raise RuntimeError(
+                            f"Pipeline error: {data.get('error', 'unknown')}"
+                        )
+
+                    elif event_type == "timeout":
+                        raise RuntimeError("Pipeline timed out")
+
+                    elif event_type == "awaiting_selection":
+                        check_id = check_id or data.get("checkId")
+                        # Extract claim positions, preferring highest-ranked
+                        claims = data.get("claims", [])
+                        claims_sorted = sorted(
+                            claims,
+                            key=lambda c: c.get("significance_rank", 999),
+                        )
+                        claim_positions = [
+                            c.get("position", i) for i, c in enumerate(claims_sorted)
+                        ]
+                        awaiting_selection = True
+                        break
+
+                    elif event_type == "connected":
+                        check_id = check_id or data.get("checkId")
+
+        if not check_id:
+            raise RuntimeError("No check ID received from pipeline")
+
+        if awaiting_selection:
+            await self._select_claims(check_id, claim_positions[:5])
+            await self._poll_until_complete(check_id)
+
+        return check_id
+
+    async def _select_claims(self, check_id: str, positions: list[int]) -> None:
+        """Select claims for Phase 2 analysis."""
+        if not positions:
+            positions = [0]
+
+        async with httpx.AsyncClient(timeout=GET_TIMEOUT) as client:
+            resp = await client.patch(
+                f"{self.base_url}/api/v1/checks/{check_id}/select-claims",
+                json={"selected_positions": positions},
+                headers={**self._headers(), "Content-Type": "application/json"},
+            )
+            if resp.status_code not in (200, 202):
+                raise RuntimeError(
+                    f"Claim selection failed ({resp.status_code}): {resp.text}"
+                )
+
+        logger.info(f"Auto-selected {len(positions)} claims for check {check_id}")
+
+    async def _poll_until_complete(self, check_id: str) -> None:
+        """Poll check status until completed or failed."""
+        elapsed = 0.0
+        async with httpx.AsyncClient(timeout=GET_TIMEOUT) as client:
+            while elapsed < MAX_POLL_DURATION:
+                resp = await client.get(
+                    f"{self.base_url}/api/v1/checks/{check_id}",
+                    headers=self._headers(),
+                )
+                if resp.status_code == 200:
+                    status = resp.json().get("status")
+                    if status == "completed":
+                        return
+                    elif status == "failed":
+                        error = resp.json().get("errorMessage", "Pipeline failed")
+                        raise RuntimeError(f"Pipeline failed: {error}")
+
+                await asyncio.sleep(POLL_INTERVAL)
+                elapsed += POLL_INTERVAL
+
+        raise RuntimeError(f"Pipeline did not complete within {MAX_POLL_DURATION}s")
+
+    async def get_check(self, check_id: str, computed: bool = False) -> dict:
+        """Retrieve a completed check by ID.
+
+        Args:
+            check_id: UUID of the check.
+            computed: If True, include _computed analytics block.
+        """
+        params = {"computed": "true"} if computed else {}
+        async with httpx.AsyncClient(timeout=GET_TIMEOUT) as client:
+            resp = await client.get(
+                f"{self.base_url}/api/v1/checks/{check_id}",
+                headers=self._headers(),
+                params=params,
+            )
+            if resp.status_code != 200:
+                raise RuntimeError(f"API error {resp.status_code}: {resp.text}")
+            return resp.json()
+
+
+class InsufficientBalanceError(RuntimeError):
+    """Raised when the agent's credit balance is insufficient for the requested tier."""
+
+    pass