arcane-sdk

Official Python SDK for the Arcane public API.

Installation

pip install arcane-sdk

Quick Start

Sync client

from arcane_sdk import ArcaneClient

client = ArcaneClient(
    base_url="https://your-instance.example.com",
    api_key="your-api-key",
)

# List prompts
prompts = client.prompts.list()

# Get a dataset (paginated rows)
dataset = client.datasets.get("dataset-uuid", {"page": 1, "limit": 20})

# Iterate over all rows without loading everything
for row in client.datasets.list_rows_paginated("dataset-uuid"):
    print(row["values"])

# Add a row
new_row = client.datasets.add_row("dataset-uuid", ["input1", "input2", "expected"])

# Search traces
search_result = client.traces.search("datasource-uuid", {"limit": 100})

# Iterate over experiment results (paginated, memory-efficient)
for result in client.experiments.list_results_paginated("experiment-uuid"):
    print(result["dataset_row"], result["experiment_result"])

Async client

import asyncio
from arcane_sdk import ArcaneClientAsync

async def main():
    async with ArcaneClientAsync(
        base_url="https://your-instance.example.com",
        api_key="your-api-key",
    ) as client:
        prompts = await client.prompts.list()
        datasets = await client.datasets.list()

        async for result in client.experiments.list_results_paginated(
            "experiment-uuid"
        ):
            print(result)

asyncio.run(main())

Authentication

Use a project-scoped API key. Create one in the Arcane UI under Project → API Keys.

The SDK uses HTTP Basic Auth with username api-key and the API key as the password.

Resources

Async iterators

For paginated experiment results:

# Sync
for result in client.experiments.list_results_paginated(experiment_id):
    ...

# Async
async for result in client.experiments.list_results_paginated(experiment_id):
    ...

For paginated dataset rows:

# Sync
for row in client.datasets.list_rows_paginated(dataset_id):
    print(row["values"])

# Async
async for row in client.datasets.list_rows_paginated(dataset_id):
    print(row["values"])

Error handling

from arcane_sdk import ArcaneClient, ArcanApiError, ArcanNotFoundError

try:
    client.datasets.get("invalid-id")
except ArcanNotFoundError:
    print("Dataset not found")
except ArcanApiError as e:
    print(e.status_code, e.message, e.request_id)

Retries

The SDK automatically retries on HTTP 5xx and network errors. Configure with max_retries (default: 3):

client = ArcaneClient(
    base_url="https://api.example.com",
    api_key="...",
    max_retries=5,
)

License

MIT