openrelay-sdk 0.1.0__tar.gz

openrelay_sdk-0.1.0/.gitignore

@@ -0,0 +1,164 @@
+# Dependencies
+node_modules
+.pnpm-store
+
+# Next.js
+.next
+out
+
+# Build
+dist
+build
+
+# Environment
+.env
+.env.local
+.env.*.local
+# scripts/local-stack.sh backs up an existing .env.local here on its first run,
+# so the copy needs the same guard as the original.
+.env.local.bak
+
+# Local stack state (scripts/local-stack.sh): ops org id, JWT secret, logs
+.local-stack/
+# Legacy state dir from the pre-rename script; migrated to .local-stack on `up`.
+# Kept ignored so its JWT secret is never swept into a commit before migration.
+.local-toolbox/
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+.DS_Store
+
+# Claude Code per-developer state (MCP server enablement, permission approvals):
+# differs per machine, never commit
+.claude/settings.local.json
+# Agent-local state: worktrees (`git add -A` would commit each one as a gitlink),
+# task lists and caches
+.claude/worktrees/
+.claude/tasks/
+.claude/cache/
+
+# A saved terraform plan holds sensitive values in cleartext and must never be
+# committed. infra/terraform/scripts/tf-run.sh writes its plans outside the
+# worktree entirely; this catches one run by hand with -out= inside it.
+*.tfplan
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Vercel
+.vercel
+
+.env.prod-local
+
+# Secrets
+secrets/
+infra/.secrets/
+**/.secrets/
+*-key.pem
+# age private decryption key: NEVER commit (only the encrypted .env.claude.* files + the public .age-recipients are)
+.env.keys
+# local Stripe API keys (holds sk_live/pk_live): NEVER commit
+.stripe.keys
+# local Cerebras API key (csk-... bearer token; lives in SSM in beta/prod). NEVER commit
+.cerebras.key
+
+# Python SDK
+sdks/python/.venv/
+sdks/python/dist/
+sdks/python/*.egg-info/
+sdks/python/dev.py
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Test results
+e2e/test-results/
+
+# Schemathesis local example database, generated config, and reports
+# (created by `st run` / `schemathesis run`; schemathesis.toml is written
+# fresh by .github/workflows/schemathesis.yml on every run, never committed)
+.schemathesis/
+schemathesis.toml
+schemathesis-report/
+
+# Compiled binaries
+infra/nomad-plugins/vm-templates/vm-templates
+
+# Cloudflare
+.wrangler/
+
+# Google service-account keys (never commit)
+scripts/.google-sheets-key.json
+*.google-sheets-key.json
+
+# Outreach recipient lists (PII: never commit)
+**/recipients*.txt
+*.recipients.txt
+# local GLM-5.2 provider API keys (never commit)
+.glm52.keys
+
+# Lead lists / customer data (never commit)
+gpu_customers_over_100.csv
+email_flags.csv
+customers_segmented.csv
+campaign_exclusions.csv
+attio_import.csv
+
+# Terraform (never commit state or real tfvars)
+**/.terraform/*
+*.tfstate
+*.tfstate.*
+*.tfvars
+!*.tfvars.example
+# Module test fixtures (fake values), loaded by terraform test.
+!infra/terraform/modules/*/tests/terraform.tfvars
+crash.log
+
+# Cloudflare Worker local dev secrets
+**/.dev.vars
+.nebius
+# Lambda Cloud API key (both spellings; never commit)
+.lambda
+.lamda
+
+# built Go binaries (never commit)
+/services/fabric/fabric-nodeagent
+/tools/brownout/brownout
+
+# patch/merge backups (never commit)
+*.orig
+*.rej
+
+# Generated by `next dev` (node_modules/next/dist/server/lib/generate-agent-files.js).
+apps/dashboard/AGENTS.md
+apps/dashboard/CLAUDE.md
+apps/toolbox/AGENTS.md
+apps/toolbox/CLAUDE.md
+apps/linkedin-outreach/AGENTS.md
+apps/linkedin-outreach/CLAUDE.md
+
+# Regenerated by `next typegen` (which every app's `typecheck` runs first), `next build` and `next dev`, with import paths that follow the dist dir of whichever ran last.
+apps/*/next-env.d.ts
+
+# Generated from services/control-plane-go/openapi.yaml by `pnpm --filter <app> openapi:gen`, which each app's typecheck, dev and build all run first.
+apps/toolbox/src/lib/api-types.gen.d.ts
+apps/dashboard/src/lib/api-types.gen.d.ts
+
+# Local Google OAuth client creds (never commit)
+.google.creds
+.eve
+.output
+
+# Lean build output (formal/)
+.lake/
+.abuse-harness/
+e2e/abuse/artifacts/

openrelay_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: openrelay-sdk
+Version: 0.1.0
+Summary: The official Python SDK for the OpenRelay API
+Project-URL: Homepage, https://openrelay.inc
+Project-URL: Documentation, https://docs.openrelay.inc
+Project-URL: Repository, https://github.com/OpenRelayInc/OpenRelay
+Project-URL: Issues, https://github.com/OpenRelayInc/OpenRelay/issues
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx<1,>=0.25.0
+Requires-Dist: pydantic<3,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenRelay Python SDK
+
+The official Python SDK for the [OpenRelay](https://openrelay.inc) API.
+
+## Installation
+
+```bash
+pip install openrelay-sdk
+```
+
+The package imports as `openrelay`. The unrelated `openrelay` distribution on
+PyPI also provides a top-level `openrelay` module, so install `openrelay-sdk`,
+and do not install both into the same environment.
+
+From a checkout of this repository: `pip install ./sdks/python`.
+
+## Quick Start
+
+```python
+import openrelay
+
+client = openrelay.Client(api_key="or_your_api_key")
+
+# List available GPUs
+gpus = client.gpus.list()
+
+# Create a VM
+vm = client.vms.create(
+    name="dev-box",
+    ssh_key_ids=["your-ssh-key-id"],
+    gpu_type="rtx-4090",
+    gpu_count=1,
+    disk_size_gb=100,
+)
+
+# Wait for it to be ready
+vm = client.vms.wait_for_status(vm.id)
+print(f"VM running at: {vm.endpoint_url}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+import openrelay
+
+async def main():
+    async with openrelay.AsyncClient(api_key="or_your_api_key") as client:
+        vm = await client.vms.get("your-vm-id")
+        print(vm.status)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+The client accepts these parameters:
+
+| Parameter | Env Variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `OPENRELAY_API_KEY` | Required |
+| `base_url` | `OPENRELAY_API_URL` | `https://api.openrelay.inc` |
+| `timeout` | (none) | `60.0` seconds |
+| `max_retries` | (none) | `2` |
+
+The `orl` CLI reads the same two variables.
+
+## License
+
+MIT

openrelay_sdk-0.1.0/README.md

@@ -0,0 +1,70 @@
+# OpenRelay Python SDK
+
+The official Python SDK for the [OpenRelay](https://openrelay.inc) API.
+
+## Installation
+
+```bash
+pip install openrelay-sdk
+```
+
+The package imports as `openrelay`. The unrelated `openrelay` distribution on
+PyPI also provides a top-level `openrelay` module, so install `openrelay-sdk`,
+and do not install both into the same environment.
+
+From a checkout of this repository: `pip install ./sdks/python`.
+
+## Quick Start
+
+```python
+import openrelay
+
+client = openrelay.Client(api_key="or_your_api_key")
+
+# List available GPUs
+gpus = client.gpus.list()
+
+# Create a VM
+vm = client.vms.create(
+    name="dev-box",
+    ssh_key_ids=["your-ssh-key-id"],
+    gpu_type="rtx-4090",
+    gpu_count=1,
+    disk_size_gb=100,
+)
+
+# Wait for it to be ready
+vm = client.vms.wait_for_status(vm.id)
+print(f"VM running at: {vm.endpoint_url}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+import openrelay
+
+async def main():
+    async with openrelay.AsyncClient(api_key="or_your_api_key") as client:
+        vm = await client.vms.get("your-vm-id")
+        print(vm.status)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+The client accepts these parameters:
+
+| Parameter | Env Variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `OPENRELAY_API_KEY` | Required |
+| `base_url` | `OPENRELAY_API_URL` | `https://api.openrelay.inc` |
+| `timeout` | (none) | `60.0` seconds |
+| `max_retries` | (none) | `2` |
+
+The `orl` CLI reads the same two variables.
+
+## License
+
+MIT

openrelay_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openrelay-sdk"
+dynamic = ["version"]
+description = "The official Python SDK for the OpenRelay API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+dependencies = [
+    "httpx>=0.25.0,<1",
+    "pydantic>=2.0.0,<3",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+# PyPI renders these as links on the package page, the page's route back to
+# the site.
+[project.urls]
+Homepage = "https://openrelay.inc"
+Documentation = "https://docs.openrelay.inc"
+Repository = "https://github.com/OpenRelayInc/OpenRelay"
+Issues = "https://github.com/OpenRelayInc/OpenRelay/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[tool.hatch.version]
+path = "src/openrelay/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openrelay"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+strict = true

openrelay_sdk-0.1.0/src/openrelay/__init__.py

@@ -0,0 +1,54 @@
+"""OpenRelay Python SDK."""
+
+from ._client import AsyncClient, Client
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    OpenRelayError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._version import __version__
+from .types.gpus import (
+    GpuAvailability,
+    GpuAvailabilityRegion,
+    GpuModel,
+    GpuModelAvailability,
+    GpuPricing,
+    GpuPricingTier,
+)
+from .types.vms import Vm, VmActionResponse, VmCreateResponse
+
+__all__ = [
+    "__version__",
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Exceptions
+    "OpenRelayError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+    # GPU types
+    "GpuModel",
+    "GpuModelAvailability",
+    "GpuAvailability",
+    "GpuAvailabilityRegion",
+    "GpuPricing",
+    "GpuPricingTier",
+    # VM types
+    "Vm",
+    "VmCreateResponse",
+    "VmActionResponse",
+]

openrelay_sdk-0.1.0/src/openrelay/_base_client.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+import random
+import re
+from typing import Any, Dict, List, Optional, Tuple, Type, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from ._constants import (
+    API_KEY_ENV_VAR,
+    CAPACITY_CODES,
+    BASE_URL_ENV_VAR,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    INITIAL_RETRY_DELAY,
+    MAX_RETRY_DELAY,
+)
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    OpenRelayError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._version import __version__
+
+T = TypeVar("T", bound=BaseModel)
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+_ERROR_TYPE_MAP: Dict[str, Type[APIError]] = {
+    "authentication_error": AuthenticationError,
+    "permission_error": PermissionDeniedError,
+    "not_found_error": NotFoundError,
+    "invalid_request_error": InvalidRequestError,
+    "rate_limit_error": RateLimitError,
+    "server_error": InternalServerError,
+}
+
+
+def _is_uuid(value: str) -> bool:
+    return bool(_UUID_RE.match(value))
+
+
+# The error type a flat control-plane body implies, which carries no type field.
+_STATUS_ERROR_TYPE: Dict[int, str] = {
+    400: "invalid_request_error",
+    401: "authentication_error",
+    403: "permission_error",
+    404: "not_found_error",
+    429: "rate_limit_error",
+}
+
+
+def _parse_error(response: httpx.Response) -> Tuple[str, str, Optional[str]]:
+    """(type, message, code) from an error response. The control plane writes a
+    flat {"error": "<message>", "code": "<CODE>"}, which carries no type, so the
+    type follows from the status. The nested {"error": {"type", "message",
+    "code"}} shape is read as it comes. A body that is neither yields a
+    server_error with a status-only message and no code."""
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+    if isinstance(body, dict):
+        error = body.get("error", {})
+        if isinstance(error, str):
+            status = response.status_code
+            code = body.get("code")
+            return (
+                "server_error" if status >= 500 else _STATUS_ERROR_TYPE.get(status, "api_error"),
+                error,
+                code if isinstance(code, str) else None,
+            )
+        if isinstance(error, dict):
+            code = error.get("code")
+            return (
+                error.get("type", "server_error"),
+                error.get("message", "Unknown error"),
+                code if isinstance(code, str) else None,
+            )
+    return "server_error", f"HTTP {response.status_code}", None
+
+
+class BaseClient:
+    """Shared configuration for sync and async clients."""
+
+    _gpu_name_cache: Optional[Dict[str, str]]
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get(API_KEY_ENV_VAR)
+        if not self.api_key:
+            raise OpenRelayError(
+                f"API key is required. Pass api_key= or set {API_KEY_ENV_VAR}."
+            )
+        self.base_url = (
+            base_url or os.environ.get(BASE_URL_ENV_VAR) or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+        self.max_retries = (
+            max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        )
+        self._gpu_name_cache = None
+
+    def _build_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"openrelay-python/{__version__}",
+        }
+
+    def _build_url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        if response.status_code == 503 and _parse_error(response)[2] in CAPACITY_CODES:
+            return False
+        return response.status_code in (429, 500, 502, 503, 504)
+
+    def _retry_delay(
+        self, attempt: int, response_headers: Optional[Dict[str, str]] = None
+    ) -> float:
+        if response_headers:
+            retry_after = response_headers.get("retry-after")
+            if retry_after:
+                try:
+                    return float(retry_after)
+                except (ValueError, TypeError):
+                    pass
+        delay = min(INITIAL_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY)
+        jitter = random.random() * 0.5 * delay
+        return delay + jitter
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        error_type, message, code = _parse_error(response)
+        exc_class = _ERROR_TYPE_MAP.get(error_type, APIError)
+        raise exc_class(
+            message,
+            status_code=response.status_code,
+            type=error_type,
+            code=code,
+            headers=dict(response.headers),
+        )
+
+    def _parse_response(self, response: httpx.Response, model: Type[T]) -> T:
+        body = response.json()
+        data = body.get("data", body)
+        return model.model_validate(data)
+
+    def _parse_response_list(
+        self, response: httpx.Response, model: Type[T]
+    ) -> List[T]:
+        body = response.json()
+        data = body.get("data", [])
+        return [model.model_validate(item) for item in data]