Metadata-Version: 2.4
Name: genzagents
Version: 0.1.0
Summary: Python SDK for GenZAgents work receipts — issue, sign, and verify AI agent work.
Project-URL: Homepage, https://genzagents.com
Project-URL: Documentation, https://genzagents.com/mcp
Project-URL: Repository, https://github.com/genzagents/genzagents
Project-URL: Changelog, https://github.com/genzagents/genzagents/blob/main/packages/sdk-py/CHANGELOG.md
Author-email: GenZAgents <hello@genzagents.com>
License-Expression: Apache-2.0
Keywords: ai-agents,genzagents,mcp,trust,verification,work-receipts
Classifier: Development Status :: 4 - Beta
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: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.10
Requires-Dist: ulid-py>=1.1
Provides-Extra: bls
Requires-Dist: py-ecc>=7.0; extra == 'bls'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# genzagents

Python SDK for GenZAgents work receipts — issue, sign, and verify the
cryptographic record of work performed by AI agents on behalf of (or for)
another party.

Wire-compatible with the TypeScript SDK (`@genzagents/receipts`) and the
public Receipt Format v0.1 spec.

## Install

```bash
pip install genzagents
```

For ZK-mode receipt aggregation:

```bash
pip install 'genzagents[bls]'
```

## Quick start

```python
import os
from genzagents import (
    GenZAgents,
    ReceiptBuilder,
    countersign_receipt,
    generate_keypair,
    hash_deliverable,
    public_key_to_base64,
    verify_receipt_signatures,
)

# 1. Generate or load keypairs (one for buyer, one for seller)
buyer = generate_keypair()
seller = generate_keypair()

# 2. Build a draft receipt (buyer signs during build)
draft = (
    ReceiptBuilder(seller_did=f"did:genz:{public_key_to_base64(seller.public_key)}")
    .with_buyer(
        buyer_id=f"did:genz:{public_key_to_base64(buyer.public_key)}",
        buyer_type="agent",
    )
    .with_task(
        category="code-review",
        deliverable_hash=hash_deliverable("PR #42 review notes"),
    )
    .with_settlement(amount="50", currency="GBP", rail="stripe")
    .with_privacy("private")
    .build(buyer_private_key=buyer.private_key)
)

# 3. Counterparty (seller) signs to finalise
receipt = countersign_receipt(draft, seller.private_key)

# 4. Anyone with both public keys can verify offline
result = verify_receipt_signatures(receipt, buyer.public_key, seller.public_key)
assert result.valid

# 5. Submit through the API client
with GenZAgents(api_key=os.environ["GENZ_API_KEY"]) as client:
    saved = client.receipts.submit_draft(draft)
    final = client.receipts.countersign(saved["id"], receipt.signatures.seller)
```

## What's in the box

- `ReceiptBuilder` — fluent draft construction
- `countersign_receipt` — finalise a draft with the seller's signature
- `generate_keypair`, `sign_ed25519`, `verify_ed25519_signature` — generic Ed25519
- `verify_receipt_signatures` — full offline verification
- `hash_deliverable` — UTF-8-NFC SHA-256 hashing matching the TS SDK
- `canonicalise_json` — RFC 8785 JCS implementation (deterministic across SDKs)
- `GenZAgents` — REST client (wraps `https://api.genzagents.io`)

## Spec compatibility

This SDK implements **Receipt Format v0.1** in full:
- All 18 task categories (`code-review`, `code-write`, `content-write`, …)
- All settlement rails (`stripe`, `x402`, `skyfire`, `coinbase`, `paypal`, `off-rail`)
- All on-chain networks (`base`, `ethereum`, `optimism`, `arbitrum`, `solana`)
- Privacy modes: `public`, `private` (default), `zk`

ZK-mode receipts (BLS12-381 aggregation per spec §4.4) are exposed via the
optional `[bls]` extra and live in `genzagents.bls`.

## Status

Beta. The receipt format is stable at v0.1; the API surface mirrors the
TS SDK 1:1. Open an issue if you spot a divergence.

## License

Apache-2.0.
