cognilateral-trust 1.3.0

Epistemic trust layer for AI agents — confidence tiers, routing, and accountability

cognilateral-trust

Epistemic trust layer for AI agents. AI that tells you when it's guessing.

pip install cognilateral-trust

Zero external dependencies. Python 3.11+.

Quick Start

from cognilateral_trust import evaluate_trust

result = evaluate_trust(0.7)
if result.should_proceed:
    perform_action()
else:
    escalate(result.accountability_record.reasons)

Confidence Tiers (C0-C9)

Tier	Name	Route
C0-C3	Unverified to Measured	basic — straight-through
C4-C6	Tested to Falsifiable	warrant_check — evidence required
C7-C9	Governance to Resilient	sovereignty_gate — full evaluation

Features

Core

• evaluate_trust() — confidence to tier to verdict (ACT/ESCALATE)
• @trust_gate — one-line trust enforcement decorator
• extract_confidence() — parse confidence from text, OpenAI, or Anthropic responses
• CalibratedTrustEngine — learning loop with JSONL persistence

Verification

• Claims extraction — factual, causal, comparative, quantitative
• Fidelity verification — word-overlap source checking
• Epistemic firewall — confidence mismatch detection (7-tier)
• Sovereignty gate — D-07 with D-05 welfare hard constraint

Network Primitives

• Trust decay — confidence attenuates across agent handoffs
• Contagion detection — track low-trust claim propagation
• Trust-weighted consensus — Bayesian composition, not majority vote
• Sovereign worker — leaf-level self-governance (D-07 at edge)
• Provenance chain — cryptographic accountability ledger

User Consent

• Sensitivity — end user controls trust threshold: "low", "default", "high"
• Nutrition label — every evaluation includes a structured disclosure (schema v1.0.0)

TrustBench (Calibration Benchmark)

• 200 scenarios across 5 domains: factual, reasoning, ambiguous, out-of-distribution, adversarial
• ECE scoring — expected calibration error measurement
• Adapters — plug any model (Ollama, OpenAI, Anthropic, custom callable)
• Fingerprint — radial calibration profile per model/domain
• Leaderboard — self-contained HTML ranking

Integrations

• LangGraph — TrustNode for StateGraph + conditional edges
• CrewAI — TrustTool implementing the Tool protocol
• OpenClaw — TrustProvider for always-on agent governance
• Cognee — trust scoring on knowledge graph edges

MCP Server

Zero-install trust evaluation as an MCP tool:

uvx cognilateral-trust-mcp

Exposes trust_evaluate, trust_extract_confidence, and trust_health over stdio JSON-RPC 2.0.

Calibration Results (TrustBench v1.0.0)

200 scenarios across 5 epistemic domains. Higher = better calibrated (1.0 = perfect).

Model	Type	Overall
qwen3:8b	General	0.51
qwen3:32b	General	0.50
qwen2.5-coder:7b	Code	0.42
qwen2.5-coder:32b	Code	0.33

Findings:

1. General models score ~0.50 — confidence correlates with correctness about half the time
2. 4x larger model is no better calibrated (0.50 vs 0.51)
3. Code-specialized models are worse (0.33-0.42) — specialization harms epistemic honesty
4. The larger coder (32b) is the worst of all four models

Reproduce: BenchRunner(OllamaAdapter("qwen3:8b")).run("qwen3:8b")

Nutrition Label

Every trust_evaluate() response includes a structured disclosure:

{
  "nutrition_label": {
    "confidence": 0.87,
    "tier": 8,
    "tier_name": "C8",
    "calibration_score": null,
    "sensitivity": "default",
    "evidence_count": 0,
    "escalation_risk": "none",
    "version": "1.0.0"
  }
}

Like an FDA nutrition label, but for AI confidence. Schema v1.0.0.

User Sensitivity

The person downstream controls how cautious the trust engine is:

# Default: standard thresholds
result = evaluate_trust(0.6)  # may proceed

# High sensitivity: stricter — user wants more caution
result = evaluate_trust(0.6, sensitivity="high")  # likely escalates

# Low sensitivity: relaxed — user accepts more risk
result = evaluate_trust(0.6, sensitivity="low")  # likely proceeds

Sensitivity shifts the proceed/escalate threshold without changing the tier. C7 is always C7.

Examples

See examples/ for runnable demos including a Colab notebook.

Example	Description
demo_trust_agent.py	End-to-end agent with trust gating and calibration
langgraph_trust_agent.py	LangGraph agent with trust node
crewai_trust_tool.py	CrewAI tool integration
anthropic_trust_wrapper.py	Anthropic API with trust evaluation
openai_trust_wrapper.py	OpenAI API with trust evaluation

Package Stats

Metric	Value
Modules	44
Tests	Run uv run pytest -q for current count
External dependencies	0
Python	3.11+
Version	1.2.0
TrustBench scenarios	200
Calibration score (qwen3:8b)	0.51

License

Apache-2.0