Getting Started with TruthGate

TruthGate installs with zero external core dependencies on Python 3.11+ and exposes a CLI, Python SDK, Stdio MCP server, and local HTTP Workbench.

Install & Demo

uvx --from git+https://github.com/codesphere-u/truthgate truthgate demo

pip install git+https://github.com/codesphere-u/truthgate.git

pip install -e ".[server]"

CLI Subcommands

• truthgate demo — Runs the 4-claim audit & surgical self-correction demo.
• truthgate benchmark [--json] — Runs all 40 deterministic precision/recall/latency scenarios.
• truthgate verify --response ... --sources-json ... --workspace . --fail-on-violation — CI gate command.
• truthgate ground --response ... --workspace . — Verifies paths, line numbers, and AST symbols.
• truthgate mcp / truthgate serve-http — Starts Stdio or Streamable HTTP MCP servers.

Python SDK & Grounding Engine

Import TruthGateVerifier and SourceDocument inside any RAG pipeline or multi-agent retry loop.

TruthGateVerifier

from truthgate import SourceDocument, TruthGateVerifier

sources = [
    SourceDocument(
        source_id="sec_policy",
        title="TLS Policy",
        content="TLS 1.0 is not permitted in production environments.",
    )
]
result = TruthGateVerifier().verify(
    response_text="TLS 1.0 is permitted in production environments [sec_policy].",
    sources=sources,
)
assert not result.passed
print(result.repair_prompt)

WorkspaceSymbolGrounder

Validates markdown code references across Python ASTs and TypeScript/JavaScript/Go/Rust symbol tables with path-traversal protection.

Model Context Protocol (MCP) Server

Connect TruthGate directly to Claude Desktop, Cursor, or Antigravity via JSON-RPC 2.0 Stdio or Streamable HTTP.

Tools & Resources

• truthgate_verify_response — Full entailment + workspace grounding + surgical repair prompt.
• truthgate_ground_workspace_refs — File, line-range, and AST symbol checker (`TG006`–`TG008`).
• truthgate_list_rules — Returns structured metadata for TG001–TG008.
• truthgate_run_benchmark — Executes the 40-scenario benchmark suite via MCP.
• Resources: truthgate://rules, truthgate://benchmark/scenarios, truthgate://docs/architecture.

Built-in Prompts

Exposes audit-response, ground-workspace, and surgical-repair prompt templates over prompts/list.

HTTP Workbench & REST API

Launch the local server with truthgate serve-http --host 127.0.0.1 --port 8000 or deploy via api/index.py (FastAPI ASGI).

REST & Observability Endpoints

• GET / — Interactive Workbench UI when Accept: text/html, service JSON otherwise.
• GET / HEAD /health, /healthz, /readyz, /info & /metrics (Prometheus or JSON).
• POST /mcp & GET /mcp (SSE) — Streamable HTTP MCP transport.
• GET /api/rules, /api/demo, /api/benchmark & POST /api/verify, /api/ground, /api/decompose.

Docker & Quality Gates

75 unit and HTTP integration tests pass with ≥90% coverage alongside strict ruff, mypy truthgate api scripts, pip-audit, and non-root Docker verification.