openbot-sdk 0.3.0__py3-none-any.whl

openbot_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""
+openbot-sdk — Python SDK for OpenBot.ai.
+
+openbot-sdk is a thin authenticated client for the OpenBot platform API.
+
+Example:
+    >>> import openbot_sdk
+    >>> client = openbot_sdk.Client()
+    >>> status = client.request("GET", "/status")
+    >>> print(status)
+"""
+
+from openbot_sdk._client import Client
+from openbot_sdk._errors import (
+    APIError,
+    APIResponseError,
+    AuthenticationError,
+    ClientClosedError,
+    NetworkError,
+    OpenBotError,
+)
+from openbot_sdk._version import __version__
+
+__all__ = [
+    "Client",
+    "OpenBotError",
+    "AuthenticationError",
+    "ClientClosedError",
+    "APIError",
+    "APIResponseError",
+    "NetworkError",
+    "__version__",
+]

openbot_sdk/_client.py

@@ -0,0 +1,281 @@
+"""OpenBot.ai Python client."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Callable, cast
+from urllib.parse import urlparse
+
+import httpx
+
+from openbot_sdk._errors import (
+    APIError,
+    APIResponseError,
+    AuthenticationError,
+    ClientClosedError,
+    NetworkError,
+)
+
+DEFAULT_BASE_URL = "https://api.openbot.ai/v1"
+RETRYABLE_STATUS_CODES = frozenset({429, 502, 503, 504})
+# A mutation's Idempotency-Key is bound to its first outcome. The gateway burns
+# the key when the upstream fails (502), so a same-key retry would only turn the
+# real error into a 409; 502 is therefore never retried for mutations.
+KEYED_MUTATION_RETRYABLE_STATUS_CODES = frozenset({429, 503, 504})
+# The first call with this key is still running; waiting and replaying the same
+# key eventually returns the stored result without a second charge.
+IN_PROGRESS_ERROR_CODES = frozenset({"invocation_in_progress"})
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "DELETE"})
+
+
+class Client:
+    """
+    Client for the OpenBot.ai API.
+
+    Args:
+        api_key: OpenBot.ai API key. Falls back to the ``OPENBOT_API_KEY``
+            environment variable if not provided.
+        base_url: Base URL for the OpenBot.ai API.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        download_timeout: float = 300.0,
+        max_retries: int = 2,
+        retry_backoff: float = 0.25,
+        allow_insecure_http: bool = False,
+        sleeper: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("OPENBOT_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "API key is required. Provide it via the api_key argument "
+                "or set the OPENBOT_API_KEY environment variable."
+            )
+
+        parsed_url = urlparse(base_url)
+        if parsed_url.scheme not in {"http", "https"} or not parsed_url.netloc:
+            raise ValueError("base_url must be an absolute HTTP(S) URL")
+        if parsed_url.scheme != "https" and not allow_insecure_http:
+            raise ValueError(
+                "base_url must use HTTPS; pass allow_insecure_http=True only for local testing"
+            )
+        if timeout <= 0 or download_timeout <= 0:
+            raise ValueError("timeouts must be greater than zero")
+        if max_retries < 0 or retry_backoff < 0:
+            raise ValueError("retry settings cannot be negative")
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.download_timeout = download_timeout
+        self.max_retries = max_retries
+        self.retry_backoff = retry_backoff
+        self._sleep = sleeper
+        self._clock = clock
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": f"openbot_sdk-python/{self._version()}",
+            },
+            timeout=self.timeout,
+        )
+        self._closed = False
+
+    def _version(self) -> str:
+        from openbot_sdk._version import __version__
+
+        return __version__
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make an HTTP request and return the JSON response."""
+        self._ensure_open()
+        request_headers = {**headers} if headers else None
+        response = self._send_with_retries(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=request_headers,
+            timeout=self.timeout,
+        )
+        self._raise_for_error(response)
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise APIResponseError("API returned a non-JSON response") from exc
+        if not isinstance(payload, dict):
+            raise APIResponseError("API returned JSON with an unexpected top-level type")
+        return cast(dict[str, Any], payload)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Call any OpenBot platform JSON API endpoint with this client's API key."""
+        return self._request(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=headers,
+        )
+
+    def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Make an authenticated request and return the raw response body."""
+        self._ensure_open()
+        request_timeout = self.download_timeout if timeout is None else timeout
+        if request_timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        response = self._send_with_retries(method, path, timeout=request_timeout)
+        self._raise_for_error(response)
+        return response.content
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Call an OpenBot platform endpoint and return its authenticated byte response."""
+        return self._request_bytes(method, path, timeout=timeout)
+
+    def _send_with_retries(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float,
+    ) -> httpx.Response:
+        normalized_method = method.upper()
+        idempotent_method = normalized_method in IDEMPOTENT_METHODS
+        keyed_mutation = not idempotent_method and bool(
+            headers and headers.get("Idempotency-Key")
+        )
+        can_retry = idempotent_method or keyed_mutation
+        attempts = self.max_retries + 1 if can_retry else 1
+
+        for attempt in range(attempts):
+            try:
+                response = self._http.request(
+                    normalized_method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=headers,
+                    timeout=timeout,
+                )
+            except httpx.RequestError as exc:
+                if attempt + 1 >= attempts:
+                    raise NetworkError(f"API request failed: {exc}") from exc
+                self._sleep_before_retry(attempt, None)
+                continue
+
+            retryable = (
+                self._keyed_mutation_should_retry(response)
+                if keyed_mutation
+                else response.status_code in RETRYABLE_STATUS_CODES
+            )
+            if not retryable or attempt + 1 >= attempts:
+                return response
+            self._sleep_before_retry(attempt, response.headers.get("Retry-After"))
+
+        raise NetworkError("API request failed after retries")
+
+    def _keyed_mutation_should_retry(self, response: httpx.Response) -> bool:
+        if response.status_code in KEYED_MUTATION_RETRYABLE_STATUS_CODES:
+            return True
+        return response.status_code == 409 and self._error_code(response) in IN_PROGRESS_ERROR_CODES
+
+    @staticmethod
+    def _error_code(response: httpx.Response) -> str | None:
+        try:
+            payload = response.json()
+        except ValueError:
+            return None
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            code = payload["error"].get("code")
+            return code if isinstance(code, str) else None
+        return None
+
+    def _sleep_before_retry(self, attempt: int, retry_after: str | None) -> None:
+        delay = self.retry_backoff * (2**attempt)
+        if retry_after is not None:
+            try:
+                delay = min(float(retry_after), 60.0)
+            except ValueError:
+                pass
+        if delay > 0:
+            self._sleep(delay)
+
+    def _raise_for_error(self, response: httpx.Response) -> None:
+        if response.status_code < 400:
+            return
+
+        message = f"API request failed ({response.status_code})"
+        code: str | None = None
+        retryable: bool | None = None
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            error = payload["error"]
+            if isinstance(error.get("message"), str):
+                message = error["message"]
+            if isinstance(error.get("code"), str):
+                code = error["code"]
+            if isinstance(error.get("retryable"), bool):
+                retryable = error["retryable"]
+        elif response.text:
+            message = f"{message}: {response.text}"
+        raise APIError(
+            message,
+            status_code=response.status_code,
+            code=code,
+            retryable=retryable,
+        )
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ClientClosedError("Client is closed")
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if not self._closed:
+            self._http.close()
+            self._closed = True
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

