Metadata-Version: 2.4
Name: aira-sdk
Version: 0.1.2
Summary: Python SDK for Aira — legal infrastructure for AI agents
Project-URL: Homepage, https://airaproof.com
Project-URL: Documentation, https://docs.airaproof.com
Project-URL: Repository, https://github.com/aira-proof/python-sdk
Project-URL: Issues, https://github.com/aira-proof/python-sdk/issues
Author-email: Aira <sdk@airaproof.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,aira,compliance,eu-ai-act,notarization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# Aira Python SDK

**Legal infrastructure for AI agents.** Cryptographic proof for every action your AI agent takes.

Aira provides the accountability layer that autonomous AI agents need to operate in regulated environments. Every action is notarized with Ed25519 signatures and RFC 3161 timestamps — producing court-admissible proof that an action happened, who authorized it, and what decision was made.

**What you get:**
- **Notarize actions** — cryptographic receipts for every agent decision, email, transaction
- **Register agents** — verifiable identity with versioned configs and public profiles
- **Multi-model consensus** — run the same decision through multiple AI models, flag disagreements
- **Evidence packages** — sealed, tamper-proof bundles for legal discovery and audit
- **Agent lifecycle** — wills, succession plans, death certificates, compliance snapshots
- **Liability commitments** — record accountability commitments with cryptographic proof
- **Human authorization** — require human co-signatures on high-stakes actions
- **Public verification** — anyone can verify a receipt without an account

Built for EU AI Act, SR 11-7, and GDPR compliance. Self-hostable. Open-source SDK.

