Metadata-Version: 2.4
Name: aga-governance
Version: 0.2.3
Summary: AGA Python SDK - Cryptographic governance receipts for AI agent tool calls
Author: Attested Intelligence Holdings LLC
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,cryptographic,governance,receipts
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Requires-Dist: pynacl>=1.5.0
Description-Content-Type: text/markdown

# AGA Python SDK

Cryptographic governance receipts for AI agent tool calls. This SDK emits the
**canonical SEP evidence bundle** — the same offline-verifiable artifact the
AGA gateway produces — so a governance decision sealed in Python re-derives,
byte-for-byte, under the independent reference verifiers.

PyPI distribution: `aga-governance`.

## What the SDK emits

Each governed tool call becomes a signed, 15-field governance receipt. Receipts
hash-link into an append-only chain, the chain's leaves bind into a Merkle root,
and a gateway-signed checkpoint binds the root, leaf count, and chain head so
truncation is detectable. The bundle uses standard primitives only:

- **Ed25519** receipt signatures (RFC 8032).
- **SHA-256** for hash chaining, Merkle trees, and leaf computation.
- **JCS-lineage canonicalization** — deterministic, byte-compatible with the
  reference verifier and with the TypeScript and Go implementations.
- A **no-prefix** binary Merkle tree with a **mandatory signed checkpoint**
  (the construction is frozen in the `aga-receipt-spec` repository).

## Install

```bash
pip install aga-governance
```

## Quick Start

```python
from aga import AgentSession

SEED = bytes.fromhex("cc" * 32)  # 32-byte signing seed (provision securely)

with AgentSession(gateway_id="my-gateway", signing_key_seed=SEED) as session:
    session.record_tool_call(
        tool_name="read_file",
        decision="PERMITTED",
        reason="allowed by policy",
        request_id="req-001",
    )
    bundle = session.export_bundle()      # a canonical SEP evidence bundle (dict)
    result = session.verify()
    assert result["overall_valid"]
```

## Offline verification

A Python-produced bundle verifies under the three independent reference verifiers
(JavaScript, Go, and Python) with no network and no dependency on the producer: the
SDK's canonicalization and leaf computation are pinned to the same cross-language
conformance vectors, so a bundle sealed here re-derives byte-for-byte under each. The
SDK's own `verify()` enforces the same strict conformance rules as those reference
verifiers — exact-key schema, canonical timestamps and ordering, envelope consistency,
strict-hex Merkle proofs, and a mandatory signed checkpoint — so it agrees with them
verdict-for-verdict rather than being a looser convenience check. Pin the gateway public
key to also prove *who* issued the bundle; without a pinned key you get an
integrity-only result.

```bash
# Using the JavaScript reference verifier from the spec repo:
node aga-receipt-spec/verify/verify-sep.mjs bundle.json --pubkey <gateway-public-key>
```

## Scope — what a verified bundle proves

A verified bundle proves the **integrity of the receipts present**: each is
authentic, correctly ordered, Merkle-included, and (when a key is pinned)
provenance-bound. It does **not** prove the policy was correct, and it does not
prove non-omission — completeness of capture is bounded by the tamper-evidence
of the interception point, which is outside the bundle. The offline-verifiable
artifact a counterparty receives is payload-excluded (it carries an
`arguments_hash`, never the raw payload). We prove the record, not that the
policy was correct.

## Tests

The SDK ships 185 automated tests (`python -m pytest`), including the
cross-stack conformance vectors that prove byte-for-byte agreement with the
JavaScript and Go implementations.

## License

Apache-2.0. Patent Pending.
