superstep 0.1.0__tar.gz

superstep-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# deps / envs
+node_modules/
+.venv/
+venv/
+# build & caches
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.tsbuildinfo
+.vite/
+# data
+*.db
+*.db-wal
+*.db-shm
+*.migrate.lock
+backend/imports/
+.imports/
+# env/secrets
+.env
+.env.*
+!.env.example
+# misc
+.DS_Store
+*.log
+*.egg-info/
+frontend/test-results/
+frontend/playwright-report/
+backend/.venv
+.coverage

superstep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thái Quí Nguyễn
+
+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.

superstep-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: superstep
+Version: 0.1.0
+Summary: Python client for the Superstep public API: start workflow runs and read their results.
+Project-URL: Homepage, https://github.com/quinguyen1502/superstep
+Project-URL: Documentation, https://quinguyen1502.github.io/superstep/run/public-api/
+Author: Qui Nguyen
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# superstep (Python SDK)
+
+Python client for the Superstep public API: start a workflow run from your own
+service, poll it, and read its final state. Sync and async clients, typed
+models and typed errors; the only dependency is `httpx`.
+
+- Guide: <https://quinguyen1502.github.io/superstep/run/public-api/>
+- API reference: <https://quinguyen1502.github.io/superstep/reference/public-api/>
+- Spec: [`docs/api/openapi.public.json`](../../docs/api/openapi.public.json)
+
+## Install
+
+```bash
+pip install superstep
+# from the repository, before the first release:
+pip install ./sdk/python
+```
+
+Python 3.9 or later.
+
+## Configure
+
+A workflow token (`wft_...`) starts runs of one workflow. The workflow owner
+creates it in the editor under **More (⋯) → API → Create token**; it is shown
+once.
+
+```python
+from superstep import Client
+
+client = Client(
+    workflow_id="example",
+    token="wft_...",
+    base_url="https://superstep.example.com",
+)
+```
+
+Arguments left out are read from `SUPERSTEP_WORKFLOW_ID`, `SUPERSTEP_TOKEN`
+and `SUPERSTEP_BASE_URL`. A missing value raises `ConfigError`.
+
+## Run a workflow
+
+```python
+# Start and wait: polls with a growing interval (1 s, 1.5 s, ... up to 10 s).
+run = client.run_and_wait({"message": "where is my order A100"}, timeout=120)
+print(run.status, run.final_state)
+
+# Or step by step.
+started = client.run({"message": "hi"})       # status "queued", poll_url set
+current = client.get_run(started.run_id)      # status, final_state, metrics ...
+done = client.wait(started.run_id, timeout=60, poll_interval=0.5)
+
+# Let the server wait (up to STUDIO_SYNC_WAIT_MAX seconds, default 30).
+run = client.run({"message": "hi"}, mode="sync")
+```
+
+`Run.done` is true for every status except `queued` and `running`. Finished
+statuses are `ok`, `error`, `cancelled`, `timeout`, `waiting` (paused at a
+Human node, see `run.waiting`) and `expired`. `run_and_wait` returns the run
+whatever its final status; check `run.status`.
+
+`callback_url=` on `run()` and `run_and_wait()` asks the server to POST the
+result to your URL when the run ends.
+
+## Async
+
+```python
+import asyncio
+from superstep import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:  # configured from the environment
+        run = await client.run_and_wait({"message": "hi"})
+        print(run.final_state)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every API error raises a subclass of `SuperstepError` with `code` (the
+API's stable error code), `status`, `message` and `details`.
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | `401 TRIGGER_TOKEN_INVALID`: missing, wrong or revoked token, or a token of another workflow |
+| `NotFoundError` | `404 RUN_NOT_FOUND` |
+| `InvalidRequestError` | `400 RUN_INPUT_INVALID`, `CALLBACK_URL_INVALID`; `422 VALIDATION_ERROR` |
+| `PayloadTooLargeError` | `413 RUN_INPUT_TOO_LARGE` |
+| `RateLimitError` | `429 RATE_LIMITED`; `retry_after` holds the seconds to wait |
+| `ServerError` | `5xx` |
+| `APIConnectionError` | Network failure, or a response that is not the API envelope |
+| `WaitTimeoutError` | `wait` / `run_and_wait` ran out of time; `err.run` is the last state |
+| `ConfigError` | Missing base URL, token or workflow id |
+
+```python
+from superstep import RateLimitError
+import time
+
+try:
+    run = client.run({"message": "hi"})
+except RateLimitError as err:
+    time.sleep(err.retry_after or 1)
+```
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                                   # unit tests, mocked HTTP
+```
+
+`tests/test_spec_sync.py` checks the models against the public spec. The live
+test (`tests/test_integration.py`) runs when `SUPERSTEP_IT_BASE_URL`,
+`SUPERSTEP_IT_TOKEN` and `SUPERSTEP_IT_WORKFLOW_ID` are set;
+`scripts/sdk_integration.sh` at the repository root starts a local backend,
+creates a token and runs it for both SDKs.
+
+## License
+
+MIT

