Metadata-Version: 2.4
Name: agledger
Version: 0.8.6
Summary: AGLedger SDK — Accountability and audit infrastructure for agentic systems.
Author-email: AGLedger LLC <support@agledger.ai>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: accountability,agents,agledger,audit,records
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: pydantic<3,>=2.0.0
Provides-Extra: dev
Requires-Dist: cbor2>=5.6; extra == 'dev'
Requires-Dist: cryptography>=42.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Provides-Extra: verify
Requires-Dist: cbor2>=5.6; extra == 'verify'
Requires-Dist: cryptography>=42.0; extra == 'verify'
Description-Content-Type: text/markdown

# AGLedger Python SDK

The official Python SDK for [AGLedger](https://agledger.ai) — accountability infrastructure for AI agents. Self-hosted. The Layer 3 accountability layer of the agent stack.

**Learn more**

- [agledger.ai](https://agledger.ai) — what AGLedger is and why Layer 3 accountability matters
- [How it works](https://agledger.ai/how-it-works) — the four-endpoint lifecycle: Record, Completion, Verdict, fulfill
- [Glossary](https://agledger.ai/glossary) — canonical definitions of Record, Completion, SCITT Receipt, Verdict, Settlement Signal
- [Documentation](https://agledger.ai/docs) — installation, integration guides, API reference
- [Protocol (AOAP)](https://agledger.ai/protocol) — the coordination language behind AGLedger

## Install

```bash
pip install agledger
```

## Quick Start

```python
import os
from agledger import AgledgerClient

client = AgledgerClient(
    api_key=os.environ["AGLEDGER_API_KEY"],
    base_url=os.environ["AGLEDGER_EXTERNAL_URL"],  # your AGLedger instance URL
)

# Create a Record. An agent key defaults the principal to itself; an admin
# key names the principal explicitly via principal_agent_id.
record = client.records.create(
    type="ACH-PROC-v1",
    contract_version="1",
    platform="internal",
    performer_agent_id="agt-123",
    criteria={"item_spec": "widgets", "quantity": {"target": 100}},
)

# Activate it
client.records.transition(record.id, "activate")

# Submit a completion
completion = client.completions.submit(
    record.id,
    evidence={"deliverable": "/out.pdf", "deliverable_type": "file_ref", "quantity_supplied": 95},
)

# Principal verdict
client.records.submit_verdict(record.id, completion_id=completion.id, verdict="accept")
```

## Configuration

```python
client = AgledgerClient(
    api_key="agl_agt_...",                              # or set AGLEDGER_API_KEY env var
    base_url="https://agledger.internal.example.com",   # your instance URL
    max_retries=2,                                      # default: 2
    timeout=30.0,                                       # default: 30s
)
```

## Async Support

```python
from agledger import AsyncAgledgerClient

async with AsyncAgledgerClient() as client:
    record = await client.records.get("rec-123")
```

## Resources

`records`, `completions` (formerly `receipts`), `verification`, `disputes`,
`webhooks`, `reputation`, `events`, `schemas`, `compliance`, `health`, `admin`
(with `admin.records` + `admin.vault` sub-resources), `a2a`, `agents`, `audit`
(with `audit.org_reads_checkpoints` and `audit.vault_checkpoints`), `auth`,
`capabilities`, `discovery`, `references`, `federation`, `federation_admin`,
`verification_keys`, `scitt` (SCITT/SCRAPI entries + Transparency Service keys),
`predicates` (predicate schema discovery).

## Webhook Verification

Webhooks ship in two signing schemes, selected per subscription via `signing_alg`.

**HMAC** (`signing_alg="hmac"`, the default) — shared-secret HMAC-SHA256:

```python
from agledger.webhooks import verify_signature

is_valid = verify_signature(raw_body, request.headers["x-agledger-signature"], webhook_secret)
```

**Ed25519** (`signing_alg="ed25519"`) — RFC 9421 HTTP Message Signatures signed
with the Server's vault key. The receiver holds no secret and verifies against
the Server's published public key, giving non-repudiation for the Settlement
Signal hop. Settlement-event subscriptions default to this when the Server has a
vault signing key.

```python
from agledger.webhooks import verify_rfc9421

# Resolve the Server's published keys once (cache them); the delivery's
# keyid is matched against them automatically.
keys = client.verification_keys.list().data

is_valid = verify_rfc9421(
    request.headers,  # must include content-digest, signature-input, signature, x-agledger-idempotency-key
    raw_body,
    keys,             # or a single base64 public key string
)
```

`verify_rfc9421` recomputes the RFC 9530 Content-Digest, reconstructs the RFC 9421
signature base, verifies the Ed25519 signature, and enforces the `created` replay
window (default/max 300s). `construct_event_rfc9421` verifies and parses in one
step. The ed25519 path needs the `cryptography` extra (`pip install 'agledger[verify]'`).

## Offline Audit Export Verification

Verify a Record's hash-chained, Ed25519-signed audit export without calling the API:

```python
from agledger.verify import verify_export

export_data = client.records.get_audit_export("rec-123")
result = verify_export(export_data.model_dump(by_alias=True))

if not result.valid:
    print(f"Broken at position {result.broken_at.position}: {result.broken_at.reason}")
# VerifyExportResult(valid=True, verified_entries=12, total_entries=12, ...)
```

Requires `cbor2` (for COSE_Sign1 decoding) and `cryptography` (for Ed25519
verification):

```bash
pip install 'agledger[verify]'
```

Rewritten in 0.8.0 to decode canonical COSE_Sign1 envelopes (RFC 9052), walk the
hash chain, and verify Ed25519 signatures. Format 2.0 (was 1.0 JCS + detached
Ed25519). Pass `public_keys={...}` to override the export's embedded keys, or
`require_key_id="key-id"` to reject exports signed by an unexpected key.

## SCITT / SCRAPI

Register Signed Statements with the Transparency Service and retrieve Transparent
Statements (Signed Statement + Receipt(s)):

```python
receipt = client.scitt.entries.register(signed_statement)
# COSE_Sign1 Merkle inclusion proof per draft-ietf-cose-merkle-tree-proofs-18

transparent = client.scitt.entries.get(entry_id)
# Transparent Statement: Signed Statement with one or more Receipts embedded

keys = client.scitt.keys.list()
# COSE_KeySet of the Transparency Service's signing keys
```

Wire format is binary `application/cose`. Errors surface as RFC 9290 CBOR
problem-details on `APIError.raw_body`.

## Predicate Schemas

Fetch the canonical JSON Schemas for each predicate kind (record-state,
settlement-signal, vault-checkpoint, schema-event, org-read,
counter-attestation, federation-projection):

```python
kinds = client.predicates.list()
schema = client.predicates.get("settlement-signal")
```

## Attestation Export

Pull a Record's chain as a tagged COSE_Sign1 stream or a sigstore-bundle v0.3.2
projection for Rekor / in-toto / sigstore-policy-controller ingest:

```python
cose_sequence = client.records.get_attestation(record_id)
# application/cose-sequence bytes (tagged COSE_Sign1 stream)

bundle = client.records.get_attestation_bundle(record_id)
# sigstore-bundle v0.3.2 projection
```

## Vault Checkpoints

Per-record signed Merkle anchors are emitted every 6 hours, letting an auditor
detect audit-vault TRUNCATE / DELETE tampering offline:

```python
checkpoints = client.audit.vault_checkpoints.list(record_id="rec-123")
```

## Licensing

AGLedger is **free for single-node deployments** (Docker Compose with bundled database). An Enterprise License is required for external database connections, federation, and multi-node deployments.

Full details: [agledger.ai/pricing](https://agledger.ai/pricing) | [License Agreement](https://agledger.ai/license)

## SDK License

Proprietary. Copyright (c) 2026 AGLedger LLC. All rights reserved.
