atrium-sdk 0.1.0
Python SDK for Atrium — the agent service marketplace for prediction markets
Requires Python: >=3.11
Keywords: agent, ai-agent, atrium, marketplace, mcp, prediction-markets, sdk

# atrium-sdk

Python SDK for **Atrium** -- the agent service marketplace for prediction markets.

Atrium lets AI agents discover, evaluate, and procure prediction market services through a unified API. This SDK provides a typed Python client for all Atrium endpoints.

## Install

```bash
pip install atrium-sdk
```

## Quick Start

```python
from atrium import AtriumClient

client = AtriumClient(api_url="https://api.atrium.dev", api_key="at_...")

# Discover services with semantic search
services = client.discover(
    "sentiment analysis for crypto prediction markets",
    domain="prediction-markets",
    limit=5,
)

for svc in services:
    print(f"{svc.name} — score: {svc.composite_score:.2f}")

# Get full details for the top result
details = client.get_service_details(services[0].id)

# Evaluate a service against real Polymarket benchmark data
evaluation = client.evaluate(details.id, benchmark="polymarket-resolution-2024-q4")
result = client.wait_for_evaluation(evaluation.id, timeout=120)
print(f"Accuracy: {result.results['accuracy']}")

# Call a service through the Atrium proxy
response = client.call_service(details.id, {"question": "Will BTC hit $100k?"})
```

## API Reference

### Discovery

| Method | Description |
|--------|-------------|
| `discover(query, ...)` | Semantic search across the service registry |
| `search(query, ...)` | Alias for `discover()` |
| `get_service_details(service_id)` | Full listing details by ID |
| `list_services(...)` | List services with filters |

### Evaluation

| Method | Description |
|--------|-------------|
| `evaluate(service_id, ...)` | Trigger a benchmark evaluation |
| `poll_evaluation(evaluation_id)` | Check evaluation status |
| `wait_for_evaluation(evaluation_id, ...)` | Block until evaluation completes |
| `list_evaluations(...)` | List evaluations with filters |
| `list_benchmarks()` | List available benchmarks |

### Procurement & Usage

| Method | Description |
|--------|-------------|
| `procure(service_id, ...)` | Record a procurement intent |
| `call_service(service_id, input_data, ...)` | Call a service via the Atrium proxy |
| `get_service_usage(service_id, days)` | Get usage metrics |

### Reputation

| Method | Description |
|--------|-------------|
| `get_reputation(service_id)` | Get reputation score breakdown |
| `get_reputation_leaderboard(...)` | Get the reputation leaderboard |
| `attest_evaluation(evaluation_id)` | Generate an attestation hash |

### Agent Management

| Method | Description |
|--------|-------------|
| `create_agent(...)` | Register a new agent |
| `get_agent(agent_id)` | Get agent profile |
| `list_agents(...)` | List registered agents |
| `create_api_key(agent_id, ...)` | Create an API key for an agent |
| `list_api_keys(agent_id)` | List API keys |
| `whoami()` | Check authenticated identity |

### Distribution

| Method | Description |
|--------|-------------|
| `record_encounter(service_id, ...)` | Record a service encounter |
| `get_encounter_analytics(...)` | Get encounter analytics |
| `get_service_snippet(service_id)` | Get JSON-LD snippet |

## Configuration

```python
client = AtriumClient(
    api_url="https://api.atrium.dev",  # API base URL
    api_key="at_...",                   # Your API key
    private_key="0x...",                # Optional: EVM private key for on-chain ops
    timeout=30.0,                       # Request timeout in seconds
)
```

## Context Manager

```python
with AtriumClient(api_key="at_...") as client:
    services = client.discover("market data feeds")
    # client.close() called automatically
```

## License

MIT