Metadata-Version: 2.4
Name: cognilateral-trust
Version: 1.2.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

### TrustBench
- **Scoring** — expected calibration error (ECE) measurement
- **Fingerprint** — radial calibration profile per model/domain
- **CLI** — `trust-check run`, `trust-check fingerprint`
- **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.

## 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 | 41 |
| Tests | Run `uv run pytest -q` for current count |
| External dependencies | 0 |
| Python | 3.11+ |
| Version | 1.1.0 |

## License

Apache-2.0
