maritime 0.2.0__tar.gz

maritime-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+*.pyc

maritime-0.2.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: maritime
+Version: 0.2.0
+Summary: Official Python SDK for Maritime — provision and drive AI agents on Maritime's serverless infrastructure from your own backend.
+Project-URL: Homepage, https://maritime.sh
+Project-URL: Documentation, https://maritime.sh/docs/build
+Project-URL: Repository, https://github.com/mariagorskikh/maritime-sdk
+Author: Maritime
+License-Expression: MIT
+Keywords: agents,ai,maritime,openclaw,sdk,serverless
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# maritime (Python SDK)
+
+Official Python SDK for [Maritime](https://maritime.sh) — provision and drive AI agents on Maritime's serverless infrastructure, straight from your own backend.
+
+Build an app where every one of **your** users gets **their own** agent: one call on sign-up spins up an isolated agent on Maritime's fleet; another sends it a message. You never touch a container.
+
+```bash
+pip install maritime
+```
+
+Python 3.9+. Zero dependencies (pure standard library).
+
+## Quick start
+
+```python
+from maritime import Maritime
+
+client = Maritime()  # reads MARITIME_API_KEY
+
+# When YOUR user signs up, give them their own agent. provision() is idempotent
+# on external_id — safe to call on every login.
+agent = client.agents.provision(
+    external_id=f"customer_{user.id}",   # your id for this agent
+    name=f"assistant-{user.id}",
+    template="openclaw",
+)
+
+# Talk to it (sleeping agents auto-wake):
+reply = client.agents.chat(agent["id"], "Summarize my unread email.")["response"]
+print(reply)
+```
+
+## Authentication
+
+Mint an API key (`mk_...`) from the dashboard (**Settings → API keys**) or the CLI (`maritime keys create`), then set `MARITIME_API_KEY`, or pass it explicitly:
+
+```python
+client = Maritime(api_key="mk_...")
+```
+
+Keys carry **scopes** — hand a narrower key to a subsystem that only needs part of the surface:
+
+| Scope | Grants |
+|-------|--------|
+| `provision` | create agents |
+| `deploy` | start/stop/restart/sleep/chat |
+| `secrets` | read/write env vars |
+| `manage` | everything, incl. delete + key management (wildcard) |
+
+```python
+worker = client.keys.create("chat-worker", scopes=["deploy"])
+# worker["raw_key"] is shown once — store it now.
+```
+
+## Agents
+
+```python
+# Create (kicks off deploy). Prefer template — a bare framework yields a broken image.
+agent = client.agents.create(
+    "support-bot",
+    template="openclaw",
+    external_id="customer_42",
+    instructions="You are a friendly support agent for Acme Inc.",
+    env=[{"key": "ACME_API_KEY", "value": "...", "secret": True}],
+    tier="smart",            # "smart" | "extended" | "always_on"
+    idle_ttl_seconds=3600,   # 0 = always-on
+)
+
+# Idempotent get-or-create by external_id (recommended for per-user provisioning)
+agent = client.agents.provision(external_id="customer_42", name="support-bot")
+
+client.agents.get(agent["id"])
+client.agents.list(external_id="customer_42")   # filter by your id
+client.agents.list()                             # all of your agents
+
+# Chat (synchronous; auto-wakes a sleeping agent)
+result = client.agents.chat(agent["id"], "Hello")
+print(result["response"])   # None + result["error"] if delivery failed
+
+# Lifecycle
+client.agents.start(agent["id"])
+client.agents.sleep(agent["id"])     # cheapest resting state (serverless snapshot)
+client.agents.restart(agent["id"])
+client.agents.delete(agent["id"])    # tears down container + volume + network
+
+# Env vars (secrets encrypted at rest; reach a running container after reload_env)
+client.agents.set_env(agent["id"], "STRIPE_KEY", "sk_live_...", secret=True)
+client.agents.list_env(agent["id"])
+client.agents.reload_env(agent["id"])
+
+# Logs
+client.agents.logs(agent["id"], limit=100, level="error")
+```
+
+## Errors
+
+Every failure is a subclass of `MaritimeError` — catch the base to catch them all, or narrow by type:
+
+```python
+from maritime import (
+    MaritimeAuthError,            # 401 / 403 — bad or under-scoped key
+    MaritimePaymentRequiredError, # 402 — wallet needs funding
+    MaritimeNotFoundError,        # 404 — no such agent (or not yours)
+    MaritimeConflictError,        # 409 — name already taken
+    MaritimeRateLimitError,       # 429
+    MaritimeAPIError,             # any other non-2xx (has .status, .detail)
+    MaritimeConnectionError,      # never reached Maritime (network/timeout)
+)
+
+try:
+    client.agents.create("dupe", template="openclaw")
+except MaritimeConflictError:
+    ...  # an agent with that name already exists
+except MaritimeAPIError as err:
+    print(err.status, err.detail, err.request_id)
+```
+
+## Configuration
+
+```python
+Maritime(
+    api_key="mk_...",                    # or MARITIME_API_KEY
+    base_url="https://api.maritime.sh",  # or MARITIME_API_URL
+    timeout=60.0,                        # per-request seconds
+    max_retries=2,                       # network + 5xx/429 (GET/DELETE and 429/503 only)
+    default_headers={"x-team": "acme"},
+)
+```
+
+Retries are safe by construction: `GET`/`DELETE` retry on any transient failure; `POST`/`PUT` retry only on network errors and `429`/`503` (never a `5xx` that might have applied a write).
+
+## License
+
+MIT

maritime-0.2.0/README.md

@@ -0,0 +1,134 @@
+# maritime (Python SDK)
+
+Official Python SDK for [Maritime](https://maritime.sh) — provision and drive AI agents on Maritime's serverless infrastructure, straight from your own backend.
+
+Build an app where every one of **your** users gets **their own** agent: one call on sign-up spins up an isolated agent on Maritime's fleet; another sends it a message. You never touch a container.
+
+```bash
+pip install maritime
+```
+
+Python 3.9+. Zero dependencies (pure standard library).
+
+## Quick start
+
+```python
+from maritime import Maritime
+
+client = Maritime()  # reads MARITIME_API_KEY
+
+# When YOUR user signs up, give them their own agent. provision() is idempotent
+# on external_id — safe to call on every login.
+agent = client.agents.provision(
+    external_id=f"customer_{user.id}",   # your id for this agent
+    name=f"assistant-{user.id}",
+    template="openclaw",
+)
+
+# Talk to it (sleeping agents auto-wake):
+reply = client.agents.chat(agent["id"], "Summarize my unread email.")["response"]
+print(reply)
+```
+
+## Authentication
+
+Mint an API key (`mk_...`) from the dashboard (**Settings → API keys**) or the CLI (`maritime keys create`), then set `MARITIME_API_KEY`, or pass it explicitly:
+
+```python
+client = Maritime(api_key="mk_...")
+```
+
+Keys carry **scopes** — hand a narrower key to a subsystem that only needs part of the surface:
+
+| Scope | Grants |
+|-------|--------|
+| `provision` | create agents |
+| `deploy` | start/stop/restart/sleep/chat |
+| `secrets` | read/write env vars |
+| `manage` | everything, incl. delete + key management (wildcard) |
+
+```python
+worker = client.keys.create("chat-worker", scopes=["deploy"])
+# worker["raw_key"] is shown once — store it now.
+```
+
+## Agents
+
+```python
+# Create (kicks off deploy). Prefer template — a bare framework yields a broken image.
+agent = client.agents.create(
+    "support-bot",
+    template="openclaw",
+    external_id="customer_42",
+    instructions="You are a friendly support agent for Acme Inc.",
+    env=[{"key": "ACME_API_KEY", "value": "...", "secret": True}],
+    tier="smart",            # "smart" | "extended" | "always_on"
+    idle_ttl_seconds=3600,   # 0 = always-on
+)
+
+# Idempotent get-or-create by external_id (recommended for per-user provisioning)
+agent = client.agents.provision(external_id="customer_42", name="support-bot")
+
+client.agents.get(agent["id"])
+client.agents.list(external_id="customer_42")   # filter by your id
+client.agents.list()                             # all of your agents
+
+# Chat (synchronous; auto-wakes a sleeping agent)
+result = client.agents.chat(agent["id"], "Hello")
+print(result["response"])   # None + result["error"] if delivery failed
+
+# Lifecycle
+client.agents.start(agent["id"])
+client.agents.sleep(agent["id"])     # cheapest resting state (serverless snapshot)
+client.agents.restart(agent["id"])
+client.agents.delete(agent["id"])    # tears down container + volume + network
+
+# Env vars (secrets encrypted at rest; reach a running container after reload_env)
+client.agents.set_env(agent["id"], "STRIPE_KEY", "sk_live_...", secret=True)
+client.agents.list_env(agent["id"])
+client.agents.reload_env(agent["id"])
+
+# Logs
+client.agents.logs(agent["id"], limit=100, level="error")
+```
+
+## Errors
+
+Every failure is a subclass of `MaritimeError` — catch the base to catch them all, or narrow by type:
+
+```python
+from maritime import (
+    MaritimeAuthError,            # 401 / 403 — bad or under-scoped key
+    MaritimePaymentRequiredError, # 402 — wallet needs funding
+    MaritimeNotFoundError,        # 404 — no such agent (or not yours)
+    MaritimeConflictError,        # 409 — name already taken
+    MaritimeRateLimitError,       # 429
+    MaritimeAPIError,             # any other non-2xx (has .status, .detail)
+    MaritimeConnectionError,      # never reached Maritime (network/timeout)
+)
+
+try:
+    client.agents.create("dupe", template="openclaw")
+except MaritimeConflictError:
+    ...  # an agent with that name already exists
+except MaritimeAPIError as err:
+    print(err.status, err.detail, err.request_id)
+```
+
+## Configuration
+
+```python
+Maritime(
+    api_key="mk_...",                    # or MARITIME_API_KEY
+    base_url="https://api.maritime.sh",  # or MARITIME_API_URL
+    timeout=60.0,                        # per-request seconds
+    max_retries=2,                       # network + 5xx/429 (GET/DELETE and 429/503 only)
+    default_headers={"x-team": "acme"},
+)
+```
+
+Retries are safe by construction: `GET`/`DELETE` retry on any transient failure; `POST`/`PUT` retry only on network errors and `429`/`503` (never a `5xx` that might have applied a write).
+
+## License
+
+MIT

maritime-0.2.0/maritime/__init__.py

@@ -0,0 +1,81 @@
+"""Official Python SDK for Maritime.
+
+Provision and drive AI agents on Maritime's serverless infrastructure from your
+own backend.
+
+    from maritime import Maritime
+
+    client = Maritime()  # reads MARITIME_API_KEY
+
+    # When YOUR user signs up, give them their own agent (idempotent):
+    agent = client.agents.provision(
+        external_id=f"customer_{user_id}",
+        name=f"assistant-{user_id}",
+        template="openclaw",
+    )
+    reply = client.agents.chat(agent["id"], "Hello!")["response"]
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._http import HttpClient
+from .errors import (
+    MaritimeAPIError,
+    MaritimeAuthError,
+    MaritimeConflictError,
+    MaritimeConnectionError,
+    MaritimeError,
+    MaritimeNotFoundError,
+    MaritimePaymentRequiredError,
+    MaritimeRateLimitError,
+)
+from .resources import Agents, Keys, Webhooks
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Maritime",
+    "MaritimeError",
+    "MaritimeConnectionError",
+    "MaritimeAPIError",
+    "MaritimeAuthError",
+    "MaritimePaymentRequiredError",
+    "MaritimeNotFoundError",
+    "MaritimeConflictError",
+    "MaritimeRateLimitError",
+]
+
+
+class Maritime:
+    """The Maritime client.
+
+    :param api_key: ``mk_...`` key. Defaults to the ``MARITIME_API_KEY`` env var.
+    :param base_url: API base. Defaults to ``MARITIME_API_URL`` or api.maritime.sh.
+    :param timeout: per-request timeout (seconds).
+    :param max_retries: retries on network errors and 5xx/429.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self.agents = Agents(self.http)
+        self.keys = Keys(self.http)
+        self.webhooks = Webhooks(self.http)
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Escape hatch for endpoints not yet wrapped."""
+        return self.http.request(method, path, **kwargs)

maritime-0.2.0/maritime/_http.py

@@ -0,0 +1,136 @@
+"""Zero-dependency HTTP transport (stdlib urllib) with typed errors + retry."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+from .errors import MaritimeConnectionError, MaritimeError, api_error_from_status
+
+DEFAULT_BASE_URL = "https://api.maritime.sh"
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class HttpClient:
+    """Thin transport: auth header, JSON encode/decode, typed errors, bounded
+    retry with backoff. No third-party dependencies."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        key = api_key or os.environ.get("MARITIME_API_KEY")
+        if not key:
+            raise MaritimeError(
+                "Missing Maritime API key. Pass api_key=... or set MARITIME_API_KEY."
+            )
+        self._api_key = key
+        self._base_url = (base_url or os.environ.get("MARITIME_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._default_headers = default_headers or {}
+
+    def _url(self, path: str, query: Optional[Dict[str, Any]]) -> str:
+        url = self._base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        return url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        idempotent: Optional[bool] = None,
+    ) -> Any:
+        url = self._url(path, query)
+        data = None
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": "maritime-python-sdk",
+        }
+        headers.update(self._default_headers)
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        method = method.upper()
+        retry_safe = idempotent if idempotent is not None else method in ("GET", "DELETE")
+
+        last_err: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    return self._parse(resp.read(), resp.status)
+            except urllib.error.HTTPError as e:
+                status = e.code
+                detail = self._detail(e)
+                request_id = e.headers.get("x-request-id") if e.headers else None
+                retryable = (
+                    attempt < self._max_retries
+                    and status in _RETRYABLE_STATUS
+                    and (retry_safe or status in (429, 503))
+                )
+                if retryable:
+                    last_err = api_error_from_status(status, detail, request_id)
+                    time.sleep(self._backoff(attempt, e))
+                    continue
+                raise api_error_from_status(status, detail, request_id)
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                last_err = e
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                reason = getattr(e, "reason", e)
+                raise MaritimeConnectionError(
+                    f"Failed to reach Maritime at {self._base_url}: {reason}"
+                ) from e
+
+        if isinstance(last_err, MaritimeError):
+            raise last_err
+        raise MaritimeConnectionError(f"Request to {url} failed after retries")
+
+    @staticmethod
+    def _backoff(attempt: int, err: Optional[urllib.error.HTTPError] = None) -> float:
+        if err is not None and err.headers:
+            retry_after = err.headers.get("retry-after")
+            if retry_after:
+                try:
+                    return min(float(retry_after), 20.0)
+                except ValueError:
+                    pass
+        return min(0.5 * (2 ** attempt), 8.0)
+
+    @staticmethod
+    def _parse(raw: bytes, status: int) -> Any:
+        if status == 204 or not raw:
+            return None
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return raw.decode("utf-8", "replace")
+
+    @staticmethod
+    def _detail(err: urllib.error.HTTPError) -> str:
+        try:
+            payload = json.loads(err.read().decode("utf-8"))
+            if isinstance(payload, dict) and "detail" in payload:
+                d = payload["detail"]
+                return d if isinstance(d, str) else json.dumps(d)
+        except Exception:  # noqa: BLE001
+            pass
+        return f"Request failed with status {err.code}"

maritime-0.2.0/maritime/errors.py

@@ -0,0 +1,61 @@
+"""Exception hierarchy for the Maritime SDK.
+
+Catch :class:`MaritimeError` to catch them all, or narrow by subclass.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class MaritimeError(Exception):
+    """Base class for every error the SDK raises."""
+
+
+class MaritimeConnectionError(MaritimeError):
+    """The request never reached Maritime (DNS, connection, timeout)."""
+
+
+class MaritimeAPIError(MaritimeError):
+    """Maritime returned a non-2xx response."""
+
+    def __init__(self, status: int, detail: str, request_id: Optional[str] = None) -> None:
+        super().__init__(f"Maritime API error {status}: {detail}")
+        self.status = status
+        self.detail = detail
+        self.request_id = request_id
+
+
+class MaritimeAuthError(MaritimeAPIError):
+    """401 / 403 — bad or insufficiently-scoped API key."""
+
+
+class MaritimePaymentRequiredError(MaritimeAPIError):
+    """402 — the account wallet needs funding before this action can proceed."""
+
+
+class MaritimeNotFoundError(MaritimeAPIError):
+    """404 — the agent (or other resource) does not exist or is not yours."""
+
+
+class MaritimeConflictError(MaritimeAPIError):
+    """409 — a uniqueness conflict (e.g. an agent name already exists)."""
+
+
+class MaritimeRateLimitError(MaritimeAPIError):
+    """429 — rate limited."""
+
+
+def api_error_from_status(status: int, detail: str, request_id: Optional[str] = None) -> MaritimeAPIError:
+    """Build the most specific error subclass for an HTTP status."""
+    if status in (401, 403):
+        return MaritimeAuthError(status, detail, request_id)
+    if status == 402:
+        return MaritimePaymentRequiredError(status, detail, request_id)
+    if status == 404:
+        return MaritimeNotFoundError(status, detail, request_id)
+    if status == 409:
+        return MaritimeConflictError(status, detail, request_id)
+    if status == 429:
+        return MaritimeRateLimitError(status, detail, request_id)
+    return MaritimeAPIError(status, detail, request_id)

maritime-0.2.0/maritime/resources.py

@@ -0,0 +1,192 @@
+"""Resource namespaces: ``client.agents`` and ``client.keys``."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._http import HttpClient
+
+
+class Agents:
+    """Operations on Maritime agents. Access via ``client.agents``."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        name: str,
+        *,
+        template: Optional[str] = None,
+        external_id: Optional[str] = None,
+        description: Optional[str] = None,
+        instructions: Optional[str] = None,
+        tier: Optional[str] = None,
+        env: Optional[List[Dict[str, Any]]] = None,
+        mem_mb: Optional[int] = None,
+        vcpus: Optional[float] = None,
+        idle_ttl_seconds: Optional[int] = None,
+        disk_gb: Optional[float] = None,
+        github_repo: Optional[str] = None,
+        image_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create an agent and kick off its deploy.
+
+        ``env`` items look like ``{"key": ..., "value": ..., "secret": True}``.
+        """
+        body: Dict[str, Any] = {
+            "name": name,
+            "templateId": template,
+            "externalId": external_id,
+            "description": description,
+            "instructions": instructions,
+            "tier": tier,
+            "memMb": mem_mb,
+            "vcpus": vcpus,
+            "idleTtlSeconds": idle_ttl_seconds,
+            "diskGb": disk_gb,
+            "githubRepo": github_repo,
+            "imageName": image_name,
+        }
+        if env:
+            body["initialEnvVars"] = [
+                {"key": e["key"], "value": e["value"], "isSecret": e.get("secret", True)}
+                for e in env
+            ]
+        body = {k: v for k, v in body.items() if v is not None}
+        return self._http.request("POST", "/api/agents", body=body)
+
+    def provision(self, external_id: str, name: str, *, template: str = "openclaw", **kwargs: Any) -> Dict[str, Any]:
+        """Get-or-create an agent by ``external_id`` (idempotent — safe to call
+        on every sign-in). Returns the existing agent if one exists."""
+        existing = self.list(external_id=external_id)
+        if existing:
+            return existing[0]
+        try:
+            return self.create(name, template=template, external_id=external_id, **kwargs)
+        except Exception:
+            # Lost a race with a concurrent provisioner — re-read.
+            raced = self.list(external_id=external_id)
+            if raced:
+                return raced[0]
+            raise
+
+    def get(self, agent_id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/api/agents/{_enc(agent_id)}")
+
+    def list(self, *, external_id: Optional[str] = None, name: Optional[str] = None) -> List[Dict[str, Any]]:
+        return self._http.request(
+            "GET", "/api/agents", query={"externalId": external_id, "name": name}
+        ) or []
+
+    def chat(self, agent_id: str, message: str, *, conversation_id: Optional[str] = None) -> Dict[str, Any]:
+        """Send a message and wait for the reply. Sleeping agents auto-wake.
+        Returns ``{"response": str | None, "error"?: str}``."""
+        return self._http.request(
+            "POST",
+            f"/api/agents/{_enc(agent_id)}/chat",
+            body={"message": message, "conversation_id": conversation_id},
+        )
+
+    def start(self, agent_id: str) -> Dict[str, Any]:
+        return self._lifecycle(agent_id, "start")
+
+    def stop(self, agent_id: str) -> Dict[str, Any]:
+        return self._lifecycle(agent_id, "stop")
+
+    def sleep(self, agent_id: str) -> Dict[str, Any]:
+        return self._lifecycle(agent_id, "sleep")
+
+    def restart(self, agent_id: str) -> Dict[str, Any]:
+        return self._lifecycle(agent_id, "restart")
+
+    def delete(self, agent_id: str) -> None:
+        self._http.request("DELETE", f"/api/agents/{_enc(agent_id)}")
+
+    def list_env(self, agent_id: str) -> List[Dict[str, Any]]:
+        return self._http.request("GET", f"/api/agents/{_enc(agent_id)}/env") or []
+
+    def set_env(self, agent_id: str, key: str, value: str, *, secret: bool = True) -> Dict[str, Any]:
+        """Set (upsert) an env var. Secrets are encrypted at rest; changes reach
+        a running container after :meth:`reload_env` or a restart."""
+        return self._http.request(
+            "POST",
+            f"/api/agents/{_enc(agent_id)}/env",
+            body={"key": key, "value": value, "isSecret": secret},
+        )
+
+    def delete_env(self, agent_id: str, key: str) -> None:
+        self._http.request("DELETE", f"/api/agents/{_enc(agent_id)}/env/{_enc(key)}")
+
+    def reload_env(self, agent_id: str) -> Dict[str, Any]:
+        return self._lifecycle(agent_id, "reload-env")
+
+    def logs(self, agent_id: str, *, limit: Optional[int] = None, level: Optional[str] = None) -> List[Dict[str, Any]]:
+        return self._http.request(
+            "GET", f"/api/agents/{_enc(agent_id)}/logs", query={"limit": limit, "level": level}
+        ) or []
+
+    def _lifecycle(self, agent_id: str, action: str) -> Dict[str, Any]:
+        return self._http.request(
+            "POST", f"/api/agents/{_enc(agent_id)}/{action}", idempotent=True
+        )
+
+
+class Keys:
+    """Manage API keys programmatically. Access via ``client.keys``."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, name: str, *, scopes: Optional[List[str]] = None, expires_in_days: Optional[int] = None) -> Dict[str, Any]:
+        """Mint a new key. The raw key is in ``["raw_key"]`` — shown once."""
+        return self._http.request(
+            "POST",
+            "/api/v1/keys",
+            body={
+                "name": name,
+                "scopes": scopes or ["provision", "deploy", "secrets", "manage"],
+                "expires_in_days": expires_in_days,
+            },
+        )
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._http.request("GET", "/api/v1/keys") or []
+
+    def revoke(self, key_id: str) -> None:
+        self._http.request("DELETE", f"/api/v1/keys/{_enc(key_id)}")
+
+
+class Webhooks:
+    """Manage outbound webhook subscriptions. Access via ``client.webhooks``.
+
+    Subscribe a URL to receive signed agent lifecycle events (agent.deployed,
+    agent.error, agent.sleeping, agent.woken, agent.restarted, agent.stopped)
+    instead of polling. Each delivery carries ``X-Maritime-Signature:
+    sha256=<hmac>`` — verify it with the subscription's secret.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, url: str, *, events: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Create a subscription. The signing ``secret`` is in the result — once."""
+        return self._http.request(
+            "POST", "/api/v1/webhooks", body={"url": url, "events": events or []}
+        )
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._http.request("GET", "/api/v1/webhooks") or []
+
+    def delete(self, subscription_id: str) -> None:
+        self._http.request("DELETE", f"/api/v1/webhooks/{_enc(subscription_id)}")
+
+    def test(self, subscription_id: str) -> Dict[str, Any]:
+        """Deliver a synthetic ``ping`` and return the result."""
+        return self._http.request("POST", f"/api/v1/webhooks/{_enc(subscription_id)}/test")
+
+
+def _enc(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(str(value), safe="")

maritime-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "maritime"
+version = "0.2.0"
+description = "Official Python SDK for Maritime — provision and drive AI agents on Maritime's serverless infrastructure from your own backend."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Maritime" }]
+keywords = ["maritime", "ai", "agents", "sdk", "openclaw", "serverless"]
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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 :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://maritime.sh"
+Documentation = "https://maritime.sh/docs/build"
+Repository = "https://github.com/mariagorskikh/maritime-sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["maritime"]

maritime-0.2.0/tests/test_client.py

@@ -0,0 +1,187 @@
+import io
+import json
+import urllib.error
+from typing import Any, Dict, List, Optional
+
+import pytest
+
+from maritime import (
+    Maritime,
+    MaritimeAuthError,
+    MaritimeConflictError,
+    MaritimeError,
+    MaritimeNotFoundError,
+    MaritimePaymentRequiredError,
+)
+
+
+class _Resp:
+    """Minimal stand-in for the object returned by urlopen()."""
+
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self._body = b"" if body is None else json.dumps(body).encode()
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+class MockTransport:
+    """Patches urllib.request.urlopen to return queued responses + record calls."""
+
+    def __init__(self, responses: List[Dict[str, Any]]):
+        self.responses = responses
+        self.calls: List[Dict[str, Any]] = []
+        self._i = 0
+
+    def __call__(self, req, timeout=None):
+        self.calls.append({
+            "url": req.full_url,
+            "method": req.get_method(),
+            "body": json.loads(req.data) if req.data else None,
+            "headers": {k.lower(): v for k, v in req.headers.items()},
+        })
+        r = self.responses[min(self._i, len(self.responses) - 1)]
+        self._i += 1
+        status = r["status"]
+        if status >= 400:
+            raise urllib.error.HTTPError(
+                req.full_url, status, r.get("detail", "err"),
+                {"content-type": "application/json"},
+                io.BytesIO(json.dumps({"detail": r.get("detail", "err")}).encode()),
+            )
+        return _Resp(status, r.get("body"))
+
+
+@pytest.fixture
+def make_client(monkeypatch):
+    def _make(responses, **kw):
+        transport = MockTransport(responses)
+        monkeypatch.setattr("urllib.request.urlopen", transport)
+        client = Maritime(api_key="mk_test", base_url="https://api.example.test", max_retries=kw.get("max_retries", 2))
+        return client, transport
+    return _make
+
+
+def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv("MARITIME_API_KEY", raising=False)
+    with pytest.raises(MaritimeError):
+        Maritime()
+
+
+def test_bearer_and_json(make_client):
+    client, t = make_client([{"status": 200, "body": [{"id": "a1"}]}])
+    agents = client.agents.list()
+    assert agents == [{"id": "a1"}]
+    assert t.calls[0]["headers"]["authorization"] == "Bearer mk_test"
+    assert t.calls[0]["url"] == "https://api.example.test/api/agents"
+
+
+def test_create_body_camelcase(make_client):
+    client, t = make_client([{"status": 201, "body": {"id": "a1"}}])
+    client.agents.create("x", template="openclaw", external_id="c1", env=[{"key": "F", "value": "b"}])
+    body = t.calls[0]["body"]
+    assert body["templateId"] == "openclaw"
+    assert body["externalId"] == "c1"
+    assert body["initialEnvVars"] == [{"key": "F", "value": "b", "isSecret": True}]
+
+
+def test_chat_conversation_id(make_client):
+    client, t = make_client([{"status": 200, "body": {"response": "hi"}}])
+    r = client.agents.chat("a1", "hello", conversation_id="c1")
+    assert r["response"] == "hi"
+    assert t.calls[0]["body"] == {"message": "hello", "conversation_id": "c1"}
+
+
+def test_list_external_id_query(make_client):
+    client, t = make_client([{"status": 200, "body": []}])
+    client.agents.list(external_id="cust_9")
+    assert "externalId=cust_9" in t.calls[0]["url"]
+
+
+def test_delete_204(make_client):
+    client, t = make_client([{"status": 204}])
+    assert client.agents.delete("a1") is None
+
+
+@pytest.mark.parametrize("status,klass", [
+    (401, MaritimeAuthError),
+    (403, MaritimeAuthError),
+    (402, MaritimePaymentRequiredError),
+    (404, MaritimeNotFoundError),
+    (409, MaritimeConflictError),
+])
+def test_typed_errors(make_client, status, klass):
+    client, _ = make_client([{"status": status, "detail": "boom"}])
+    with pytest.raises(klass):
+        client.agents.get("a1")
+
+
+def test_error_exposes_status_detail(make_client):
+    client, _ = make_client([{"status": 404, "detail": "no such agent"}])
+    with pytest.raises(MaritimeNotFoundError) as exc:
+        client.agents.get("a1")
+    assert exc.value.status == 404
+    assert exc.value.detail == "no such agent"
+
+
+def test_retry_503_then_ok(make_client):
+    client, t = make_client([{"status": 503, "detail": "down"}, {"status": 200, "body": [{"id": "ok"}]}])
+    assert client.agents.list() == [{"id": "ok"}]
+    assert len(t.calls) == 2
+
+
+def test_no_retry_post_500(make_client):
+    client, t = make_client([{"status": 500, "detail": "err"}, {"status": 201, "body": {"id": "nope"}}], max_retries=3)
+    with pytest.raises(MaritimeError) as exc:
+        client.agents.create("x", template="openclaw")
+    assert exc.value.status == 500
+    assert len(t.calls) == 1
+
+
+def test_webhooks_create_list_delete_test(make_client):
+    client, t = make_client([
+        {"status": 201, "body": {"id": "wh1", "url": "https://x.test/h", "events": ["agent.error"], "secret": "whsec_x"}},
+        {"status": 200, "body": []},
+        {"status": 204},
+        {"status": 200, "body": {"delivered": True, "status_code": 200}},
+    ])
+    created = client.webhooks.create("https://x.test/h", events=["agent.error"])
+    assert created["secret"] == "whsec_x"
+    assert t.calls[0]["url"].endswith("/api/v1/webhooks")
+    assert t.calls[0]["body"] == {"url": "https://x.test/h", "events": ["agent.error"]}
+
+    client.webhooks.list()
+    assert t.calls[1]["method"] == "GET"
+
+    client.webhooks.delete("wh1")
+    assert t.calls[2]["method"] == "DELETE"
+    assert t.calls[2]["url"].endswith("/api/v1/webhooks/wh1")
+
+    r = client.webhooks.test("wh1")
+    assert r["delivered"] is True
+    assert t.calls[3]["url"].endswith("/api/v1/webhooks/wh1/test")
+
+
+def test_provision_returns_existing(make_client):
+    client, t = make_client([{"status": 200, "body": [{"id": "existing", "externalId": "c1"}]}])
+    a = client.agents.provision(external_id="c1", name="x")
+    assert a["id"] == "existing"
+    assert len(t.calls) == 1  # only the list, no create
+
+
+def test_provision_creates_when_absent(make_client):
+    client, t = make_client([
+        {"status": 200, "body": []},
+        {"status": 201, "body": {"id": "new", "externalId": "c2"}},
+    ])
+    a = client.agents.provision(external_id="c2", name="x")
+    assert a["id"] == "new"
+    assert len(t.calls) == 2
+    assert t.calls[1]["body"]["templateId"] == "openclaw"