Metadata-Version: 2.4
Name: cognilateral-trust
Version: 1.3.0
Summary: Epistemic trust layer for AI agents — confidence tiers, routing, and accountability
Project-URL: Homepage, https://cognilateral.com
Project-URL: Repository, https://github.com/heymumford/cognilateral-trust
License-Expression: Apache-2.0
Keywords: agents,ai,confidence,epistemic,routing,trust
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# cognilateral-trust

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

```bash
pip install cognilateral-trust
```

Zero external dependencies. Python 3.11+.

## Quick Start

```python
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:

```bash
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:

```json
{
  "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:

```python
# 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/`](examples/) for runnable demos including a [Colab notebook](examples/trust_demo.ipynb).

| 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
