openbot-sdk 0.3.0__tar.gz

openbot_sdk-0.3.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

openbot_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.3.0
+
+### Removed
+
+- Ego Semantic Annotation create/get/cancel/result wrappers. The operation is
+  discontinued, and the OpenAPI compatibility check no longer requires its routes.
+
+### Fixed
+
+- Mutations carrying an `Idempotency-Key` are no longer retried after `502`:
+  the gateway burns the key when the upstream fails, so a same-key retry masked
+  the real error as `409`. `409 invocation_in_progress` is now retried with the
+  same key until the stored result is replayed.
+- `scripts/check_openapi_contract.py` sends an SDK User-Agent; the production
+  edge rejected the default Python-urllib agent with `403`, which would have
+  failed the release workflow.
+
+## 0.2.0
+
+### Added
+
+- Ego Semantic Annotation create/get/cancel/result wrappers.
+- Mandatory stable idempotency key, source SHA-256, and bounded duration checks.
+- OpenAPI compatibility checks for the complete asynchronous operation surface.
+
+### Safety
+
+- The wrapper does not perform inference locally or fabricate fallback results.
+- Feature-gate, concurrency, provider, and billing failures remain structured API errors.
+
+## 0.1.0
+
+### Changed
+
+- Removed the unreleased Bench wrapper and run polling types.
+- Kept the SDK as a neutral authenticated client for operations published by
+  the production OpenAPI contract.
+- Removed customer webhook signing helpers until a deployed asynchronous API
+  publishes a callback contract.
+
+## 0.0.2
+
+### Added
+
+- Public `Client.request(...)` for authenticated JSON platform API calls.
+- Public `Client.request_bytes(...)` for authenticated byte responses.
+- Configurable request/download timeouts and bounded retry behavior.
+- Typed network and response errors.
+- Single-source version and release-tag validation.
+
+### Clarified
+
+- `openbot-sdk` is only a thin client for the OpenBot platform API.
+- Robot/ego data processing belongs to `openbot-data`.
+- No Hosted Data resources, jobs, uploads, review, or export helpers are part of
+  this package.
+
+## 0.0.1
+
+### Added
+
+- Initial API-key client.
+- Bench contract wrapper and polling result helper.
+- Webhook signature verification.

openbot_sdk-0.3.0/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.

openbot_sdk-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,107 @@
+# 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/VERSION

@@ -0,0 +1 @@
+0.3.0

openbot_sdk-0.3.0/docs/README.md

@@ -0,0 +1,6 @@
+# Documentation
+
+- [Getting started](getting-started.md)
+- [API reference](api-reference.md)
+
+The live OpenBot OpenAPI document remains the endpoint source of truth.

openbot_sdk-0.3.0/docs/api-reference.md

@@ -0,0 +1,44 @@
+# Client reference
+
+## `Client`
+
+```python
+Client(
+    api_key=None,
+    base_url="https://api.openbot.ai/v1",
+    timeout=60.0,
+    download_timeout=300.0,
+    max_retries=2,
+    retry_backoff=0.25,
+    allow_insecure_http=False,
+)
+```
+
+`api_key` falls back to `OPENBOT_API_KEY`.
+
+## `request`
+
+```python
+client.request(method, path, json=None, params=None, headers=None)
+```
+
+Returns a JSON object. Non-JSON or non-object responses raise
+`APIResponseError`; HTTP failures raise `APIError`.
+
+## `request_bytes`
+
+```python
+client.request_bytes(method, path, timeout=None)
+```
+
+Returns raw response bytes.
+
+## Errors
+
+- `AuthenticationError`
+- `APIError`
+- `APIResponseError`
+- `NetworkError`
+
+Endpoint-specific wrappers are checked against the matching OpenBot OpenAPI
+operation before release.

openbot_sdk-0.3.0/docs/getting-started.md

@@ -0,0 +1,26 @@
+# Getting started
+
+```bash
+pip install openbot-sdk
+export OPENBOT_API_KEY="ob_..."
+```
+
+```python
+from openbot_sdk import Client
+
+with Client() as client:
+    status = client.request("GET", "/status")
+    print(status)
+```
+
+For local API development only:
+
+```python
+client = Client(
+    api_key="ob_local_test",
+    base_url="http://127.0.0.1:8787/v1",
+    allow_insecure_http=True,
+)
+```
+
+The SDK contains no Hosted Data workflow or robot-data processing logic.

