Metadata-Version: 2.4
Name: tesoro
Version: 0.1.1
Summary: Autonomous Economic Governance Layer — decide, cap and prove what an autonomous agent spends
Author: Jayzilva
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/aegoll/tesoro
Project-URL: Documentation, https://aegoll.github.io/tesoro/
Project-URL: Standard, https://github.com/aegoll/aegs
Project-URL: Examples, https://github.com/aegoll/tesoro-integrations
Project-URL: Changelog, https://github.com/aegoll/tesoro/blob/main/CHANGELOG.md
Keywords: agent,governance,budget,spend-control,x402,autonomous,payments,audit,aegs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: schema
Requires-Dist: jsonschema>=4.20; extra == "schema"
Provides-Extra: x402
Requires-Dist: x402[evm,httpx]>=2.18.0; extra == "x402"
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1; extra == "claude"
Provides-Extra: adk
Requires-Dist: google-adk>=1.0; extra == "adk"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == "crewai"
Provides-Extra: advisors
Requires-Dist: anthropic>=0.40; extra == "advisors"
Requires-Dist: openai>=1.50; extra == "advisors"
Requires-Dist: google-genai>=0.3; extra == "advisors"
Requires-Dist: groq>=0.13; extra == "advisors"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Dynamic: license-file

# tesoro

**Know what your autonomous agent spends, cap it across time, and be able to prove why
anything was refused.**

`tesoro` is an *Autonomous Economic Governance Layer* (AEGL): it sits between an agent and
every dollar it spends — the tokens it burns thinking and the money it pays out — and
decides, before the payment, whether it should happen. Ten deterministic engines, no model
in the decision path, an append-only hash-chained record of every decision and the control
that made it.

