somia 0.1.0a1

Python SDK for interacting with Somia Agent API

Somia Python SDK

Alpha release (0.1.0a1) — early SDK for testing and evaluation. APIs may change. Install with pip install somia --pre or pin pip install somia==0.1.0a1.

Official Python client for the Somia Agent API.

The SDK is open source under the MIT license. Access to the Somia platform requires a Somia account and API key; usage of the hosted API is subject to Somia's terms and billing.

Supported endpoints

• POST /api/v1/external/agent/{agent_id}/session — create a session
• POST /api/v1/external/agent/{agent_id}/session/{session_id} — continue a session

Installation

From PyPI (pre-release):

pip install somia --pre

Or pin the exact version:

pip install somia==0.1.0a1

From source (development):

git clone https://github.com/somia-platform/somia-python-sdk.git
cd somia-python-sdk
pip install -e ".[dev]"

Requires Python 3.11+.

Quickstart

from somia import SomiaClient

with SomiaClient(
    base_url="https://api.somia-platform.com",
    api_key="your_api_key",
) as client:
    response = client.sessions.create_session(
        agent_id=123,
        input_data="Hello",
        pipeline_version="production",
    )
    print(response.session_id, response.message)

Continue an existing session

from somia import SomiaClient

with SomiaClient(
    base_url="https://api.somia-platform.com",
    api_key="your_api_key",
) as client:
    response = client.sessions.interact_session(
        agent_id=123,
        session_id="550e8400-e29b-41d4-a716-446655440000",
        input_data="Can you explain it in one paragraph?",
    )
    print(response.message)

You can also use client.sessions.run(...) with an optional session_id to create or continue in one call.

Streaming responses (SSE)

from somia import SomiaClient

with SomiaClient(
    base_url="https://api.somia-platform.com",
    api_key="your_api_key",
) as client:
    events = client.sessions.create_session(
        agent_id=123,
        input_data="Stream this answer",
        stream=True,
    )
    for event in events:
        if event.event_type == "chunk":
            print("chunk:", event.data)
        elif event.event_type == "error":
            print("error:", event.data)
        elif event.event_type == "end":
            print("stream ended")

Authentication

By default the SDK sends your API key in the x-api-key header. Override the header name if needed:

client = SomiaClient(
    base_url="https://api.somia-platform.com",
    api_key="your_api_key",
    api_key_header="apikey",
)

Error handling

from somia import AuthError, RateLimitError, ServiceUnavailableError, SomiaClient

try:
    with SomiaClient(base_url="https://api.somia-platform.com", api_key="...") as client:
        client.sessions.create_session(agent_id=123, input_data="Hi")
except AuthError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ServiceUnavailableError as exc:
    print(f"Retry later: {exc}")

Common error classes:

• BadRequestError — invalid payloads
• AuthError — missing or invalid API key
• PermissionDeniedError — access or usage-limit failures
• NotFoundError — missing agents or sessions
• RateLimitError — rate limits exceeded
• ServiceUnavailableError — platform saturation or timeouts
• ServerError — unexpected server-side failures
• TransportError — network-level failures
• StreamParseError — malformed SSE payloads

Session flow notes

• Create-session may ignore input_data when Begin has no required query fields.
• Interact-session always uses session_id in the path and forwards input_data as the turn payload.
• Non-streaming responses include fields such as session_id, message, history, pending, and finished.

Development

See CONTRIBUTING.md for local setup, testing, versioning, and release instructions.

License

MIT — see LICENSE.