Metadata-Version: 2.4
Name: aal-sdk
Version: 0.1.3
Summary: Python SDK for the Agent Action Ledger API
Project-URL: Homepage, https://agentink.dev
Project-URL: Repository, https://github.com/brianofearth/agent-action-ledger
License-Expression: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.39.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# aal-sdk (Python)

Python SDK for [Agent Ink](https://agentink.dev) — the audit trail and logging API for AI agents. Full parity with the TypeScript SDK.

## Getting Started

1. Sign up at [agentink.dev](https://agentink.dev) (free during beta)
2. Go to **Dashboard > API Keys** and create a new key
3. Install the SDK and use your key in the examples below

## Installation

```bash
pip install aal-sdk
```

With optional integrations:

```bash
pip install aal-sdk[anthropic]  # Anthropic client wrapper
pip install aal-sdk[mcp]        # MCP server wrapper
```

## Quick Start

```python
import asyncio
from aal_sdk import AALClient

async def main():
    client = AALClient({
        "api_url": "https://api.agentink.dev",
        "api_key": "your-api-key",
    })

    session = client.start_session({"agent_id": "my-agent"})

    session.log_action({
        "action_type": "TOOL_CALL",
        "tool_name": "get_weather",
        "parameters": {"city": "London"},
        "response": {"temp": 15},
        "status": "SUCCESS",
        "latency_ms": 42,
    })

    await client.shutdown()

asyncio.run(main())
```

## Auto-Instrumentation

### Anthropic Client

```python
from aal_sdk import AALClient
from aal_sdk.anthropic import wrap_anthropic_client
from anthropic import AsyncAnthropic

client = AALClient({"api_url": "...", "api_key": "..."})
session = client.start_session({"agent_id": "claude-agent"})

anthropic = wrap_anthropic_client(AsyncAnthropic(), session)
# All tool_use blocks are now automatically logged
```

### MCP Server

```python
from aal_sdk import AALClient
from aal_sdk.mcp import wrap_mcp_server
from mcp import Server

client = AALClient({"api_url": "...", "api_key": "..."})
session = client.start_session({"agent_id": "mcp-agent"})

server = Server("my-server")
wrap_mcp_server(server, session)
# All tool calls are now automatically logged
```

## API Reference

### AALClient

- `AALClient(config)` -- Create a client with `api_url`, `api_key`, optional `flush_interval` and `batch_size`
- `start_session(config)` -- Create a new session (returns `AALSession`)
- `session(session_id, agent_id)` -- Get a handle to an existing session
- `get_events(params)` -- Query events with optional filters
- `get_session(session_id)` -- Get session details
- `shutdown()` -- Drain buffer and close connections

### AALSession

- `log_action(input)` -- Log an action event (buffered, auto-flushed)

### Wrappers

- `wrap_anthropic_client(client, session)` -- Auto-log Anthropic tool_use blocks
- `wrap_mcp_server(server, session)` -- Auto-log MCP tool calls

## Documentation

Full documentation at [agentink.dev/docs](https://agentink.dev/docs).

## License

MIT
