bma-sdk 0.4.0__tar.gz

bma_sdk-0.4.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+uv.lock

bma_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: bma-sdk
+Version: 0.4.0
+Summary: Python client for the BMA REST API and the BMA extensions to the Anthropic Managed Agents API.
+Project-URL: Repository, https://github.com/beeos-ai/bma-sdks
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dateutil>=2.8.0
+Description-Content-Type: text/markdown
+
+# bma-sdk
+
+Python client for the BMA REST API, generated from
+[`contracts/bma/rest.openapi.yaml`](../contracts/bma/rest.openapi.yaml), plus
+the BMA extensions to the Anthropic Managed Agents API.
+
+```python
+from bma_sdk import BmaClient, unwrap
+from bma_sdk.rest.api.agents import create_agent_input, create_agent_session
+from bma_sdk.rest.models import CreateAgentInputRequest, CreateAgentSessionRequest, TextContentBlock
+
+with BmaClient(token, "https://host/api/v1") as bma:
+    session = unwrap(create_agent_session.sync_detailed(
+        org, project, agent, client=bma.rest,
+        body=CreateAgentSessionRequest(idempotency_key="task-1"),
+    )).session
+    unwrap(create_agent_input.sync_detailed(
+        org, project, agent, client=bma.rest, session_id=session.id,
+        body=CreateAgentInputRequest(content_blocks=[TextContentBlock(type_="text", text="Start.")]),
+    ))
+    for frame in bma.stream_events(org, project, agent, session_id=session.id):
+        print(frame.event, frame.sequence)
+```
+
+`bma_sdk.rest` contains one module per contract operation with
+`sync`/`sync_detailed`/`asyncio`/`asyncio_detailed` functions. `BmaClient`
+adds bearer authentication, `stream_events`, and `download_artifact` (size and
+sha256 verified).
+
+## BMA extensions to the Anthropic facade
+
+Use the official Anthropic SDK for `/v1/agents`, `/v1/environments`,
+`/v1/sessions` and events. The routes BMA adds:
+
+```python
+from bma_sdk.facade_extensions import FacadeExtensionsClient, bma_sequence
+
+with FacadeExtensionsClient(api_key, "https://host", project_id="proj_...") as ext:
+    ticket = ext.get_session_desktop_stream(session_id, desktop_session_id=desktop_id)
+    ext.upload_session_file(session_id, "report.pdf", data)
+    page = ext.list_session_files(session_id, limit=100)
+```
+
+The module also exports `ModelConfigOverride`, `MCPServerBMAAuth`,
+`IDEMPOTENCY_KEY_HEADER`, and `bma_sequence(event)`.
+
+The executor protocol (executor, harness and agent ends) is the separate
+package [`bma-executor-sdk`](../executor/python).

bma_sdk-0.4.0/README.md

@@ -0,0 +1,48 @@
+# bma-sdk
+
+Python client for the BMA REST API, generated from
+[`contracts/bma/rest.openapi.yaml`](../contracts/bma/rest.openapi.yaml), plus
+the BMA extensions to the Anthropic Managed Agents API.
+
+```python
+from bma_sdk import BmaClient, unwrap
+from bma_sdk.rest.api.agents import create_agent_input, create_agent_session
+from bma_sdk.rest.models import CreateAgentInputRequest, CreateAgentSessionRequest, TextContentBlock
+
+with BmaClient(token, "https://host/api/v1") as bma:
+    session = unwrap(create_agent_session.sync_detailed(
+        org, project, agent, client=bma.rest,
+        body=CreateAgentSessionRequest(idempotency_key="task-1"),
+    )).session
+    unwrap(create_agent_input.sync_detailed(
+        org, project, agent, client=bma.rest, session_id=session.id,
+        body=CreateAgentInputRequest(content_blocks=[TextContentBlock(type_="text", text="Start.")]),
+    ))
+    for frame in bma.stream_events(org, project, agent, session_id=session.id):
+        print(frame.event, frame.sequence)
+```
+
+`bma_sdk.rest` contains one module per contract operation with
+`sync`/`sync_detailed`/`asyncio`/`asyncio_detailed` functions. `BmaClient`
+adds bearer authentication, `stream_events`, and `download_artifact` (size and
+sha256 verified).
+
+## BMA extensions to the Anthropic facade
+
+Use the official Anthropic SDK for `/v1/agents`, `/v1/environments`,
+`/v1/sessions` and events. The routes BMA adds:
+
+```python
+from bma_sdk.facade_extensions import FacadeExtensionsClient, bma_sequence
+
+with FacadeExtensionsClient(api_key, "https://host", project_id="proj_...") as ext:
+    ticket = ext.get_session_desktop_stream(session_id, desktop_session_id=desktop_id)
+    ext.upload_session_file(session_id, "report.pdf", data)
+    page = ext.list_session_files(session_id, limit=100)
+```
+
+The module also exports `ModelConfigOverride`, `MCPServerBMAAuth`,
+`IDEMPOTENCY_KEY_HEADER`, and `bma_sequence(event)`.
+
+The executor protocol (executor, harness and agent ends) is the separate
+package [`bma-executor-sdk`](../executor/python).