openbot_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "openbot-sdk"
+dynamic = ["version"]
+description = "Thin Python client for the OpenBot.ai platform API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "OpenBot.ai", email = "hello@openbot.ai" }
+]
+keywords = [
+  "OpenBot.ai",
+  "API client",
+  "API key",
+  "embodied AI",
+  "VLA",
+  "HTTP client",
+  "robotics",
+]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.0.0",
+  "pytest>=7.0.0",
+  "pytest-asyncio>=0.23.0",
+  "respx>=0.22.0",
+  "ruff>=0.6.0",
+  "mypy>=1.11.0",
+  "twine>=6.2.0",
+]
+
+[project.urls]
+Homepage = "https://openbot.ai"
+Documentation = "https://openbot.ai/api/docs"
+Repository = "https://github.com/openbotai/openbot-sdk"
+Issues = "https://github.com/openbotai/openbot-sdk/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openbot_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/docs",
+  "/LICENSE",
+  "/README.md",
+  "/CHANGELOG.md",
+  "/VERSION",
+  "/scripts",
+  "/src",
+  "/tests",
+  "/pyproject.toml",
+]
+exclude = [
+  "**/__pycache__",
+  "**/*.pyc",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.hatch.version]
+path = "VERSION"
+pattern = "^(?P<version>[^\\s]+)$"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