[![PyPI version](https://img.shields.io/pypi/v/aira-sdk.svg)](https://pypi.org/project/aira-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

```bash
pip install aira-sdk
```

## Quick Start

```python
from aira import Aira

aira = Aira(api_key="aira_live_xxx")

# Notarize an agent action
receipt = aira.notarize(
    action_type="email_sent",
    details="Sent onboarding email to customer@example.com",
    agent_id="support-agent",
    model_id="claude-sonnet-4-6",
    instruction_hash="sha256:a1b2c3...",
)

print(receipt.payload_hash)   # sha256:e5f6a7b8...
print(receipt.signature)       # ed25519:base64url...
print(receipt.action_id)       # uuid
```

## Decorator -- Auto-Notarize Functions

```python
@aira.trace(agent_id="lending-agent", action_type="loan_decision")
def approve_loan(application):
    decision = model.predict(application)
    return decision

# Every call to approve_loan() is automatically notarized
result = approve_loan({"credit_score": 742, "income": 45000})
```

The decorator is non-blocking -- if notarization fails, your function still returns normally. Arguments and return values are never sent to the API; only a metadata hash is recorded.

## Async Support

```python
from aira import AsyncAira

async with AsyncAira(api_key="aira_live_xxx") as aira:
    receipt = await aira.notarize(
        action_type="contract_signed",
        details="Agent signed vendor agreement #1234",
        agent_id="procurement-agent",
    )

    # Async decorator
    @aira.trace(agent_id="my-agent")
    async def process_order(order):
        return await execute(order)
```

## Agent Registry

```python
# Register an agent
agent = aira.register_agent(
    agent_slug="support-agent-v2",
    display_name="Customer Support Agent",
    capabilities=["email", "chat", "tickets"],
    public=True,
)

# Publish a version
version = aira.publish_version(
    slug="support-agent-v2",
    version="1.0.0",
    model_id="claude-sonnet-4-6",
    changelog="Initial release",
)

# List all agents
agents, pagination = aira.list_agents(page=1)

# Decommission
aira.decommission_agent("old-agent")
```

## Action Notarization

```python
# Notarize with full parameters
receipt = aira.notarize(
    action_type="loan_approved",
    details="Approved loan #4521 for $25,000",
    agent_id="lending-agent",
    model_id="claude-sonnet-4-6",
    instruction_hash="sha256:...",
    idempotency_key="loan-4521",  # Prevents duplicate notarizations
)

# Retrieve action details
action = aira.get_action("action-uuid")
print(action.action_type)
print(action.receipt)

# List actions with filters
actions, pagination = aira.list_actions(
    page=1,
    action_type="loan_approved",
    agent_id="lending-agent",
)

# Human co-signature
aira.authorize_action("action-uuid", authorizer_email="compliance@acme.com")

# Legal hold
aira.set_legal_hold("action-uuid")
aira.release_legal_hold("action-uuid")

# Chain of custody
chain = aira.get_action_chain("action-uuid")
```

## Evidence Packages

```python
# Bundle actions into a sealed evidence package
package = aira.create_evidence_package(
    title="Q1 2026 Audit Trail -- Lending Agent",
    action_ids=["act-uuid-1", "act-uuid-2", "act-uuid-3"],
    description="All lending decisions for regulatory review",
)

print(package.package_hash)  # Cryptographically sealed
print(package.signature)     # Ed25519 signed

# List and retrieve
packages, pagination = aira.list_evidence_packages(page=1)
pkg = aira.get_evidence_package("package-uuid")

# Time travel -- query actions at a point in time
result = aira.time_travel(
    agent_id="lending-agent",
    point_in_time="2026-01-15T00:00:00Z",
)
```

## Compliance Snapshots

```python
snapshot = aira.create_compliance_snapshot(
    framework="eu-ai-act",
    agent_slug="lending-agent",
    findings={"art_12_logging": "pass", "art_14_oversight": "pass"},
)

# List by framework
snapshots, pagination = aira.list_compliance_snapshots(
    page=1,
    framework="eu-ai-act",
)
```

## Agent Will & Estate

```python
# Set succession plan
aira.set_agent_will(
    slug="support-agent-v2",
    successor_slug="support-agent-v3",
    succession_policy="transfer_to_successor",
    data_retention_days=2555,
    notify_emails=["compliance@acme.com"],
)

# Retrieve will
will = aira.get_agent_will("support-agent-v2")

# Issue death certificate (triggers succession)
aira.issue_death_certificate("old-agent", reason="Replaced by v3")

# Retrieve death certificate
cert = aira.get_death_certificate("old-agent")
```

## Escrow (Liability Commitments)

Escrow accounts are **accountability ledgers** — they record liability commitments with cryptographic proof. No real funds are custodied by Aira.

```python
# Record a liability commitment
account = aira.create_escrow_account(purpose="Vendor contract #4521")

# Record commitment before agent acts
tx = aira.escrow_deposit(account.id, amount=5000.00, description="10% liability commitment")

# Release commitment after successful completion
aira.escrow_release(account.id, amount=5000.00)

# Dispute if something goes wrong
aira.escrow_dispute(account.id, amount=2000.00, description="Incorrect vendor payment")

# List accounts
accounts, pagination = aira.list_escrow_accounts(page=1)
```

## Cases (Multi-Model Adjudication)

```python
# Run a case across multiple AI models
case = aira.run_case(
    details="Should we approve loan application #4521?",
    models=["claude-sonnet-4-6", "gpt-4o", "gemini-2.0-flash"],
)

print(case["consensus"]["decision"])    # "approve"
print(case["consensus"]["confidence"])  # 0.92

# List cases
cases, pagination = aira.list_cases(page=1)
```

## Ask Aira (Chat)

```python
# Specify a model explicitly
response = aira.ask("How many email actions were notarized this week?", model="claude-sonnet-4-6")
print(response["content"])
```

The `model` parameter is optional. If omitted, the organization's default chat model is used.

> **Note:** A default chat model must be configured in your dashboard (Settings → Models) before using `ask()` without an explicit model.

## Public Verification

```python
# Anyone can verify -- no auth needed
result = aira.verify_action("action-uuid")
print(result.valid)     # True
print(result.message)   # "Action receipt exists and signing key is valid."
```

## Error Handling

```python
from aira import Aira, AiraError

try:
    receipt = aira.notarize(action_type="email_sent", details="test")
except AiraError as e:
    print(e.status)   # 429
    print(e.code)     # PLAN_LIMIT_EXCEEDED
    print(e.message)  # Monthly operation limit reached
```

## Configuration

```python
aira = Aira(
    api_key="aira_live_xxx",
    base_url="https://your-self-hosted.com",  # Self-hosted
    timeout=60.0,                               # Request timeout
)
```

## Development

```bash
git clone https://github.com/aira-proof/python-sdk.git
cd python-sdk
pip install -e ".[dev]"
pytest
```

## License

MIT

## Links

- [Interactive Demo](https://app.airaproof.com/demo) — try Aira in your browser, no code needed
- [Documentation](https://docs.airaproof.com)
- [API Reference](https://docs.airaproof.com/docs/api-reference)
- [Dashboard](https://app.airaproof.com)
- [GitHub](https://github.com/aira-proof/python-sdk)