**📖 [Documentation](https://aegoll.github.io/tesoro/)** — what an AEGL is, the architecture,
policies and rules, framework adapters, and the AEGS standard.

```bash
pip install tesoro
tesoro init
```

```python
from tesoro import Governor

gov = Governor.load()                     # reads ./tesoro.yaml
decision = gov.authorize(amount_usd="2.50", vendor="acme", resource="/market/snapshot")

if decision.approved:
    pay(...)                              # your payment call, on any rail
    gov.settle(decision, success=True)    # envelopes consume here, not above
else:
    print(decision.verdict, decision.attributed_control, decision.reason)
```

Or from the terminal, which is the same layer and the same evidence:

```bash
tesoro check                                    # validate before an agent holds a wallet
tesoro decide --amount 2.50 --vendor acme --resource /market/snapshot
echo $?                                         # 0 approved · 2 refused · 1 invalid · 3 chain · 4 usage
tesoro report --html -o spend.html              # one self-contained page, no server
```

Start with [`docs/quickstart.md`](https://github.com/aegoll/tesoro/blob/main/docs/quickstart.md).

> **Status: pre-release.** Nothing is published yet. Ported from a working prototype and now
> at **597 tests**, a 7/7 [AEGS](https://github.com/aegoll/aegs) conformance score with both
> levels claimable, and **151 specification test vectors executing** against 56 normative
> clauses. See [`PLAN.md`](https://github.com/aegoll/tesoro/blob/main/PLAN.md) and [`CHANGELOG.md`](https://github.com/aegoll/tesoro/blob/main/CHANGELOG.md).

---

## A cap on one payment is not a budget

Per-payment caps are becoming table stakes; the x402 SDKs now ship one. `tesoro` is about
what a single cap cannot express:

| | A per-payment cap | `tesoro` |
|---|---|---|
| One transaction too large | ✅ | ✅ |
| Cumulative spend over a day, a month, a window | — | ✅ |
| Per-vendor and per-resource ceilings | — | ✅ |
| Velocity, and the *shape* of a sequence | — | ✅ (in progress) |
| Counterparty trust earned over settlements | — | ✅ |
| Whether this spend matches what the agent was **sent to do** | — | ✅ |
| Which control refused, recorded as evidence | — | ✅ |
| Tamper-evident decision history | — | ✅ |
| Policy as a reviewable, versioned, hashed file | — | ✅ |

Forty payments of one cent each pass every per-payment cap ever written. That is the
problem this layer exists for.

## Two channels, never one budget

An agent spends in two directions, and they are not the same money:

- **internal** — the tokens it burns thinking. Real currency, on your provider key.
- **external** — what it pays out. Settled to a counterparty.

Different currencies, different counterparties, different failure modes. They never share an
envelope. An exhausted token budget must *reject*, not queue for review: there is no human
to ask mid-run, and starting a run that cannot finish wastes the budget that is already short.

## Design commitments

These are not preferences. Each is enforced by a test.

- **No model in the decision path.** Every engine is deterministic integer arithmetic over
  structured values. An optional advisor may be consulted behind an economic gate and is
  *clamped* — it can tighten a verdict, never widen one. A governance layer that needs a
  model to authorize a payment has lost its cost and latency guarantees.
- **Policy is data, never code.** Declarative rules, a fixed comparator vocabulary, no
  `eval`. This is a security boundary: an executable policy file fetched from a registry is
  remote code execution wearing a governance hat.
- **Money never touches a float.** Integer atomic units internally; conversion happens once
  at the boundary with an explicitly specified rounding mode. Passing a `float` raises.
- **Absent ≠ not-run ≠ unknown ≠ zero.** Four distinct states. An unmeasured vendor history
  rendered as `0` once made every advisor treat established counterparties as strangers.
- **Every control may only narrow.** No engine can widen a verdict another one set.
- **Evidence is append-only and hash-chained**, with its one known gap documented rather
  than papered over.
- **CLI first.** The terminal is the product surface; the optional localhost page comes
  later, binds `127.0.0.1` only, and is off unless you start it.

## AEGS

`tesoro` is a **policy-engine host**. [AEGS](https://github.com/aegoll/aegs) — the
Autonomous Economic Governance Standard — is one *profile* it can enforce, and the default.
Pick it and your agent emits conformant, scoreable Decision Records without your ever having
read the specification.

A **profile** says which controls must exist and what evidence must be emitted; that is
written by the standard. A **policy pack** says what the rules actually are; that is written
by you.

## Repositories

| | |
|---|---|
| [`tesoro`](https://github.com/aegoll/tesoro) | this package |
| [`aegs`](https://github.com/aegoll/aegs) | the standard: spec, schemas, vectors, conformance |
| [`tesoro-integrations`](https://github.com/aegoll/tesoro-integrations) | example agents, frameworks, use cases |
| [`Jayzilva/x402`](https://github.com/Jayzilva/x402) | the proof-of-concept this grew from. Read-only |

## Documentation

- [`docs/quickstart.md`](https://github.com/aegoll/tesoro/blob/main/docs/quickstart.md) — governing an agent from nothing, in about five minutes
- [`docs/api-surface.md`](https://github.com/aegoll/tesoro/blob/main/docs/api-surface.md) — the public API, and what is deliberately not public
- [`docs/adapters.md`](https://github.com/aegoll/tesoro/blob/main/docs/adapters.md) — framework and rail adapters, and what is verified about each
- [`PLAN.md`](https://github.com/aegoll/tesoro/blob/main/PLAN.md) — the build plan, as tracked checkboxes
- [`PROVENANCE.md`](https://github.com/aegoll/tesoro/blob/main/PROVENANCE.md) — what was ported from the prototype, and from which commit

## What is not established

Read this before quoting anything. AML/CFT effectiveness is a schema with no engine behind
it. No regulatory compliance is claimed or sought. Every measurement so far is one run or a
handful, single-agent, on testnet. The conformance suite has never scored an implementation
nobody here wrote — that is the open question it exists to answer. Three red-team findings
are open by design, each needing a control that does not yet exist.

The red team's verdict on this layer's own central claim, kept because it is the fairest
summary available: *the layer resists prose; it did not resist a minus sign, and it does not
yet resist patience.*

## Licence

Apache-2.0. The patent grant matters for anything with standards ambition.