bma_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "bma-sdk"
+version = "0.4.0"
+description = "Python client for the BMA REST API and the BMA extensions to the Anthropic Managed Agents API."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+  "attrs>=22.2.0",
+  "httpx>=0.27,<1",
+  "python-dateutil>=2.8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/beeos-ai/bma-sdks"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bma_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

bma_sdk-0.4.0/src/bma_sdk/__init__.py

@@ -0,0 +1,12 @@
+"""Python client for the BMA REST API.
+
+* :mod:`bma_sdk.rest` - generated from ``contracts/bma/rest.openapi.yaml``.
+* :class:`BmaClient` - authentication, event stream, verified artifact downloads.
+* :mod:`bma_sdk.facade_extensions` - BMA extensions to the Anthropic Managed
+  Agents API (not part of the Anthropic contract).
+"""
+
+from .client import DEFAULT_BASE_URL, SDK_VERSION, BmaApiError, BmaClient, StreamFrame, parse_sse, unwrap
+
+__version__ = SDK_VERSION
+__all__ = ["DEFAULT_BASE_URL", "SDK_VERSION", "BmaApiError", "BmaClient", "StreamFrame", "parse_sse", "unwrap"]

bma_sdk-0.4.0/src/bma_sdk/client.py

@@ -0,0 +1,214 @@
+"""Authenticated BMA REST client.
+
+Every operation and model lives in :mod:`bma_sdk.rest`, generated from
+``contracts/bma/rest.openapi.yaml``. This module adds only what the contract
+does not describe: bearer authentication, error decoding, the server-sent
+event stream, and verified artifact downloads.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .rest.client import AuthenticatedClient
+from .rest.models.artifact import Artifact
+from .rest.types import Response
+
+DEFAULT_BASE_URL = "https://api.bma.beeos.ai/v1"
+SDK_VERSION = "0.4.0"
+_USER_AGENT = f"bma-sdks-python/{SDK_VERSION}"
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+class BmaApiError(Exception):
+    """A non-2xx response from the BMA API."""
+
+    def __init__(self, status: int, body: Any) -> None:
+        wire = body if isinstance(body, dict) else {}
+        self.status = status
+        self.code: str = wire.get("code") if isinstance(wire.get("code"), str) else ""
+        message = wire.get("error") if isinstance(wire.get("error"), str) and wire.get("error") else f"HTTP {status}"
+        self.message: str = message
+        self.current_digest: str | None = wire.get("current_digest")
+        self.issues: list[Any] | None = wire.get("issues")
+        super().__init__(f"bma: HTTP {status} {self.code or 'unknown'}: {message}")
+
+    @property
+    def retryable(self) -> bool:
+        """Whether a retry may succeed without changing the request."""
+        return (
+            self.status in (408, 429)
+            or self.status >= 500
+            or self.code in ("service_unavailable", "rate_limited")
+        )
+
+
+def unwrap(response: Response[Any]) -> Any:
+    """Return ``response.parsed`` for 2xx responses or raise :class:`BmaApiError`.
+
+    Use with the generated ``sync_detailed``/``asyncio_detailed`` functions.
+    """
+    status = int(response.status_code)
+    if 200 <= status < 300:
+        return response.parsed
+    try:
+        body = json.loads(response.content)
+    except ValueError:
+        body = None
+    raise BmaApiError(status, body)
+
+
+@dataclass(frozen=True)
+class StreamFrame:
+    """One SSE data frame. ``data`` is the decoded JSON payload."""
+
+    event: str
+    data: Any
+    id: str | None = None
+    sequence: int | None = None
+
+
+class BmaClient:
+    """BMA REST client.
+
+    ``client.rest`` is the generated :class:`bma_sdk.rest.client.AuthenticatedClient`
+    to pass to any generated operation, for example::
+
+        from bma_sdk.rest.api.agents import create_agent_session
+        session = unwrap(create_agent_session.sync_detailed(org, project, agent, client=bma.rest, body=...))
+    """
+
+    def __init__(self, token: str, base_url: str = DEFAULT_BASE_URL) -> None:
+        token = (token or "").strip()
+        if not token:
+            raise ValueError("bma: token is required")
+        base_url = (base_url or DEFAULT_BASE_URL).strip().rstrip("/")
+        if urlsplit(base_url).scheme not in ("http", "https"):
+            raise ValueError("bma: base_url must use http or https")
+        self.base_url = base_url
+        self.rest = AuthenticatedClient(base_url=base_url, token=token, headers={"User-Agent": _USER_AGENT})
+
+    def close(self) -> None:
+        self.rest.get_httpx_client().close()
+
+    def __enter__(self) -> BmaClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def stream_events(
+        self,
+        org_id: str,
+        project_id: str,
+        agent_id: str,
+        *,
+        session_id: str | None = None,
+        after_sequence: int | None = None,
+        last_event_id: int | None = None,
+        stream_deltas: bool | None = None,
+    ) -> Iterator[StreamFrame]:
+        """Iterate ``GET .../agents/{agent_id}/events/stream``.
+
+        Heartbeat comments are skipped; the iterator ends when the server closes
+        the stream.
+        """
+        params: dict[str, str] = {}
+        if session_id is not None:
+            params["session_id"] = session_id
+        if after_sequence is not None:
+            params["after_sequence"] = str(after_sequence)
+        if stream_deltas is not None:
+            params["stream_deltas"] = "true" if stream_deltas else "false"
+        headers = {"Accept": "text/event-stream"}
+        if last_event_id is not None:
+            headers["Last-Event-ID"] = str(last_event_id)
+        path = f"/orgs/{org_id}/projects/{project_id}/agents/{agent_id}/events/stream"
+        with self.rest.get_httpx_client().stream("GET", path, params=params, headers=headers, timeout=None) as response:
+            _raise_for_status(response)
+            media = response.headers.get("content-type", "").split(";")[0].strip()
+            if media != "text/event-stream":
+                raise ValueError(f"bma: event stream content type = {media!r}")
+            for event, frame_id, data in parse_sse(response.iter_lines()):
+                sequence = None
+                if frame_id is not None:
+                    if not frame_id.isdigit():
+                        raise ValueError(f"bma: invalid event id {frame_id!r}")
+                    sequence = int(frame_id)
+                yield StreamFrame(event=event, data=json.loads(data), id=frame_id, sequence=sequence)
+
+    def download_artifact(self, artifact: Artifact, *, max_bytes: int) -> bytes:
+        """Download artifact content and verify its recorded size and sha256 digest."""
+        size = artifact.size_bytes
+        if max_bytes <= 0:
+            raise ValueError("bma: max_bytes is required")
+        if not isinstance(size, int) or size < 0 or size > max_bytes:
+            raise ValueError("bma: artifact size is missing or exceeds max_bytes")
+        digest = artifact.digest if isinstance(artifact.digest, str) else ""
+        if not _DIGEST.match(digest):
+            raise ValueError("bma: artifact digest must be sha256:<hex>")
+        path = (
+            f"/orgs/{artifact.org_id}/projects/{artifact.project_id}"
+            f"/agents/{artifact.agent_id}/artifacts/{artifact.id}/content"
+        )
+        hasher = hashlib.sha256()
+        chunks: list[bytes] = []
+        total = 0
+        with self.rest.get_httpx_client().stream(
+            "GET", path, headers={"Accept": "application/octet-stream"}
+        ) as response:
+            _raise_for_status(response)
+            for chunk in response.iter_bytes():
+                total += len(chunk)
+                if total > size:
+                    raise ValueError(f"bma: artifact is larger than {size} bytes")
+                hasher.update(chunk)
+                chunks.append(chunk)
+        if total != size:
+            raise ValueError(f"bma: artifact size = {total}, want {size}")
+        if not hmac.compare_digest("sha256:" + hasher.hexdigest(), digest):
+            raise ValueError("bma: artifact digest mismatch")
+        return b"".join(chunks)
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if 200 <= response.status_code < 300:
+        return
+    raw = response.read()
+    try:
+        body = json.loads(raw)
+    except ValueError:
+        body = None
+    raise BmaApiError(response.status_code, body)
+
+
+def parse_sse(lines: Iterator[str]) -> Iterator[tuple[str, str | None, str]]:
+    """Minimal text/event-stream parser yielding ``(event, id, data)``."""
+    event, frame_id, data = "", None, []
+    for line in lines:
+        if line == "":
+            if data:
+                yield event or "message", frame_id, "\n".join(data)
+            event, frame_id, data = "", None, []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        value = value[1:] if value.startswith(" ") else value
+        if field == "event":
+            event = value
+        elif field == "id":
+            frame_id = value
+        elif field == "data":
+            data.append(value)
+    if data:
+        yield event or "message", frame_id, "\n".join(data)

bma_sdk-0.4.0/src/bma_sdk/facade_extensions/__init__.py

@@ -0,0 +1,215 @@
+"""BMA extensions to the Anthropic Managed Agents API.
+
+The standard facade routes (``/v1/agents``, ``/v1/environments``,
+``/v1/sessions``, events, events/stream, ``/v1/files``,
+``/v1/memory_stores``) are served by the official Anthropic SDKs pointed at a
+BMA deployment. Everything in this
+package is a BMA extension that is NOT part of the Anthropic contract. The
+models and operations under ``_generated`` come from
+``contracts/bma/facade-extensions.openapi.yaml``.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ._generated.api.default import (
+    add_session_resource,
+    delete_session_resource,
+    download_session_file,
+    get_session_desktop_stream,
+    list_session_files,
+    list_session_resources,
+    upload_session_file,
+)
+from ._generated.client import Client
+from ._generated.models import (
+    DeletedSessionResource,
+    DesktopStream,
+    FileResource,
+    FileResourcePage,
+    FileResourceParams,
+    MCPServerBMAAuth,
+    ModelConfigOverride,
+    SessionFile,
+    SessionFilePage,
+    UploadSessionFileBody,
+)
+from ._generated.types import UNSET, File, Response
+
+__all__ = [
+    "IDEMPOTENCY_KEY_HEADER",
+    "MAX_SESSION_FILE_BYTES",
+    "DeletedSessionResource",
+    "DesktopStream",
+    "FacadeApiError",
+    "FacadeExtensionsClient",
+    "FileResource",
+    "FileResourcePage",
+    "MCPServerBMAAuth",
+    "ModelConfigOverride",
+    "SessionFile",
+    "SessionFileContent",
+    "SessionFilePage",
+    "bma_sequence",
+]
+
+#: BMA extension header forwarded on session create and send-events.
+IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+MAX_SESSION_FILE_BYTES = 8 << 20
+
+
+class FacadeApiError(Exception):
+    """An Anthropic-style error envelope returned by a facade extension route."""
+
+    def __init__(self, status: int, body: Any) -> None:
+        error = body.get("error") if isinstance(body, dict) else None
+        error = error if isinstance(error, dict) else {}
+        self.status = status
+        self.type: str = error.get("type") if isinstance(error.get("type"), str) else "api_error"
+        self.code: str | None = error.get("code") if isinstance(error.get("code"), str) else None
+        self.message: str = error.get("message") or f"HTTP {status}"
+        super().__init__(f"bma facade: HTTP {status} {self.type}: {self.message}")
+
+
+def bma_sequence(event: Any) -> int | None:
+    """Return the BMA extension ``bma_sequence`` of a facade session event.
+
+    ``None`` for preview and synthetic events. Send it as ``Last-Event-ID`` to
+    resume ``GET /v1/sessions/{id}/events/stream``.
+    """
+    value = event.get("bma_sequence") if isinstance(event, dict) else None
+    return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+@dataclass(frozen=True)
+class SessionFileContent:
+    """One downloaded session file with its response metadata."""
+
+    content: bytes
+    content_type: str | None
+    filename: str | None
+    digest: str | None
+
+
+def _disposition_filename(value: str | None) -> str | None:
+    if not value:
+        return None
+    for part in value.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename="):
+            return part[len("filename="):].strip().strip('"')
+    return None
+
+
+def _check(response: Response[Any]) -> Any:
+    status = int(response.status_code)
+    if 200 <= status < 300:
+        return response.parsed
+    try:
+        body = json.loads(response.content)
+    except ValueError:
+        body = None
+    raise FacadeApiError(status, body)
+
+
+class FacadeExtensionsClient:
+    """Client for the BMA extension routes of the Anthropic-compatible facade."""
+
+    def __init__(self, api_key: str, base_url: str, *, project_id: str | None = None) -> None:
+        api_key = (api_key or "").strip()
+        if not api_key:
+            raise ValueError("bma facade: api_key is required")
+        base_url = (base_url or "").strip().rstrip("/")
+        if not base_url.startswith(("http://", "https://")):
+            raise ValueError("bma facade: base_url must be an http or https origin")
+        if base_url.endswith("/v1"):
+            raise ValueError("bma facade: base_url must be the origin without /v1")
+        headers = {"x-api-key": api_key}
+        if project_id:
+            headers["x-bma-project-id"] = project_id
+        self.raw = Client(base_url=base_url, headers=headers)
+
+    def close(self) -> None:
+        self.raw.get_httpx_client().close()
+
+    def __enter__(self) -> FacadeExtensionsClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def get_session_desktop_stream(
+        self,
+        session_id: str,
+        *,
+        desktop_session_id: str,
+        ttl_seconds: int | None = None,
+        origin: str | None = None,
+    ) -> DesktopStream:
+        """BMA extension: ``GET /v1/sessions/{session_id}/desktop/stream``."""
+        return _check(
+            get_session_desktop_stream.sync_detailed(
+                session_id,
+                client=self.raw,
+                desktop_session_id=desktop_session_id,
+                ttl_seconds=UNSET if ttl_seconds is None else ttl_seconds,
+                origin=UNSET if origin is None else origin,
+            )
+        )
+
+    def upload_session_file(self, session_id: str, filename: str, content: bytes) -> SessionFile:
+        """BMA extension: ``POST /v1/sessions/{session_id}/files`` (1 byte to 8 MiB)."""
+        if not 0 < len(content) <= MAX_SESSION_FILE_BYTES:
+            raise ValueError(f"bma facade: session file must be 1..{MAX_SESSION_FILE_BYTES} bytes")
+        body = UploadSessionFileBody(file=File(payload=io.BytesIO(content), file_name=filename))
+        return _check(upload_session_file.sync_detailed(session_id, client=self.raw, body=body))
+
+    def list_session_files(self, session_id: str, *, limit: int | None = None, page: str | None = None) -> SessionFilePage:
+        """BMA extension: ``GET /v1/sessions/{session_id}/files``."""
+        return _check(
+            list_session_files.sync_detailed(
+                session_id,
+                client=self.raw,
+                limit=UNSET if limit is None else limit,
+                page=UNSET if page is None else page,
+            )
+        )
+
+    def download_session_file(self, session_id: str, file_id: str) -> SessionFileContent:
+        """BMA extension: ``GET /v1/sessions/{session_id}/files/{file_id}/content``."""
+        response = download_session_file.sync_detailed(session_id, file_id, client=self.raw)
+        parsed = _check(response)
+        if not isinstance(parsed, File):
+            raise FacadeApiError(int(response.status_code), None)
+        headers = response.headers
+        return SessionFileContent(
+            content=parsed.payload.read(),
+            content_type=headers.get("content-type"),
+            filename=_disposition_filename(headers.get("content-disposition")),
+            digest=headers.get("x-bma-file-digest"),
+        )
+
+    def add_session_resource(
+        self, session_id: str, file_id: str, *, mount_path: str | None = None
+    ) -> FileResource:
+        """BMA extension: ``POST /v1/sessions/{session_id}/resources``.
+
+        Mounts a project file by reference; the returned ``file_id`` is the
+        session instance created for the mount.
+        """
+        body = FileResourceParams(
+            type_="file", file_id=file_id, mount_path=UNSET if mount_path is None else mount_path
+        )
+        return _check(add_session_resource.sync_detailed(session_id, client=self.raw, body=body))
+
+    def list_session_resources(self, session_id: str) -> FileResourcePage:
+        """BMA extension: ``GET /v1/sessions/{session_id}/resources``."""
+        return _check(list_session_resources.sync_detailed(session_id, client=self.raw))
+
+    def delete_session_resource(self, session_id: str, resource_id: str) -> DeletedSessionResource:
+        """BMA extension: ``DELETE /v1/sessions/{session_id}/resources/{resource_id}``."""
+        return _check(delete_session_resource.sync_detailed(session_id, resource_id, client=self.raw))

bma_sdk-0.4.0/src/bma_sdk/facade_extensions/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing BMA extensions to the Anthropic Managed Agents API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

bma_sdk-0.4.0/src/bma_sdk/facade_extensions/_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

bma_sdk-0.4.0/src/bma_sdk/facade_extensions/_generated/api/default/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""