superstep-0.1.0/README.md

@@ -0,0 +1,121 @@
+# superstep (Python SDK)
+
+Python client for the Superstep public API: start a workflow run from your own
+service, poll it, and read its final state. Sync and async clients, typed
+models and typed errors; the only dependency is `httpx`.
+
+- Guide: <https://quinguyen1502.github.io/superstep/run/public-api/>
+- API reference: <https://quinguyen1502.github.io/superstep/reference/public-api/>
+- Spec: [`docs/api/openapi.public.json`](../../docs/api/openapi.public.json)
+
+## Install
+
+```bash
+pip install superstep
+# from the repository, before the first release:
+pip install ./sdk/python
+```
+
+Python 3.9 or later.
+
+## Configure
+
+A workflow token (`wft_...`) starts runs of one workflow. The workflow owner
+creates it in the editor under **More (⋯) → API → Create token**; it is shown
+once.
+
+```python
+from superstep import Client
+
+client = Client(
+    workflow_id="example",
+    token="wft_...",
+    base_url="https://superstep.example.com",
+)
+```
+
+Arguments left out are read from `SUPERSTEP_WORKFLOW_ID`, `SUPERSTEP_TOKEN`
+and `SUPERSTEP_BASE_URL`. A missing value raises `ConfigError`.
+
+## Run a workflow
+
+```python
+# Start and wait: polls with a growing interval (1 s, 1.5 s, ... up to 10 s).
+run = client.run_and_wait({"message": "where is my order A100"}, timeout=120)
+print(run.status, run.final_state)
+
+# Or step by step.
+started = client.run({"message": "hi"})       # status "queued", poll_url set
+current = client.get_run(started.run_id)      # status, final_state, metrics ...
+done = client.wait(started.run_id, timeout=60, poll_interval=0.5)
+
+# Let the server wait (up to STUDIO_SYNC_WAIT_MAX seconds, default 30).
+run = client.run({"message": "hi"}, mode="sync")
+```
+
+`Run.done` is true for every status except `queued` and `running`. Finished
+statuses are `ok`, `error`, `cancelled`, `timeout`, `waiting` (paused at a
+Human node, see `run.waiting`) and `expired`. `run_and_wait` returns the run
+whatever its final status; check `run.status`.
+
+`callback_url=` on `run()` and `run_and_wait()` asks the server to POST the
+result to your URL when the run ends.
+
+## Async
+
+```python
+import asyncio
+from superstep import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:  # configured from the environment
+        run = await client.run_and_wait({"message": "hi"})
+        print(run.final_state)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every API error raises a subclass of `SuperstepError` with `code` (the
+API's stable error code), `status`, `message` and `details`.
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | `401 TRIGGER_TOKEN_INVALID`: missing, wrong or revoked token, or a token of another workflow |
+| `NotFoundError` | `404 RUN_NOT_FOUND` |
+| `InvalidRequestError` | `400 RUN_INPUT_INVALID`, `CALLBACK_URL_INVALID`; `422 VALIDATION_ERROR` |
+| `PayloadTooLargeError` | `413 RUN_INPUT_TOO_LARGE` |
+| `RateLimitError` | `429 RATE_LIMITED`; `retry_after` holds the seconds to wait |
+| `ServerError` | `5xx` |
+| `APIConnectionError` | Network failure, or a response that is not the API envelope |
+| `WaitTimeoutError` | `wait` / `run_and_wait` ran out of time; `err.run` is the last state |
+| `ConfigError` | Missing base URL, token or workflow id |
+
+```python
+from superstep import RateLimitError
+import time
+
+try:
+    run = client.run({"message": "hi"})
+except RateLimitError as err:
+    time.sleep(err.retry_after or 1)
+```
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                                   # unit tests, mocked HTTP
+```
+
+`tests/test_spec_sync.py` checks the models against the public spec. The live
+test (`tests/test_integration.py`) runs when `SUPERSTEP_IT_BASE_URL`,
+`SUPERSTEP_IT_TOKEN` and `SUPERSTEP_IT_WORKFLOW_ID` are set;
+`scripts/sdk_integration.sh` at the repository root starts a local backend,
+creates a token and runs it for both SDKs.
+
+## License
+
+MIT

