somia 0.1.0a1__tar.gz

somia-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Somia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

somia-0.1.0a1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include src *.py
+global-exclude *.py[cod]
+global-exclude __pycache__
+prune **/__pycache__

somia-0.1.0a1/PKG-INFO

@@ -0,0 +1,174 @@
+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).

somia-0.1.0a1/README.md

@@ -0,0 +1,149 @@
+# 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).

somia-0.1.0a1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "somia"
+version = "0.1.0a1"
+description = "Python SDK for interacting with Somia Agent API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Somia" }
+]
+keywords = ["somia", "agents", "api", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0,<1.0.0",
+  "pydantic>=2.7.0,<3.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-cov>=5.0.0"
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

somia-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

somia-0.1.0a1/src/somia/__init__.py

@@ -0,0 +1,37 @@
+from somia.client import AgentSessionsClient, SomiaClient
+from somia.exceptions import (
+    ApiError,
+    AuthError,
+    BadRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    SomiaError,
+    StreamParseError,
+    TransportError,
+)
+from somia.models import AgentExecutionRequest, AgentSessionResponse, StreamEvent
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "AgentExecutionRequest",
+    "AgentSessionResponse",
+    "AgentSessionsClient",
+    "ApiError",
+    "AuthError",
+    "BadRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "SomiaClient",
+    "SomiaError",
+    "StreamEvent",
+    "StreamParseError",
+    "TransportError",
+    "__version__",
+]

