Metadata-Version: 2.4
Name: sentinel-trust-oracle
Version: 0.1.0
Summary: Behavioral trust gating for autonomous agent payments — spend governance and an audit trail over the SENTINEL oracle. Framework-agnostic core with a LangChain adapter.
Project-URL: Homepage, https://sentinel-agent.dev
Project-URL: Whitepaper, https://sentinel-agent.dev/whitepaper
Project-URL: Methodology, https://sentinel-agent.dev/methodology
Project-URL: Repository, https://github.com/teodorofodocrispin-cmyk/sentinel-trust-oracle
Author: Ivar Garcés
License: MIT
License-File: LICENSE
Keywords: agent-safety,agentic-payments,ai-agents,audit-trail,langchain,middleware,oracle,sentinel,trust,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Requires-Dist: langchain>=1.0.0; extra == 'langchain'
Description-Content-Type: text/markdown

# sentinel-trust-oracle

**Behavioral trust gating for autonomous agent payments.** Before your agent pays an x402 counterparty, `sentinel-trust-oracle` checks whether that counterparty is trustworthy, enforces spend limits, and records every decision to an append-only audit trail — the spend governance, guardrails, and traceability that production agent payments need.

Framework-agnostic core; ships a **LangChain** adapter today.

```bash
pip install "sentinel-trust-oracle[langchain]"
```

## Why this exists

Agents that pay for APIs today do it one of two unsafe ways: hardcoded credentials with no spend governance and no audit trail, or pre-authorized unlimited spend. Neither is production-safe — an agent in a loop, or a prompt-injected one, can drain a budget or pay a malicious counterparty in seconds.

`sentinel-trust-oracle` closes that gap. It gates each payment on a **behavioral trust score** from the [SENTINEL oracle](https://sentinel-agent.dev) — trust derived from *verifiable conduct* (did this counterparty pay, deliver, and price honestly?), not from gameable reputation — and wraps it in the governance a real deployment requires. The reasoning is set out in the [Recomputable Trust whitepaper](https://sentinel-agent.dev/whitepaper).

## LangChain usage

```python
from langchain.agents import create_agent
from sentinel_trust_oracle import SentinelOracleMiddleware

agent = create_agent(
    model="gpt-4o",
    tools=[pay_for_api],  # your x402 payment tool
    middleware=[
        SentinelOracleMiddleware(
            min_score=60,           # require SENTINEL trust score >= 60 to pay
            daily_limit_usdc=10,    # cap total daily spend
            per_call_limit_usdc=1,  # cap any single payment
            fail_closed=True,       # if trust can't be verified, block (default)
            payment_tools=["pay_for_api"],  # which tools to gate
        )
    ],
)
```

The middleware intercepts each gated tool call, extracts the counterparty (and amount) from its arguments, checks the oracle, and either lets the payment proceed or blocks it with an explanatory message the agent can read. Every decision — pass or block — is recorded:

```python
mw = SentinelOracleMiddleware(min_score=60)
# ... after the agent runs ...
for entry in mw.audit_trail:
    print(entry["timestamp"], entry["subject"], entry["decision"], entry["reason"])
```

## Framework-agnostic core

The trust gate is pure Python (standard library only — **zero runtime dependencies** in the core) and can be used without any framework:

```python
from sentinel_trust_oracle import TrustGate, TrustQuery

gate = TrustGate(min_score=60, daily_limit_usdc=10)
verdict = gate.check(TrustQuery(subject="0xCf1d...", amount_usdc=1.0))

if verdict.decision.value == "PASS":
    ...  # proceed with payment
else:
    print(verdict.reason)          # why it was blocked
    print(verdict.evidence_uri)    # link to recomputable evidence
```

This design means adapters for other frameworks (CrewAI, AutoGen, …) are thin wrappers over the same core.

## How the decision is made

1. **Spend guardrails first.** A payment over the per-call or daily limit is blocked before the oracle is even queried.
2. **Trust check.** The oracle returns a 0–100 behavioral trust score for the counterparty. `score >= min_score` → PASS; below → FAIL.
3. **Fail-closed by default.** If the oracle can't be reached or has no score, the gate blocks (configurable via `fail_closed`).
4. **Audit trail.** Every decision is appended to an in-memory, JSON-serializable trail, and optionally forwarded to an `audit_sink` callable for external logging.

## Configuration

| Parameter | Default | Meaning |
|---|---|---|
| `min_score` | `60` | Minimum SENTINEL trust score (0–100) to allow a payment |
| `daily_limit_usdc` | `None` | Max total USDC approved per calendar day |
| `per_call_limit_usdc` | `None` | Max USDC for any single payment |
| `fail_closed` | `True` | Block when trust can't be verified |
| `payment_tools` | `None` | Tool names to gate; `None` gates every tool with a counterparty arg |
| `subject_keys` | common set | Tool-arg names to read the counterparty address from |
| `amount_keys` | common set | Tool-arg names to read the payment amount from |
| `base_url` | SENTINEL prod | Oracle endpoint |

## Compliance note

The append-only audit trail and signed-attestation evidence this package surfaces are designed to support the record-keeping and traceability that emerging agentic-AI regulation calls for (e.g. EU AI Act Art. 12 tamper-evident logging, Singapore IMDA audit trails). See [sentinel-agent.dev/compliance](https://sentinel-agent.dev/compliance). This is engineering tooling, not legal advice, and it does not by itself make any system compliant.

## Links

- SENTINEL oracle: https://sentinel-agent.dev
- Whitepaper — *Recomputable Trust*: https://sentinel-agent.dev/whitepaper
- Methodology: https://sentinel-agent.dev/methodology
- Compliance mapping: https://sentinel-agent.dev/compliance

## License

MIT
