Metadata-Version: 2.4
Name: somia
Version: 0.1.0a1
Summary: Python SDK for interacting with Somia Agent API
Author: Somia
License-Expression: MIT
Keywords: somia,agents,api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: pydantic<3.0.0,>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Dynamic: license-file

# 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](https://somia-platform.com) 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):

```bash
pip install somia --pre
```

Or pin the exact version:

```bash
pip install somia==0.1.0a1
```

From source (development):

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

Requires Python 3.11+.

## Quickstart

```python
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

```python
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)

```python
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:

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

## Error handling

```python
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](CONTRIBUTING.md) for local setup, testing, versioning, and release instructions.

## License

MIT — see [LICENSE](LICENSE).