superstep-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "superstep"
+dynamic = ["version"]
+description = "Python client for the Superstep public API: start workflow runs and read their results."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Qui Nguyen" }]
+dependencies = ["httpx>=0.25,<1"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Framework :: AsyncIO",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+# `factory deps apply` installs `.[test]`, so verification has pytest without it in base deps.
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/quinguyen1502/superstep"
+Documentation = "https://quinguyen1502.github.io/superstep/run/public-api/"
+
+[tool.hatch.version]
+path = "src/superstep/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/superstep"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

superstep-0.1.0/src/superstep/__init__.py

@@ -0,0 +1,10 @@
+"""Superstep Python SDK: start workflow runs over the public API and read their results."""
+from ._client import AsyncClient, Client
+from ._errors import (APIConnectionError, AuthenticationError, ConfigError, InvalidRequestError, NotFoundError, PayloadTooLargeError,
+                      RateLimitError, ServerError, SuperstepError, WaitTimeoutError)
+from ._models import Run, RunMetrics, RunStatus, RunWaiting
+from ._version import __version__
+
+__all__ = ["Client", "AsyncClient", "Run", "RunMetrics", "RunStatus", "RunWaiting", "SuperstepError", "ConfigError",
+           "APIConnectionError", "AuthenticationError", "NotFoundError", "InvalidRequestError", "PayloadTooLargeError",
+           "RateLimitError", "ServerError", "WaitTimeoutError", "__version__"]

superstep-0.1.0/src/superstep/_base.py

@@ -0,0 +1,64 @@
+"""What the sync and async clients share: configuration, request building, envelope parsing and the poll schedule."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Iterator, Optional
+from urllib.parse import quote
+
+from ._errors import APIConnectionError, ConfigError, error_for
+from ._models import Run
+from ._version import __version__
+
+ENV_BASE_URL, ENV_TOKEN, ENV_WORKFLOW_ID = "SUPERSTEP_BASE_URL", "SUPERSTEP_TOKEN", "SUPERSTEP_WORKFLOW_ID"
+DEFAULT_TIMEOUT = 60.0  # per HTTP request; a `sync` start may hold the connection up to STUDIO_SYNC_WAIT_MAX (30 s)
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    token: str
+    workflow_id: str
+
+    @classmethod
+    def resolve(cls, base_url: Optional[str], token: Optional[str], workflow_id: Optional[str]) -> "Config":
+        values = {"base_url": base_url or os.environ.get(ENV_BASE_URL), "token": token or os.environ.get(ENV_TOKEN),
+                  "workflow_id": workflow_id or os.environ.get(ENV_WORKFLOW_ID)}
+        env = {"base_url": ENV_BASE_URL, "token": ENV_TOKEN, "workflow_id": ENV_WORKFLOW_ID}
+        missing = [f"{k} (or {env[k]})" for k, v in values.items() if not v]
+        if missing: raise ConfigError("Missing " + ", ".join(missing), code="CONFIG_MISSING")
+        return cls(base_url=str(values["base_url"]).rstrip("/"), token=str(values["token"]), workflow_id=str(values["workflow_id"]))
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return {"X-Workflow-Token": self.token, "Accept": "application/json", "User-Agent": f"superstep-python/{__version__}"}
+
+    def runs_url(self, run_id: Optional[str] = None) -> str:
+        url = f"{self.base_url}/api/hooks/workflows/{quote(self.workflow_id, safe='')}/runs"
+        return f"{url}/{quote(run_id, safe='')}" if run_id else url
+
+
+def start_body(input: Optional[Dict[str, Any]], mode: str, callback_url: Optional[str]) -> Dict[str, Any]:
+    if mode not in ("async", "sync"): raise ValueError("mode must be 'async' or 'sync'")
+    body: Dict[str, Any] = {"input": input or {}, "mode": mode}
+    if callback_url: body["callback_url"] = callback_url
+    return body
+
+
+def parse(status: int, headers: Dict[str, str], payload: Any) -> Run:
+    """Unwrap the envelope; raise the typed error for an error envelope."""
+    if not isinstance(payload, dict) or "success" not in payload:
+        raise APIConnectionError(f"Unexpected response (HTTP {status}); is base_url a Superstep server?", code="BAD_RESPONSE", status=status)
+    if not payload["success"]:
+        err = payload.get("error") or {}
+        raise error_for(status, err.get("code", "UNKNOWN"), err.get("message", f"HTTP {status}"), err.get("details"), headers)
+    return Run.from_dict(payload["data"])
+
+
+def poll_delays(initial: float, maximum: float, factor: float) -> Iterator[float]:
+    """initial, initial*factor, ... capped at maximum."""
+    if initial <= 0 or factor < 1: raise ValueError("poll_interval must be > 0 and backoff >= 1")
+    delay = initial
+    while True:
+        yield min(delay, maximum)
+        delay *= factor

superstep-0.1.0/src/superstep/_client.py

@@ -0,0 +1,125 @@
+"""Sync and async clients. Both send the same requests (`_base`); only the transport and sleeping differ."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._base import DEFAULT_TIMEOUT, Config, parse, poll_delays, start_body
+from ._errors import APIConnectionError, WaitTimeoutError
+from ._models import Run
+
+
+def _json(r: httpx.Response) -> Any:
+    try: return r.json()
+    except ValueError: return None
+
+
+class _Common:
+    def __init__(self, workflow_id: Optional[str], token: Optional[str], base_url: Optional[str]):
+        self.config = Config.resolve(base_url, token, workflow_id)
+
+    def _deadline(self, timeout: Optional[float]) -> Optional[float]:
+        return None if timeout is None else time.monotonic() + timeout
+
+    @staticmethod
+    def _sleep_for(delay: float, deadline: Optional[float], run: Run) -> float:
+        if deadline is None: return delay
+        left = deadline - time.monotonic()
+        if left <= 0: raise WaitTimeoutError(f"Run {run.run_id} still {run.status} after the timeout", run)
+        return min(delay, left)
+
+
+class Client(_Common):
+    """Synchronous client.
+
+        client = Client(workflow_id="example", token="wft_...", base_url="http://localhost:8080")
+        run = client.run_and_wait({"message": "hi"}, timeout=60)
+
+    Unset arguments fall back to SUPERSTEP_WORKFLOW_ID, SUPERSTEP_TOKEN and SUPERSTEP_BASE_URL.
+    """
+
+    def __init__(self, workflow_id: Optional[str] = None, token: Optional[str] = None, base_url: Optional[str] = None, *,
+                 timeout: float = DEFAULT_TIMEOUT, http_client: Optional[httpx.Client] = None):
+        super().__init__(workflow_id, token, base_url)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+
+    def _send(self, method: str, url: str, body: Optional[Dict[str, Any]] = None) -> Run:
+        try: r = self._http.request(method, url, json=body, headers=self.config.headers)
+        except httpx.HTTPError as e: raise APIConnectionError(str(e) or type(e).__name__, code="CONNECTION_ERROR") from e
+        return parse(r.status_code, dict(r.headers), _json(r))
+
+    def run(self, input: Optional[Dict[str, Any]] = None, *, mode: str = "async", callback_url: Optional[str] = None) -> Run:
+        """Start a run. `async` returns at once (status `queued`); `sync` waits up to the server's limit."""
+        return self._send("POST", self.config.runs_url(), start_body(input, mode, callback_url))
+
+    def get_run(self, run_id: str) -> Run:
+        return self._send("GET", self.config.runs_url(run_id))
+
+    def wait(self, run_id: str, *, timeout: Optional[float] = 300.0, poll_interval: float = 1.0, max_poll_interval: float = 10.0,
+             backoff: float = 1.5) -> Run:
+        """Poll until the run is done. Raises WaitTimeoutError after `timeout` seconds (None waits forever)."""
+        deadline, delays = self._deadline(timeout), poll_delays(poll_interval, max_poll_interval, backoff)
+        while True:
+            run = self.get_run(run_id)
+            if run.done: return run
+            time.sleep(self._sleep_for(next(delays), deadline, run))
+
+    def run_and_wait(self, input: Optional[Dict[str, Any]] = None, *, timeout: Optional[float] = 300.0, poll_interval: float = 1.0,
+                     max_poll_interval: float = 10.0, backoff: float = 1.5, callback_url: Optional[str] = None) -> Run:
+        """Start a run and poll (interval growing by `backoff` up to `max_poll_interval`) until it is done."""
+        started = self.run(input, callback_url=callback_url)
+        if started.done: return started
+        return self.wait(started.run_id, timeout=timeout, poll_interval=poll_interval, max_poll_interval=max_poll_interval, backoff=backoff)
+
+    def close(self) -> None:
+        if self._owns_http: self._http.close()
+
+    def __enter__(self) -> "Client": return self
+
+    def __exit__(self, *exc: Any) -> None: self.close()
+
+
+class AsyncClient(_Common):
+    """Asynchronous client with the same methods as `Client`, as coroutines."""
+
+    def __init__(self, workflow_id: Optional[str] = None, token: Optional[str] = None, base_url: Optional[str] = None, *,
+                 timeout: float = DEFAULT_TIMEOUT, http_client: Optional[httpx.AsyncClient] = None):
+        super().__init__(workflow_id, token, base_url)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_http = http_client is None
+
+    async def _send(self, method: str, url: str, body: Optional[Dict[str, Any]] = None) -> Run:
+        try: r = await self._http.request(method, url, json=body, headers=self.config.headers)
+        except httpx.HTTPError as e: raise APIConnectionError(str(e) or type(e).__name__, code="CONNECTION_ERROR") from e
+        return parse(r.status_code, dict(r.headers), _json(r))
+
+    async def run(self, input: Optional[Dict[str, Any]] = None, *, mode: str = "async", callback_url: Optional[str] = None) -> Run:
+        return await self._send("POST", self.config.runs_url(), start_body(input, mode, callback_url))
+
+    async def get_run(self, run_id: str) -> Run:
+        return await self._send("GET", self.config.runs_url(run_id))
+
+    async def wait(self, run_id: str, *, timeout: Optional[float] = 300.0, poll_interval: float = 1.0, max_poll_interval: float = 10.0,
+                   backoff: float = 1.5) -> Run:
+        deadline, delays = self._deadline(timeout), poll_delays(poll_interval, max_poll_interval, backoff)
+        while True:
+            run = await self.get_run(run_id)
+            if run.done: return run
+            await asyncio.sleep(self._sleep_for(next(delays), deadline, run))
+
+    async def run_and_wait(self, input: Optional[Dict[str, Any]] = None, *, timeout: Optional[float] = 300.0, poll_interval: float = 1.0,
+                           max_poll_interval: float = 10.0, backoff: float = 1.5, callback_url: Optional[str] = None) -> Run:
+        started = await self.run(input, callback_url=callback_url)
+        if started.done: return started
+        return await self.wait(started.run_id, timeout=timeout, poll_interval=poll_interval, max_poll_interval=max_poll_interval, backoff=backoff)
+
+    async def aclose(self) -> None:
+        if self._owns_http: await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient": return self
+
+    async def __aexit__(self, *exc: Any) -> None: await self.aclose()

superstep-0.1.0/src/superstep/_errors.py

@@ -0,0 +1,85 @@
+"""Typed errors, mapped from the API's stable error codes (docs/api-errors.md), then from the HTTP status."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type
+
+
+class SuperstepError(Exception):
+    """Base class. `code` is the API error code (or a client-side one such as CONNECTION_ERROR)."""
+
+    def __init__(self, message: str, *, code: str = "UNKNOWN", status: Optional[int] = None, details: Any = None,
+                 headers: Optional[Dict[str, str]] = None):
+        super().__init__(message)
+        self.message, self.code, self.status, self.details, self.headers = message, code, status, details, headers or {}
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, status={self.status!r}, message={self.message!r})"
+
+
+class ConfigError(SuperstepError):
+    """Missing base URL, token or workflow id."""
+
+
+class APIConnectionError(SuperstepError):
+    """The request did not reach the server or the response was not the API's envelope."""
+
+
+class AuthenticationError(SuperstepError):
+    """401 TRIGGER_TOKEN_INVALID: missing, invalid or revoked token, or a token of another workflow."""
+
+
+class NotFoundError(SuperstepError):
+    """404, e.g. RUN_NOT_FOUND."""
+
+
+class InvalidRequestError(SuperstepError):
+    """400 / 422: RUN_INPUT_INVALID, CALLBACK_URL_INVALID, VALIDATION_ERROR (see `details`)."""
+
+
+class PayloadTooLargeError(SuperstepError):
+    """413 RUN_INPUT_TOO_LARGE."""
+
+
+class RateLimitError(SuperstepError):
+    """429 RATE_LIMITED. `retry_after` is the number of seconds to wait."""
+
+    @property
+    def retry_after(self) -> Optional[float]:
+        value = self.headers.get("retry-after") or self.headers.get("Retry-After")
+        try: return float(value) if value is not None else None
+        except ValueError: return None
+
+
+class ServerError(SuperstepError):
+    """5xx, e.g. INTERNAL_ERROR."""
+
+
+class WaitTimeoutError(SuperstepError):
+    """`run_and_wait` gave up before the run finished. `run` is the last state seen."""
+
+    def __init__(self, message: str, run: Any):
+        super().__init__(message, code="WAIT_TIMEOUT")
+        self.run = run
+
+
+BY_CODE: Dict[str, Type[SuperstepError]] = {
+    "TRIGGER_TOKEN_INVALID": AuthenticationError,
+    "RUN_NOT_FOUND": NotFoundError,
+    "WORKFLOW_NOT_FOUND": NotFoundError,
+    "NOT_FOUND": NotFoundError,
+    "RUN_INPUT_INVALID": InvalidRequestError,
+    "CALLBACK_URL_INVALID": InvalidRequestError,
+    "VALIDATION_ERROR": InvalidRequestError,
+    "BAD_REQUEST": InvalidRequestError,
+    "RUN_INPUT_TOO_LARGE": PayloadTooLargeError,
+    "PAYLOAD_TOO_LARGE": PayloadTooLargeError,
+    "RATE_LIMITED": RateLimitError,
+    "INTERNAL_ERROR": ServerError,
+}
+BY_STATUS: Dict[int, Type[SuperstepError]] = {401: AuthenticationError, 404: NotFoundError, 400: InvalidRequestError,
+                                              422: InvalidRequestError, 413: PayloadTooLargeError, 429: RateLimitError}
+
+
+def error_for(status: int, code: str, message: str, details: Any = None, headers: Optional[Dict[str, str]] = None) -> SuperstepError:
+    cls = BY_CODE.get(code) or BY_STATUS.get(status) or (ServerError if status >= 500 else SuperstepError)
+    return cls(message, code=code, status=status, details=details, headers=headers)

superstep-0.1.0/src/superstep/_models.py

@@ -0,0 +1,59 @@
+"""Typed models of the public API payloads (docs/api/openapi.public.json; tests/test_spec_sync.py keeps them in step)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, Dict, Literal, Optional, Tuple
+
+RunStatus = Literal["queued", "running", "ok", "error", "cancelled", "timeout", "waiting", "expired"]
+PENDING: Tuple[str, ...] = ("queued", "running")
+
+
+def _pick(cls, data: Optional[Dict[str, Any]]):
+    if data is None: return None
+    names = {f.name for f in fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in names})
+
+
+@dataclass(frozen=True)
+class RunMetrics:
+    duration_ms: Optional[float] = None
+    tokens_in: Optional[int] = None
+    tokens_out: Optional[int] = None
+    cost_usd: Optional[float] = None
+    error_count: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class RunWaiting:
+    """The Human node a `waiting` run is paused at."""
+    node: Optional[str] = None
+    prompt: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Run:
+    """A run as returned by `run()` and `get_run()`. A just-queued run has only `run_id`, `status` and `poll_url`."""
+    run_id: str
+    status: RunStatus
+    workflow_id: Optional[str] = None
+    source: Optional[str] = None
+    final_state: Optional[Dict[str, Any]] = None
+    error: Optional[Any] = None
+    waiting: Optional[RunWaiting] = None
+    metrics: Optional[RunMetrics] = None
+    trace_url: Optional[str] = None
+    started: Optional[float] = None
+    ended: Optional[float] = None
+    poll_url: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def done(self) -> bool:
+        """True once the run has stopped changing (any status but `queued` / `running`)."""
+        return self.status not in PENDING
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Run":
+        plain = {f.name for f in fields(cls)} - {"waiting", "metrics", "raw"}
+        return cls(**{k: v for k, v in data.items() if k in plain}, waiting=_pick(RunWaiting, data.get("waiting")),
+                   metrics=_pick(RunMetrics, data.get("metrics")), raw=dict(data))

superstep-0.1.0/src/superstep/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

superstep-0.1.0/tests/conftest.py

@@ -0,0 +1,44 @@
+import json
+from typing import Callable, List
+
+import httpx
+import pytest
+
+BASE, WID, TOKEN = "http://superstep.test", "wf1", "wft_test"
+
+
+def env(data, status=200, headers=None):
+    return httpx.Response(status, json={"success": True, "data": data, "error": None}, headers=headers)
+
+
+def err(code, status, message="boom", details=None, headers=None):
+    return httpx.Response(status, json={"success": False, "data": None, "error": {"code": code, "message": message, "details": details}},
+                          headers=headers)
+
+
+class Recorder:
+    """A scripted server: each request pops the next response (or calls it with the request)."""
+
+    def __init__(self, *responses):
+        self.responses: List = list(responses)
+        self.requests: List[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        nxt = self.responses.pop(0)
+        return nxt(request) if isinstance(nxt, Callable) else nxt
+
+    def body(self, i=0):
+        return json.loads(self.requests[i].content)
+
+
+@pytest.fixture
+def no_env(monkeypatch):
+    for k in ("SUPERSTEP_BASE_URL", "SUPERSTEP_TOKEN", "SUPERSTEP_WORKFLOW_ID"): monkeypatch.delenv(k, raising=False)
+
+
+@pytest.fixture
+def no_sleep(monkeypatch):
+    slept = []
+    monkeypatch.setattr("superstep._client.time.sleep", slept.append)
+    return slept

superstep-0.1.0/tests/test_async.py

@@ -0,0 +1,33 @@
+import httpx
+import pytest
+
+from superstep import AsyncClient, AuthenticationError, WaitTimeoutError
+from conftest import BASE, TOKEN, WID, Recorder, env, err
+from test_client import DONE, QUEUED, RUNNING
+
+
+@pytest.fixture
+def no_async_sleep(monkeypatch):
+    slept = []
+
+    async def fake(s): slept.append(s)
+    monkeypatch.setattr("superstep._client.asyncio.sleep", fake)
+    return slept
+
+
+def make(rec):
+    return AsyncClient(WID, TOKEN, BASE, http_client=httpx.AsyncClient(transport=httpx.MockTransport(rec)))
+
+
+async def test_async_run_and_wait(no_env, no_async_sleep):
+    rec = Recorder(env(QUEUED, 202), env(RUNNING), env(DONE))
+    async with make(rec) as c:
+        run = await c.run_and_wait({"x": 1}, poll_interval=0.5)
+    assert run.final_state == {"answer": 42} and no_async_sleep == [0.5] and rec.body() == {"input": {"x": 1}, "mode": "async"}
+
+
+async def test_async_errors_and_timeout(no_env, no_async_sleep):
+    with pytest.raises(AuthenticationError):
+        await make(Recorder(err("TRIGGER_TOKEN_INVALID", 401))).get_run("r1")
+    with pytest.raises(WaitTimeoutError):
+        await make(Recorder(env(QUEUED, 202), env(RUNNING))).run_and_wait({}, timeout=0)

superstep-0.1.0/tests/test_client.py

@@ -0,0 +1,100 @@
+import httpx
+import pytest
+
+from superstep import (APIConnectionError, AuthenticationError, Client, ConfigError, InvalidRequestError, NotFoundError,
+                       PayloadTooLargeError, RateLimitError, Run, ServerError, SuperstepError, WaitTimeoutError)
+from superstep._base import poll_delays
+from conftest import BASE, TOKEN, WID, Recorder, env, err
+
+QUEUED = {"run_id": "r1", "status": "queued", "poll_url": f"{BASE}/api/hooks/workflows/{WID}/runs/r1"}
+DONE = {"run_id": "r1", "workflow_id": WID, "status": "ok", "source": "api", "final_state": {"answer": 42}, "error": None, "waiting": None,
+        "metrics": {"duration_ms": 12.5, "tokens_in": 1, "tokens_out": 2, "cost_usd": 0.0, "error_count": 0}, "trace_url": None,
+        "started": 1.0, "ended": 2.0}
+RUNNING = {**DONE, "status": "running", "final_state": None, "metrics": None, "ended": None}
+
+
+def make(rec, **kw):
+    return Client(WID, TOKEN, BASE + "/", http_client=httpx.Client(transport=httpx.MockTransport(rec)), **kw)
+
+
+def test_run_sends_token_body_and_parses(no_env):
+    rec = Recorder(env(QUEUED, 202))
+    run = make(rec).run({"q": 1}, callback_url="https://hook.example.com")
+    req = rec.requests[0]
+    assert req.method == "POST" and str(req.url) == f"{BASE}/api/hooks/workflows/{WID}/runs"
+    assert req.headers["x-workflow-token"] == TOKEN and req.headers["user-agent"].startswith("superstep-python/")
+    assert rec.body() == {"input": {"q": 1}, "mode": "async", "callback_url": "https://hook.example.com"}
+    assert isinstance(run, Run) and run.status == "queued" and not run.done and run.poll_url == QUEUED["poll_url"]
+
+
+def test_get_run_typed_model(no_env):
+    rec = Recorder(env(DONE))
+    run = make(rec).get_run("r 1")
+    assert str(rec.requests[0].url).endswith("/runs/r%201")
+    assert run.done and run.final_state == {"answer": 42} and run.metrics.duration_ms == 12.5 and run.raw["source"] == "api"
+
+
+def test_run_and_wait_polls_with_backoff(no_env, no_sleep):
+    rec = Recorder(env(QUEUED, 202), env(RUNNING), env(RUNNING), env(RUNNING), env(DONE))
+    run = make(rec).run_and_wait({}, poll_interval=1, backoff=2, max_poll_interval=3)
+    assert run.status == "ok" and no_sleep == [1, 2, 3] and len(rec.requests) == 5
+
+
+def test_run_and_wait_times_out(no_env, monkeypatch):
+    clock = iter(range(0, 1000, 5))
+    monkeypatch.setattr("superstep._client.time.monotonic", lambda: next(clock))
+    monkeypatch.setattr("superstep._client.time.sleep", lambda s: None)
+    rec = Recorder(env(QUEUED, 202), *[env(RUNNING)] * 10)
+    with pytest.raises(WaitTimeoutError) as e:
+        make(rec).run_and_wait({}, timeout=12)
+    assert e.value.run.status == "running" and e.value.code == "WAIT_TIMEOUT"
+
+
+def test_sync_mode_returns_the_result(no_env):
+    rec = Recorder(env(DONE))
+    assert make(rec).run({}, mode="sync").status == "ok" and rec.body()["mode"] == "sync"
+    with pytest.raises(ValueError): make(Recorder()).run({}, mode="later")
+
+
+@pytest.mark.parametrize("code,status,cls", [
+    ("TRIGGER_TOKEN_INVALID", 401, AuthenticationError), ("RUN_NOT_FOUND", 404, NotFoundError), ("RUN_INPUT_INVALID", 400, InvalidRequestError),
+    ("CALLBACK_URL_INVALID", 400, InvalidRequestError), ("VALIDATION_ERROR", 422, InvalidRequestError),
+    ("RUN_INPUT_TOO_LARGE", 413, PayloadTooLargeError), ("INTERNAL_ERROR", 500, ServerError), ("SOMETHING_NEW", 503, ServerError),
+    ("SOMETHING_NEW", 418, SuperstepError)])
+def test_errors_are_typed_by_code(no_env, code, status, cls):
+    with pytest.raises(cls) as e:
+        make(Recorder(err(code, status, details=[{"field": "mode"}]))).get_run("r1")
+    assert type(e.value) is cls and e.value.code == code and e.value.status == status
+
+
+def test_rate_limit_exposes_retry_after(no_env):
+    with pytest.raises(RateLimitError) as e:
+        make(Recorder(err("RATE_LIMITED", 429, headers={"Retry-After": "7"}))).run({})
+    assert e.value.retry_after == 7.0
+
+
+def test_non_envelope_and_network_errors(no_env):
+    with pytest.raises(APIConnectionError) as e:
+        make(Recorder(httpx.Response(502, text="<html>bad gateway</html>"))).get_run("r1")
+    assert e.value.code == "BAD_RESPONSE"
+
+    def down(request): raise httpx.ConnectError("refused", request=request)
+    with pytest.raises(APIConnectionError) as e:
+        make(Recorder(down)).get_run("r1")
+    assert e.value.code == "CONNECTION_ERROR"
+
+
+def test_env_var_fallback(no_env, monkeypatch):
+    with pytest.raises(ConfigError) as e: Client()
+    assert "SUPERSTEP_TOKEN" in str(e.value)
+    monkeypatch.setenv("SUPERSTEP_BASE_URL", "http://env.test/"); monkeypatch.setenv("SUPERSTEP_TOKEN", "wft_env")
+    monkeypatch.setenv("SUPERSTEP_WORKFLOW_ID", "wenv")
+    with Client() as c:
+        assert c.config.runs_url("x") == "http://env.test/api/hooks/workflows/wenv/runs/x" and c.config.token == "wft_env"
+    assert Client(token="wft_arg").config.token == "wft_arg"  # arguments win
+
+
+def test_poll_delays():
+    d = poll_delays(0.5, 2, 2)
+    assert [next(d) for _ in range(5)] == [0.5, 1, 2, 2, 2]
+    with pytest.raises(ValueError): next(poll_delays(0, 1, 1))

superstep-0.1.0/tests/test_integration.py

@@ -0,0 +1,29 @@
+"""Live test against a running backend. scripts/sdk_integration.sh (repository root) starts one and sets the variables."""
+import os
+
+import pytest
+
+from superstep import AsyncClient, AuthenticationError, Client, NotFoundError
+
+IT = {k: os.environ.get(f"SUPERSTEP_IT_{k.upper()}") for k in ("base_url", "token", "workflow_id")}
+pytestmark = pytest.mark.skipif(not all(IT.values()), reason="set SUPERSTEP_IT_BASE_URL, SUPERSTEP_IT_TOKEN, SUPERSTEP_IT_WORKFLOW_ID")
+INPUT = {"message": "where is my order A100"}
+
+
+def test_live_sync_client():
+    with Client(**IT) as c:
+        started = c.run(INPUT)
+        assert started.status == "queued" and started.poll_url.endswith(started.run_id)
+        run = c.wait(started.run_id, timeout=60, poll_interval=0.2)
+        assert run.status == "ok" and run.final_state["intent"] == "order_status" and run.source == "api"
+        assert c.run_and_wait(INPUT, timeout=60, poll_interval=0.2).status == "ok"
+        assert c.run(INPUT, mode="sync").status == "ok"
+        with pytest.raises(NotFoundError): c.get_run("does-not-exist")
+    with pytest.raises(AuthenticationError), Client(**{**IT, "token": "wft_wrong"}) as bad:
+        bad.run(INPUT)
+
+
+async def test_live_async_client():
+    async with AsyncClient(**IT) as c:
+        run = await c.run_and_wait(INPUT, timeout=60, poll_interval=0.2)
+    assert run.status == "ok" and run.metrics is not None

superstep-0.1.0/tests/test_spec_sync.py

@@ -0,0 +1,38 @@
+"""The hand-written models follow the public spec (docs/api/openapi.public.json)."""
+import json
+import pathlib
+import typing
+from dataclasses import fields
+
+import pytest
+
+from superstep import Run, RunMetrics, RunStatus, RunWaiting
+from superstep._errors import BY_CODE
+
+SPEC = pathlib.Path(__file__).resolve().parents[3] / "docs/api/openapi.public.json"
+pytestmark = pytest.mark.skipif(not SPEC.exists(), reason="run inside the superstep repository")
+
+
+def schemas():
+    return json.loads(SPEC.read_text())["components"]["schemas"]
+
+
+def props(name):
+    return set(schemas()[name]["properties"])
+
+
+def names(cls):
+    return {f.name for f in fields(cls)} - {"raw"}
+
+
+def test_models_match_the_spec():
+    assert names(Run) == props("RunResult") | props("RunAccepted") | props("RunPending")
+    assert names(RunMetrics) == props("RunMetrics") and names(RunWaiting) == props("RunWaiting")
+    assert set(typing.get_args(RunStatus)) == set(schemas()["RunResult"]["properties"]["status"]["enum"])
+
+
+def test_every_documented_error_code_is_mapped():
+    spec = json.loads(SPEC.read_text())
+    codes = {code for item in spec["paths"].values() for op in item.values() for r in op["responses"].values()
+             for code in r["content"]["application/json"].get("examples", {})}
+    assert codes and codes <= set(BY_CODE)