openbot_sdk-0.3.0/scripts/check_openapi_contract.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Validate an OpenBot OpenAPI file or URL against the SDK contract."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+from urllib.request import Request, urlopen
+
+from openbot_sdk._contract import openapi_compatibility_errors
+from openbot_sdk._version import __version__
+
+
+def load(source: str) -> dict[str, Any]:
+    if source.startswith(("https://", "http://")):
+        # The production edge rejects the default Python-urllib User-Agent with 403.
+        request = Request(source, headers={"User-Agent": f"openbot_sdk-python/{__version__}"})
+        with urlopen(request, timeout=20) as response:  # noqa: S310 - explicit CLI input
+            return cast(dict[str, Any], json.load(response))
+    return cast(dict[str, Any], json.loads(Path(source).read_text(encoding="utf-8")))
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: check_openapi_contract.py FILE_OR_URL", file=sys.stderr)
+        return 2
+    errors = openapi_compatibility_errors(load(sys.argv[1]))
+    if errors:
+        print("OpenAPI contract is incompatible:", file=sys.stderr)
+        for error in errors:
+            print(f"- {error}", file=sys.stderr)
+        return 1
+    print(f"OpenAPI contract is compatible with openbot-sdk {__version__}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openbot_sdk-0.3.0/scripts/check_version.py

@@ -0,0 +1,61 @@
+"""Validate the package version source, metadata, changelog, and optional tag."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+VERSION_PATTERN = re.compile(
+    r"^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)"
+    r"(?:(?:a|b|rc)(?:0|[1-9]\d*))?(?:\.post(?:0|[1-9]\d*))?"
+    r"(?:\.dev(?:0|[1-9]\d*))?$"
+)
+
+
+def fail(message: str) -> None:
+    print(f"version check failed: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tag", help="Git tag to compare with v<version>")
+    args = parser.parse_args()
+
+    version = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
+    if not VERSION_PATTERN.fullmatch(version):
+        fail(f"VERSION is not a supported PEP 440 release: {version!r}")
+
+    pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    project_match = re.search(r"(?ms)^\[project\]\s*(.*?)(?=^\[|\Z)", pyproject)
+    if project_match is None:
+        fail("pyproject.toml has no [project] section")
+    project = project_match.group(1)
+    if not re.search(r'^dynamic\s*=\s*\[\s*"version"\s*\]\s*$', project, re.MULTILINE):
+        fail("pyproject.toml must declare only a dynamic project version")
+    if re.search(r"^version\s*=", project, re.MULTILINE):
+        fail("pyproject.toml must not declare a static project version")
+
+    hatch_match = re.search(
+        r"(?ms)^\[tool\.hatch\.version\]\s*(.*?)(?=^\[|\Z)", pyproject
+    )
+    if hatch_match is None or not re.search(
+        r'^path\s*=\s*"VERSION"\s*$', hatch_match.group(1), re.MULTILINE
+    ):
+        fail("Hatch version source must be VERSION")
+
+    changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+    if f"## {version}" not in changelog:
+        fail(f"CHANGELOG.md has no section for {version}")
+
+    if args.tag and args.tag != f"v{version}":
+        fail(f"tag {args.tag!r} does not match v{version}")
+
+    print(f"version {version} is consistent")
+
+
+if __name__ == "__main__":
+    main()

openbot_sdk-0.3.0/scripts/test_matrix.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+for version in 3.9 3.10 3.11 3.12; do
+  echo "Testing openbot-sdk on Python ${version}"
+  uv run --isolated --python "${version}" --extra dev pytest -q
+done
+
+echo "Running static checks against the Python 3.9 compatibility target"
+uv run --isolated --python 3.9 --extra dev ruff check .
+uv run --isolated --python 3.9 --extra dev mypy src

openbot_sdk-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/openbot_sdk/py.typed

@@ -0,0 +1 @@
+

openbot_sdk-0.3.0/tests/test_client.py

@@ -0,0 +1,230 @@
+import os
+
+import pytest
+import respx
+from httpx import ConnectError, Request, Response
+
+import openbot_sdk
+from openbot_sdk import AuthenticationError
+
+
+@pytest.fixture
+def mock_api() -> respx.MockRouter:
+    with respx.mock(base_url="https://api.openbot.ai/v1") as router:
+        yield router
+
+
+def test_client_requires_api_key() -> None:
+    os.environ.pop("OPENBOT_API_KEY", None)
+    with pytest.raises(AuthenticationError):
+        openbot_sdk.Client()
+
+
+def test_client_accepts_api_key_argument() -> None:
+    client = openbot_sdk.Client(api_key="test-key")
+    assert client.api_key == "test-key"
+    client.close()
+
+
+def test_client_uses_environment_variable() -> None:
+    os.environ["OPENBOT_API_KEY"] = "env-key"
+    client = openbot_sdk.Client()
+    assert client.api_key == "env-key"
+    client.close()
+    os.environ.pop("OPENBOT_API_KEY", None)
+
+
+def test_client_request_success(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/me").respond(200, json={"key_id": "key_123", "scopes": ["api:invoke"]})
+
+    client = openbot_sdk.Client(api_key="test-key")
+    data = client.request("GET", "/me")
+
+    assert data["key_id"] == "key_123"
+    client.close()
+
+
+def test_client_exposes_only_platform_resources() -> None:
+    client = openbot_sdk.Client(api_key="test-key")
+    assert not hasattr(client, "bench")
+    assert not hasattr(client, "synth")
+    assert not hasattr(client, "data")
+    client.close()
+
+
+def test_client_request_raises_api_error(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/unknown").respond(404, text="Not found")
+
+    client = openbot_sdk.Client(api_key="test-key")
+    with pytest.raises(openbot_sdk.APIError) as exc_info:
+        client._request("GET", "/unknown")
+
+    assert exc_info.value.status_code == 404
+    client.close()
+
+
+def test_client_exposes_structured_api_error(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/status").respond(
+        409,
+        json={
+            "error": {
+                "code": "conflict",
+                "message": "The request conflicts with current state",
+                "retryable": False,
+            }
+        },
+    )
+    client = openbot_sdk.Client(api_key="test-key")
+
+    with pytest.raises(openbot_sdk.APIError) as exc_info:
+        client.request("GET", "/status")
+
+    assert exc_info.value.status_code == 409
+    assert exc_info.value.code == "conflict"
+    assert exc_info.value.retryable is False
+    client.close()
+
+
+def test_client_request_bytes(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/artifact").respond(200, content=b"artifact-bytes")
+    client = openbot_sdk.Client(api_key="test-key")
+
+    assert client.request_bytes("GET", "/artifact") == b"artifact-bytes"
+    client.close()
+
+
+def test_closed_client_rejects_requests() -> None:
+    client = openbot_sdk.Client(api_key="test-key")
+    client.close()
+
+    with pytest.raises(openbot_sdk.ClientClosedError):
+        client.request("GET", "/status")
+
+
+def test_client_rejects_insecure_base_url() -> None:
+    with pytest.raises(ValueError, match="HTTPS"):
+        openbot_sdk.Client(api_key="test-key", base_url="http://api.example.test/v1")
+
+
+def test_client_allows_explicit_local_http_for_testing() -> None:
+    client = openbot_sdk.Client(
+        api_key="test-key",
+        base_url="http://127.0.0.1:8787/v1",
+        allow_insecure_http=True,
+    )
+    client.close()
+
+
+def test_client_wraps_network_errors(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/me").mock(
+        side_effect=ConnectError("offline", request=Request("GET", "https://api.openbot.ai"))
+    )
+    client = openbot_sdk.Client(api_key="test-key", max_retries=0)
+
+    with pytest.raises(openbot_sdk.NetworkError, match="offline"):
+        client._request("GET", "/me")
+    client.close()
+
+
+def test_client_rejects_invalid_success_payload(mock_api: respx.MockRouter) -> None:
+    mock_api.get("/me").respond(200, text="not-json")
+    client = openbot_sdk.Client(api_key="test-key")
+
+    with pytest.raises(openbot_sdk.APIResponseError, match="non-JSON"):
+        client._request("GET", "/me")
+    client.close()
+
+
+def test_client_retries_idempotent_request(mock_api: respx.MockRouter) -> None:
+    route = mock_api.get("/me")
+    route.side_effect = [
+        Response(503, text="busy"),
+        Response(200, json={"key_id": "key_123", "scopes": ["api:invoke"]}),
+    ]
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    data = client._request("GET", "/me")
+
+    assert data["key_id"] == "key_123"
+    assert route.call_count == 2
+    client.close()
+
+
+def test_keyed_mutation_does_not_retry_a_burned_key_after_502(
+    mock_api: respx.MockRouter,
+) -> None:
+    route = mock_api.post("/invoke/judge")
+    route.side_effect = [
+        Response(502, json={"error": {"code": "upstream_error", "message": "HTTP 500"}}),
+        Response(409, json={"error": {"code": "upstream_error", "message": "failed"}}),
+    ]
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    with pytest.raises(openbot_sdk.APIError) as exc_info:
+        client.request("POST", "/invoke/judge", json={}, headers={"Idempotency-Key": "key-00001"})
+
+    assert exc_info.value.status_code == 502
+    assert exc_info.value.code == "upstream_error"
+    assert route.call_count == 1
+    client.close()
+
+
+def test_keyed_mutation_waits_for_an_in_progress_invocation(
+    mock_api: respx.MockRouter,
+) -> None:
+    route = mock_api.post("/invoke/judge")
+    route.side_effect = [
+        ConnectError("reset"),
+        Response(409, json={"error": {"code": "invocation_in_progress", "message": "busy"}}),
+        Response(200, json={"verdict": "accept"}),
+    ]
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    data = client.request(
+        "POST", "/invoke/judge", json={}, headers={"Idempotency-Key": "key-00001"}
+    )
+
+    assert data == {"verdict": "accept"}
+    assert route.call_count == 3
+    assert {call.request.headers["Idempotency-Key"] for call in route.calls} == {"key-00001"}
+    client.close()
+
+
+def test_keyed_mutation_retries_settlement_pending(mock_api: respx.MockRouter) -> None:
+    route = mock_api.post("/invoke/judge")
+    route.side_effect = [
+        Response(503, json={"error": {"code": "settlement_pending", "message": "retry"}}),
+        Response(200, json={"verdict": "accept"}),
+    ]
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    data = client.request(
+        "POST", "/invoke/judge", json={}, headers={"Idempotency-Key": "key-00001"}
+    )
+
+    assert data == {"verdict": "accept"}
+    assert route.call_count == 2
+    client.close()
+
+
+def test_keyed_mutation_does_not_retry_other_conflicts(mock_api: respx.MockRouter) -> None:
+    route = mock_api.post("/invoke/judge")
+    route.respond(409, json={"error": {"code": "idempotency_key_conflict", "message": "x"}})
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    with pytest.raises(openbot_sdk.APIError) as exc_info:
+        client.request("POST", "/invoke/judge", json={}, headers={"Idempotency-Key": "key-00001"})
+
+    assert exc_info.value.code == "idempotency_key_conflict"
+    assert route.call_count == 1
+    client.close()
+
+
+def test_idempotent_request_still_retries_502(mock_api: respx.MockRouter) -> None:
+    route = mock_api.get("/me")
+    route.side_effect = [Response(502, text="bad gateway"), Response(200, json={"ok": True})]
+    client = openbot_sdk.Client(api_key="test-key", retry_backoff=0)
+
+    assert client.request("GET", "/me") == {"ok": True}
+    assert route.call_count == 2
+    client.close()

openbot_sdk-0.3.0/tests/test_contract.py

@@ -0,0 +1,46 @@
+from openbot_sdk._contract import openapi_compatibility_errors
+
+
+def required_paths() -> dict[str, dict[str, object]]:
+    return {
+        "/v1/me": {"get": {}},
+    }
+
+
+def test_neutral_sdk_accepts_api_context_contract() -> None:
+    spec = {
+        "paths": required_paths(),
+        "components": {
+            "securitySchemes": {
+                "ApiKeyAuth": {"type": "http", "scheme": "bearer"},
+            }
+        },
+    }
+    assert openapi_compatibility_errors(spec) == []
+
+
+def test_neutral_sdk_rejects_removed_product_paths() -> None:
+    spec = {
+        "paths": {
+            **required_paths(),
+            "/v1/bench/rollouts": {"post": {}},
+            "/v1/synth/jobs": {"post": {}},
+        },
+        "components": {
+            "securitySchemes": {
+                "ApiKeyAuth": {"type": "http", "scheme": "bearer"},
+            }
+        },
+    }
+    assert openapi_compatibility_errors(spec) == [
+        "removed product path is still published: /v1/bench/rollouts",
+        "removed product path is still published: /v1/synth/jobs",
+    ]
+
+
+def test_sdk_requires_the_api_key_context_route() -> None:
+    errors = openapi_compatibility_errors({
+        "paths": {},
+        "components": {"securitySchemes": {"Bearer": {"type": "http", "scheme": "bearer"}}},
+    })
+    assert errors == ["GET /v1/me is required for API-key context probing"]

openbot_sdk-0.3.0/tests/test_version.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+import openbot_sdk
+
+
+def test_runtime_version_matches_package_metadata() -> None:
+    assert openbot_sdk.__version__ == version("openbot-sdk")