openbot_sdk/_contract.py

@@ -0,0 +1,31 @@
+"""Compatibility checks between the SDK and the served OpenBot OpenAPI contract."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def openapi_compatibility_errors(spec: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    paths = spec.get("paths")
+    if not isinstance(paths, dict):
+        return ["OpenAPI paths must be an object"]
+    me = paths.get("/v1/me")
+    if not isinstance(me, dict) or "get" not in me:
+        errors.append("GET /v1/me is required for API-key context probing")
+    forbidden = ("/v1/bench", "/v1/synth", "/v1/data/")
+    for path in paths:
+        removed = isinstance(path, str) and any(
+            path == prefix or path.startswith(prefix) for prefix in forbidden
+        )
+        if removed:
+            errors.append(f"removed product path is still published: {path}")
+    schemes = spec.get("components", {}).get("securitySchemes", {})
+    if not isinstance(schemes, dict) or not any(
+        isinstance(value, dict)
+        and value.get("type") == "http"
+        and value.get("scheme") == "bearer"
+        for value in schemes.values()
+    ):
+        errors.append("a Bearer security scheme is required")
+    return errors

openbot_sdk/_errors.py

@@ -0,0 +1,40 @@
+"""OpenBot.ai SDK errors."""
+
+from __future__ import annotations
+
+
+class OpenBotError(Exception):
+    """Base error for all OpenBot.ai SDK errors."""
+
+
+class AuthenticationError(OpenBotError):
+    """Raised when the API key is missing or invalid."""
+
+
+class APIError(OpenBotError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        *,
+        code: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.retryable = retryable
+
+
+class APIResponseError(OpenBotError):
+    """Raised when a successful API response has an invalid payload."""
+
+
+class NetworkError(OpenBotError):
+    """Raised when the API cannot be reached or a request times out."""
+
+
+class ClientClosedError(OpenBotError):
+    """Raised when a closed client is used."""

openbot_sdk/_version.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("openbot-sdk")
+except PackageNotFoundError:  # pragma: no cover - raw source tree without installation
+    __version__ = "0+unknown"

openbot_sdk/py.typed

@@ -0,0 +1 @@
+

openbot_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: openbot-sdk
+Version: 0.3.0
+Summary: Thin Python client for the OpenBot.ai platform API.
+Project-URL: Homepage, https://openbot.ai
+Project-URL: Documentation, https://openbot.ai/api/docs
+Project-URL: Repository, https://github.com/openbotai/openbot-sdk
+Project-URL: Issues, https://github.com/openbotai/openbot-sdk/issues
+Author-email: "OpenBot.ai" <hello@openbot.ai>
+License: MIT
+License-File: LICENSE
+Keywords: API client,API key,HTTP client,OpenBot.ai,VLA,embodied AI,robotics
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openbot-sdk
+
+`openbot-sdk` is the thin Python client for the
+[OpenBot.ai platform API](https://openbot.ai/api/docs).
+
+It handles API-key authentication, HTTP requests, timeouts, bounded retries,
+and typed errors. It does not process robot data and is not tied to a Hosted
+Data product.
+
+## Install
+
+```bash
+pip install openbot-sdk
+```
+
+Requires Python 3.9+.
+
+## Authentication
+
+```bash
+export OPENBOT_API_KEY="ob_..."
+```
+
+```python
+from openbot_sdk import Client
+
+client = Client()  # reads OPENBOT_API_KEY
+status = client.request("GET", "/status")
+print(status)
+```
+
+You can also pass the key explicitly:
+
+```python
+client = Client(api_key="ob_...")
+```
+
+## Call platform APIs
+
+Use `request` for JSON APIs and `request_bytes` for byte responses:
+
+```python
+payload = client.request(
+    "POST",
+    "/some-resource",
+    json={"name": "example"},
+    headers={"Idempotency-Key": "request-123"},
+)
+
+content = client.request_bytes("GET", "/some-artifact")
+```
+
+Only call routes published in the current OpenBot OpenAPI document. As the
+platform adds real APIs, the SDK may add small convenience wrappers for those
+same contracts.
+
+The SDK intentionally has no Bench, Synth, or Hosted Data resource wrapper.
+Convenience wrappers correspond to operations in the checked OpenAPI contract;
+`request(...)` remains the forward-compatible escape hatch.
+
+## Errors, retries, and security
+
+```python
+from openbot_sdk import APIError, NetworkError
+
+try:
+    payload = client.request("GET", "/status")
+except APIError as exc:
+    print(exc.status_code)
+except NetworkError as exc:
+    print(exc)
+```
+
+The client retries idempotent methods on transport errors, `429`, and
+transient `5xx` responses. Mutations carrying an `Idempotency-Key` are retried
+with the same key only where that is safe: transport errors, `429`, `503`
+(for example `settlement_pending`), `504`, and `409 invocation_in_progress`.
+A `502` is returned immediately, because the gateway burns the key when the
+upstream fails; retry that call with a new key. For `POST /v1/invoke/:slug`,
+create the client with `timeout` (seconds) larger than the API's
+`x-openbot-timeout-ms`, so a slow upstream is not mistaken for a network failure.
+Plain HTTP base URLs are rejected by default; enable them only for explicit
+local testing.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python scripts/check_version.py
+python scripts/check_openapi_contract.py /path/to/openapi.json
+pytest -v
+ruff check src tests
+mypy src
+python -m build
+```
+
+`VERSION` is the package version source of truth. Release tags use `v<version>`.
+
+## Package boundaries
+
+- `openbot-sdk`: OpenBot platform API client.
+- `openbot-data`: local robot/ego data processing library.
+- OpenBot platform: server-side API implementation and infrastructure.
+
+## License
+
+MIT

openbot_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+openbot_sdk/__init__.py,sha256=Gxqx_OHi4lOFmUDXq8nzAMXooiRsMnmElE3ExbFRX3k,693
+openbot_sdk/_client.py,sha256=LPiB2ZvtijuJDel9nyWx4gQ4FD8j0cqC8oo_hSPHsDs,9736
+openbot_sdk/_contract.py,sha256=ubku0k8eqNN9lNS7Wk-j3WzoMLP66qv9st1_SpCWfYU,1188
+openbot_sdk/_errors.py,sha256=xnzQm-2HVN5FsE41EqGpZW43laDovDvWV9Rrn_IEmPU,974
+openbot_sdk/_version.py,sha256=bS1AeZ1VrsFMXQNQwSETkDdXyNoBsjXkLw7qDYbTRYs,226
+openbot_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+openbot_sdk-0.3.0.dist-info/METADATA,sha256=X4F37COsbM9AGPIK9n4OE5mvk2fKcFpxQtI6c35F-F8,4313
+openbot_sdk-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openbot_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=b0Vh5bHTOKkuhoBZ6HsAZyXm2Dm9p0q2MoUqYNZ15tc,1067
+openbot_sdk-0.3.0.dist-info/RECORD,,

openbot_sdk-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

openbot_sdk-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenBot.ai
+
+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.