somia-0.1.0a1/src/somia/_http.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Iterator, Optional, Set
+
+import httpx
+
+from somia.exceptions import TransportError, raise_for_status
+from somia.models import StreamEvent
+from somia.streaming import parse_sse_events
+
+
+class HttpTransport:
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 60.0,
+        retries: int = 2,
+        retry_backoff_seconds: float = 0.5,
+        api_key_header: str = "x-api-key",
+        transient_status_codes: Optional[Set[int]] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._retries = max(0, retries)
+        self._retry_backoff_seconds = max(0.0, retry_backoff_seconds)
+        self._transient_status_codes = transient_status_codes or {429, 500, 502, 503, 504}
+        client_kwargs: Dict[str, Any] = {
+            "base_url": base_url.rstrip("/"),
+            "timeout": httpx.Timeout(timeout),
+            "headers": {
+                api_key_header: api_key,
+                "content-type": "application/json",
+            },
+        }
+        if transport is not None:
+            client_kwargs["transport"] = transport
+        self._client = httpx.Client(**client_kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def post_json(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        last_error: Optional[Exception] = None
+        for attempt in range(self._retries + 1):
+            try:
+                response = self._client.post(path, json=payload)
+            except httpx.HTTPError as exc:
+                if attempt >= self._retries:
+                    raise TransportError(str(exc)) from exc
+                self._sleep_backoff(attempt)
+                continue
+
+            if response.status_code in self._transient_status_codes and attempt < self._retries:
+                last_error = TransportError(
+                    f"Transient HTTP status {response.status_code} for {path}",
+                )
+                self._sleep_backoff(attempt)
+                continue
+
+            body = self._decode_json_or_text(response)
+            raise_for_status(response.status_code, body)
+            if isinstance(body, dict):
+                return body
+            raise TransportError("Expected JSON object response from API.")
+
+        if last_error is not None:
+            raise last_error
+        raise TransportError("Request failed without a recoverable response.")
+
+    def post_stream(self, path: str, payload: Dict[str, Any]) -> Iterator[StreamEvent]:
+        try:
+            with self._client.stream("POST", path, json=payload) as response:
+                if response.status_code >= 400:
+                    body = self._decode_json_or_text(response)
+                    raise_for_status(response.status_code, body)
+                for event in parse_sse_events(response.iter_lines()):
+                    yield event
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+
+    def _sleep_backoff(self, attempt: int) -> None:
+        sleep_seconds = self._retry_backoff_seconds * (2 ** attempt)
+        if sleep_seconds > 0:
+            time.sleep(sleep_seconds)
+
+    @staticmethod
+    def _decode_json_or_text(response: httpx.Response) -> Any:
+        try:
+            return response.json()
+        except ValueError:
+            if response.text:
+                return response.text
+            return None

somia-0.1.0a1/src/somia/client.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, Optional, Union
+
+from somia._http import HttpTransport
+from somia.models import AgentExecutionRequest, AgentSessionResponse, StreamEvent
+
+
+class AgentSessionsClient:
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    def create_session(
+        self,
+        agent_id: int,
+        *,
+        input_data: Optional[Any] = None,
+        stream: bool = False,
+        pipeline_version: Union[int, str] = "production",
+        trace_enabled: bool = False,
+        test: bool = False,
+        source: Optional[str] = None,
+    ) -> Union[AgentSessionResponse, Iterator[StreamEvent]]:
+        payload = self._payload(
+            input_data=input_data,
+            stream=stream,
+            pipeline_version=pipeline_version,
+            trace_enabled=trace_enabled,
+            test=test,
+            source=source,
+        )
+        path = f"/api/v1/external/agent/{agent_id}/session"
+        if stream:
+            return self._transport.post_stream(path, payload)
+        return AgentSessionResponse.model_validate(self._transport.post_json(path, payload))
+
+    def interact_session(
+        self,
+        agent_id: int,
+        session_id: str,
+        *,
+        input_data: Optional[Any] = None,
+        stream: bool = False,
+        pipeline_version: Union[int, str] = "production",
+        trace_enabled: bool = False,
+        test: bool = False,
+        source: Optional[str] = None,
+    ) -> Union[AgentSessionResponse, Iterator[StreamEvent]]:
+        payload = self._payload(
+            input_data=input_data,
+            stream=stream,
+            pipeline_version=pipeline_version,
+            trace_enabled=trace_enabled,
+            test=test,
+            source=source,
+        )
+        path = f"/api/v1/external/agent/{agent_id}/session/{session_id}"
+        if stream:
+            return self._transport.post_stream(path, payload)
+        return AgentSessionResponse.model_validate(self._transport.post_json(path, payload))
+
+    def run(
+        self,
+        agent_id: int,
+        *,
+        input_data: Optional[Any] = None,
+        session_id: Optional[str] = None,
+        stream: bool = False,
+        pipeline_version: Union[int, str] = "production",
+        trace_enabled: bool = False,
+        test: bool = False,
+        source: Optional[str] = None,
+    ) -> Union[AgentSessionResponse, Iterator[StreamEvent]]:
+        if session_id:
+            return self.interact_session(
+                agent_id,
+                session_id,
+                input_data=input_data,
+                stream=stream,
+                pipeline_version=pipeline_version,
+                trace_enabled=trace_enabled,
+                test=test,
+                source=source,
+            )
+        return self.create_session(
+            agent_id,
+            input_data=input_data,
+            stream=stream,
+            pipeline_version=pipeline_version,
+            trace_enabled=trace_enabled,
+            test=test,
+            source=source,
+        )
+
+    @staticmethod
+    def _payload(
+        *,
+        input_data: Optional[Any],
+        stream: bool,
+        pipeline_version: Union[int, str],
+        trace_enabled: bool,
+        test: bool,
+        source: Optional[str],
+    ) -> Dict[str, Any]:
+        request = AgentExecutionRequest(
+            input_data=input_data,
+            stream=stream,
+            pipeline_version=pipeline_version,
+            trace_enabled=trace_enabled,
+            test=test,
+            source=source,
+        )
+        return request.model_dump(exclude_none=True)
+
+
+class SomiaClient:
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 60.0,
+        retries: int = 2,
+        retry_backoff_seconds: float = 0.5,
+        api_key_header: str = "x-api-key",
+    ) -> None:
+        self._transport = HttpTransport(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            retries=retries,
+            retry_backoff_seconds=retry_backoff_seconds,
+            api_key_header=api_key_header,
+        )
+        self.sessions = AgentSessionsClient(self._transport)
+        self.agents = self.sessions
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "SomiaClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()