tidebase 0.5.0__py3-none-any.whl

tidebase/__init__.py

@@ -0,0 +1,771 @@
+"""Tidebase Python SDK.
+
+Tidebase is an open-source checkpoint layer for AI agents: wrap your steps,
+and failed runs resume from the last safe point — in your own Postgres,
+without moving execution into a new runtime.
+
+    from tidebase import Tidebase
+
+    tide = Tidebase()  # reads TIDEBASE_URL, default http://localhost:7373
+
+    def workflow(run, input):
+        plan = run.step("plan", lambda: make_plan(input))
+        run.state.set({"status": "writing", "progress": 0.7})
+        return run.step("write-report", lambda: write_report(plan))
+
+    tide.run("generate-report", workflow, run_id=run_id)
+
+Zero dependencies (stdlib only). Mirrors @tidebase/sdk semantics: completed
+steps replay from checkpoints, leases fence concurrent workers, gates resolve
+exactly once, and unkeyed external writes classify as manual_review.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Iterator, Optional
+from urllib import error as urlerror
+from urllib import parse as urlparse
+from urllib import request as urlrequest
+
+__all__ = [
+    "Tidebase",
+    "RunContext",
+    "TidebaseError",
+    "RunCancelled",
+    "GateDecision",
+    "new_run_id",
+    "verify_webhook_signature",
+]
+
+
+class TidebaseError(RuntimeError):
+    """A Tidebase API request failed."""
+
+    def __init__(self, status: int, body: str, path: str):
+        super().__init__(f"Tidebase request failed: {status} {body} ({path})")
+        self.status = status
+        self.body = body
+        self.path = path
+
+
+class RunCancelled(RuntimeError):
+    """The run was cancelled while this worker held it. Let it propagate."""
+
+    def __init__(self, run_id: str):
+        super().__init__(f"Run {run_id} was cancelled")
+        self.run_id = run_id
+
+
+class GateDecision:
+    def __init__(self, gate: dict):
+        self.gate_id: str = gate["id"]
+        self.name: str = gate["name"]
+        self.status: str = gate["status"]
+        self.decision: str = gate["decision"]
+        self.actor: Optional[str] = gate.get("actor")
+        self.payload: Any = gate.get("decisionPayload")
+
+    @property
+    def approved(self) -> bool:
+        return self.decision == "approved"
+
+
+def new_run_id() -> str:
+    return "run_" + uuid.uuid4().hex
+
+
+def _stable_stringify(value: Any) -> str:
+    """Deterministic JSON with sorted object keys.
+
+    Matches the TypeScript SDK's stableStringify for the common JSON types so
+    both SDKs compute the same input hash. (Caveat: floats that JavaScript
+    prints without a fractional part, e.g. 1.0, differ — avoid mixing SDKs on
+    a step whose input contains such floats.)
+    """
+    if value is None or not isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, list):
+        return "[" + ",".join(_stable_stringify(v) for v in value) + "]"
+    return (
+        "{"
+        + ",".join(
+            f"{json.dumps(str(k), ensure_ascii=False)}:{_stable_stringify(value[k])}"
+            for k in sorted(value)
+        )
+        + "}"
+    )
+
+
+def _hash_stable(value: Any) -> str:
+    return hashlib.sha256(_stable_stringify(value).encode("utf-8")).hexdigest()
+
+
+def _classify_resume_decision(options: dict) -> str:
+    """Mirror of the server's inferReplay and the TS SDK's classification."""
+    replay = options.get("replay")
+    if replay == "manual":
+        return "manual_review"
+    if replay == "never":
+        return "fail_hard"
+    if replay == "auto":
+        return "safe_replay"
+    side_effects = [e for e in (options.get("sideEffects") or []) if e]
+    reads_only = len(side_effects) > 0 and all(e == "read" for e in side_effects)
+    writes_externally = len(side_effects) > 0 and not reads_only
+    if writes_externally and not options.get("idempotencyKey"):
+        return "manual_review"
+    return "safe_replay"
+
+
+def verify_webhook_signature(body: bytes, signature_header: Optional[str], secret: str) -> bool:
+    """Verify an HMAC-signed Tidebase webhook payload (timing-safe)."""
+    if not signature_header:
+        return False
+    if signature_header.startswith("sha256="):
+        signature_header = signature_header[len("sha256="):]
+    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature_header)
+
+
+def _serialize_error(error: BaseException) -> dict:
+    return {"name": type(error).__name__, "message": str(error)}
+
+
+class Tidebase:
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        webhook_secret: Optional[str] = None,
+    ):
+        self.url = (url or os.environ.get("TIDEBASE_URL") or "http://localhost:7373").rstrip("/")
+        self.api_key = api_key or os.environ.get("TIDEBASE_API_KEY")
+        self.webhook_secret = webhook_secret or os.environ.get("TIDEBASE_WEBHOOK_SECRET")
+        self.runs = RunsClient(self)
+        self.queues = QueuesClient(self)
+        self.schedules = SchedulesClient(self)
+        self._workflows: dict = {}
+
+    def workflow(self, name: str, fn: Optional[Callable] = None):
+        """Register a workflow for the work loop / webhook handler. Usable as
+        a decorator: @tide.workflow("generate-report")."""
+        if fn is None:
+            def decorator(f):
+                self._workflows[name] = f
+                return f
+            return decorator
+        self._workflows[name] = fn
+        return fn
+
+    # ---- transport -------------------------------------------------------
+
+    def request(self, method: str, path: str, body: Any = None) -> Any:
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        headers = {"content-type": "application/json"}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        req = urlrequest.Request(self.url + path, data=data, headers=headers, method=method)
+        try:
+            with urlrequest.urlopen(req) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urlerror.HTTPError as e:
+            body_text = e.read().decode("utf-8", "replace")
+            try:
+                if json.loads(body_text).get("code") == "run_cancelled":
+                    parts = path.split("/")
+                    run_id = parts[2] if len(parts) > 2 and parts[1] == "runs" else "unknown"
+                    raise RunCancelled(run_id) from None
+            except (ValueError, KeyError, AttributeError):
+                pass
+            raise TidebaseError(e.code, body_text, path) from None
+
+    # ---- workflows -------------------------------------------------------
+
+    def run(
+        self,
+        workflow_name: str,
+        workflow: Callable[["RunContext", Any], Any],
+        run_id: Optional[str] = None,
+        input: Any = None,
+        metadata: Optional[dict] = None,
+        recovery_webhook: Optional[str] = None,
+        channels: Optional[list] = None,
+    ) -> Any:
+        """Create (or resume, when run_id is given) a run and execute the workflow.
+
+        Completed steps inside the workflow replay from their checkpoints; only
+        unfinished steps execute.
+        """
+        if run_id is None:
+            run = self.runs.create(
+                workflow_name,
+                input=input,
+                metadata=metadata,
+                recovery_webhook=recovery_webhook,
+                channels=channels,
+            )
+        else:
+            run = self.runs.get(run_id)["run"]
+
+        if run["workflowName"] != workflow_name:
+            raise ValueError(
+                f"Run {run['id']} belongs to workflow {run['workflowName']}, not {workflow_name}"
+            )
+        if run["status"] == "completed":
+            return run["result"]
+
+        begin = self.request("POST", f"/runs/{run['id']}/begin")
+        return self._execute(run["id"], run["input"], begin["leaseOwner"], workflow)
+
+    def _execute(self, run_id: str, input: Any, lease_owner: str, workflow: Callable) -> Any:
+        context = RunContext(self, run_id, lease_owner)
+        try:
+            result = workflow(context, input)
+            self.request("POST", f"/runs/{run_id}/complete", {"result": result})
+            return result
+        except RunCancelled:
+            # The run is already terminal — never report failure after cancel.
+            raise
+        except BaseException as error:
+            try:
+                self.request("POST", f"/runs/{run_id}/fail", {"error": _serialize_error(error)})
+            except Exception:
+                pass
+            raise
+
+    def enqueue(
+        self,
+        workflow_name: str,
+        *,
+        queue: str = "default",
+        input: Any = None,
+        metadata: Optional[dict] = None,
+        dedupe_key: Optional[str] = None,
+        delay_s: Optional[float] = None,
+        run_at: Optional[str] = None,
+        max_attempts: Optional[int] = None,
+        priority: Optional[int] = None,
+        deadline_s: Optional[float] = None,
+        recovery_webhook: Optional[str] = None,
+    ) -> dict:
+        """Enqueue a workflow as a durable queued run. Returns
+        {"run": ..., "deduplicated": bool}."""
+        body: dict = {"workflowName": workflow_name}
+        if input is not None:
+            body["input"] = input
+        if metadata is not None:
+            body["metadata"] = metadata
+        if dedupe_key is not None:
+            body["dedupeKey"] = dedupe_key
+        if delay_s is not None:
+            body["delayMs"] = int(delay_s * 1000)
+        if run_at is not None:
+            body["runAt"] = run_at
+        if max_attempts is not None:
+            body["maxAttempts"] = max_attempts
+        if priority is not None:
+            body["priority"] = priority
+        if deadline_s is not None:
+            body["deadlineMs"] = int(deadline_s * 1000)
+        if recovery_webhook is not None:
+            body["recoveryWebhook"] = recovery_webhook
+        return self.request("POST", f"/queues/{urlparse.quote(queue, safe='')}/enqueue", body)
+
+    def work(
+        self,
+        queues: Optional[list] = None,
+        *,
+        lease_owner: Optional[str] = None,
+        poll_s: float = 1.0,
+        limit: int = 1,
+        stop: Optional[Callable[[], bool]] = None,
+        on_error: Optional[Callable[[BaseException, dict], None]] = None,
+    ) -> None:
+        """Pull-mode worker loop: claim ready runs and execute their
+        registered workflows (register with @tide.workflow). Runs until
+        stop() returns True."""
+        queues = queues or ["default"]
+        while not (stop and stop()):
+            claim = self.request(
+                "POST",
+                "/queues/claim",
+                {"queues": queues, "leaseOwner": lease_owner, "limit": limit}
+                if lease_owner
+                else {"queues": queues, "limit": limit},
+            )
+            for run in claim["runs"]:
+                workflow = self._workflows.get(run["workflowName"])
+                if workflow is None:
+                    try:
+                        self.request(
+                            "POST",
+                            f"/runs/{run['id']}/fail",
+                            {"error": {"message": f"no workflow registered for {run['workflowName']}"}},
+                        )
+                    except Exception:
+                        pass
+                    continue
+                try:
+                    self._execute(run["id"], run["input"], claim["leaseOwner"], workflow)
+                except BaseException as error:
+                    if on_error:
+                        on_error(error, run)
+            if not claim["runs"]:
+                time.sleep(poll_s)
+
+
+class RunsClient:
+    def __init__(self, client: Tidebase):
+        self._client = client
+
+    def create(
+        self,
+        workflow_name: str,
+        input: Any = None,
+        metadata: Optional[dict] = None,
+        recovery_webhook: Optional[str] = None,
+        channels: Optional[list] = None,
+    ) -> dict:
+        body: dict = {}
+        if input is not None:
+            body["input"] = input
+        if metadata is not None:
+            body["metadata"] = metadata
+        if recovery_webhook is not None:
+            body["recoveryWebhook"] = recovery_webhook
+        if channels is not None:
+            body["channels"] = channels
+        quoted = urlparse.quote(workflow_name, safe="")
+        return self._client.request("POST", f"/runs/{quoted}", body)["run"]
+
+    def list(self) -> list:
+        return self._client.request("GET", "/runs")["runs"]
+
+    def get(self, run_id: str) -> dict:
+        """Full run detail: run, steps, state, gates, events, usage, children."""
+        return self._client.request("GET", f"/runs/{run_id}")
+
+    def recover(self, run_id: str, reason: str = "manual") -> dict:
+        return self._client.request("POST", f"/runs/{run_id}/recover", {"reason": reason})
+
+    def cancel(self, run_id: str, reason: Optional[str] = None, actor: Optional[str] = None) -> dict:
+        """Cancel a run: authoritative and one-way. In-flight workers observe
+        it at their next step/gate boundary."""
+        body: dict = {}
+        if reason is not None:
+            body["reason"] = reason
+        if actor is not None:
+            body["actor"] = actor
+        return self._client.request("POST", f"/runs/{run_id}/cancel", body)["run"]
+
+    def subscribe(self, run_id: str, after: int = 0) -> Iterator[dict]:
+        """Yield run events from the SSE stream (blocking generator)."""
+        token = f"&token={urlparse.quote(self._client.api_key)}" if self._client.api_key else ""
+        url = f"{self._client.url}/runs/{run_id}/events?after={after}{token}"
+        req = urlrequest.Request(url, headers={"accept": "text/event-stream"})
+        with urlrequest.urlopen(req) as response:
+            for raw in response:
+                line = raw.decode("utf-8").rstrip("\n")
+                if line.startswith("data:"):
+                    yield json.loads(line[len("data:"):].strip())
+
+
+class QueuesClient:
+    def __init__(self, client: "Tidebase"):
+        self._client = client
+
+    def configure(
+        self,
+        name: str,
+        *,
+        concurrency: Optional[int] = None,
+        rate_per_minute: Optional[int] = None,
+        invoke_url: Optional[str] = None,
+    ) -> dict:
+        body: dict = {}
+        if concurrency is not None:
+            body["concurrency"] = concurrency
+        if rate_per_minute is not None:
+            body["ratePerMinute"] = rate_per_minute
+        if invoke_url is not None:
+            body["invokeUrl"] = invoke_url
+        return self._client.request("PUT", f"/queues/{urlparse.quote(name, safe='')}/config", body)
+
+    def list(self) -> list:
+        return self._client.request("GET", "/queues")["queues"]
+
+
+class SchedulesClient:
+    def __init__(self, client: "Tidebase"):
+        self._client = client
+
+    def set(
+        self,
+        name: str,
+        *,
+        cron: str,
+        workflow_name: str,
+        input: Any = None,
+        queue: str = "default",
+        max_attempts: Optional[int] = None,
+        enabled: bool = True,
+    ) -> dict:
+        body: dict = {"cron": cron, "workflowName": workflow_name, "queue": queue, "enabled": enabled}
+        if input is not None:
+            body["input"] = input
+        if max_attempts is not None:
+            body["maxAttempts"] = max_attempts
+        return self._client.request("PUT", f"/schedules/{urlparse.quote(name, safe='')}", body)["schedule"]
+
+    def list(self) -> list:
+        return self._client.request("GET", "/schedules")["schedules"]
+
+    def delete(self, name: str) -> dict:
+        return self._client.request("DELETE", f"/schedules/{urlparse.quote(name, safe='')}")
+
+
+class RunContext:
+    def __init__(self, client: Tidebase, run_id: str, lease_owner: str):
+        self._client = client
+        self.run_id = run_id
+        self._lease_owner = lease_owner
+        self.state = RunState(client, run_id)
+        self.usage = RunUsage(client, run_id)
+        self.snapshots = RunSnapshots(client, run_id)
+
+    # ---- steps -----------------------------------------------------------
+
+    def step(
+        self,
+        name: str,
+        fn: Callable[[], Any],
+        *,
+        input: Any = None,
+        input_hash: Optional[str] = None,
+        retries: int = 0,
+        timeout_s: Optional[float] = None,
+        side_effects: Optional[list] = None,
+        idempotency_key: Optional[str] = None,
+        replay: Optional[str] = None,
+        checkpoint_invariant: Any = None,
+        verified_by: Any = None,
+        credentials: Optional[list] = None,
+    ) -> Any:
+        """Checkpoint a unit of work. On replay the stored output is returned
+        without executing fn. External writes should declare side_effects and
+        an idempotency_key, or final failures classify as manual_review."""
+        options: dict = {}
+        if input is not None:
+            options["input"] = input
+        if retries:
+            options["retries"] = retries
+        if timeout_s is not None:
+            options["timeoutMs"] = int(timeout_s * 1000)
+        if side_effects is not None:
+            options["sideEffects"] = side_effects
+        if idempotency_key is not None:
+            options["idempotencyKey"] = idempotency_key
+        if replay is not None:
+            options["replay"] = replay
+        if checkpoint_invariant is not None:
+            options["checkpointInvariant"] = checkpoint_invariant
+        if verified_by is not None:
+            options["verifiedBy"] = verified_by
+        if credentials is not None:
+            options["credentials"] = credentials
+
+        resolved_hash = input_hash or _hash_stable(input if input is not None else None)
+
+        def begin() -> dict:
+            return self._client.request(
+                "POST",
+                f"/runs/{self.run_id}/steps/begin",
+                {
+                    "name": name,
+                    "inputHash": resolved_hash,
+                    "input": input,
+                    "options": options,
+                    "leaseOwner": self._lease_owner,
+                },
+            )
+
+        current = begin()
+        if current["action"] == "return":
+            return current["output"]
+        if current["action"] == "cancelled":
+            raise RunCancelled(self.run_id)
+        if current["action"] == "input_mismatch":
+            raise ValueError(
+                f"Step {name} input hash changed for this run. "
+                f"Expected {current['expectedInputHash']}, got {current['actualInputHash']}"
+            )
+        if current["action"] == "locked":
+            raise RuntimeError(f"Step {name} is currently leased by another worker")
+
+        attempts = max(1, retries + 1)
+        for attempt in range(1, attempts + 1):
+            if attempt > 1:
+                # A retryable failure released the lease server-side; re-begin
+                # to acquire a fresh lease before reporting results.
+                current = begin()
+                if current["action"] == "return":
+                    return current["output"]
+                if current["action"] == "cancelled":
+                    raise RunCancelled(self.run_id)
+                if current["action"] == "locked":
+                    raise RuntimeError(f"Step {name} is currently leased by another worker")
+                if current["action"] == "input_mismatch":
+                    raise ValueError(f"Step {name} input hash changed for this run")
+            try:
+                result = fn()
+                self._client.request(
+                    "POST",
+                    f"/runs/{self.run_id}/steps/{current['step']['id']}/complete",
+                    {"leaseOwner": current["leaseOwner"], "output": result},
+                )
+                return result
+            except BaseException as error:
+                retryable = attempt < attempts
+                try:
+                    self._client.request(
+                        "POST",
+                        f"/runs/{self.run_id}/steps/{current['step']['id']}/fail",
+                        {
+                            "leaseOwner": current["leaseOwner"],
+                            "retryable": retryable,
+                            "resumeDecision": "auto_retry"
+                            if retryable
+                            else _classify_resume_decision(options),
+                            "error": _serialize_error(error),
+                        },
+                    )
+                except Exception:
+                    pass
+                if not retryable:
+                    raise
+        raise RuntimeError(f"Step {name} failed")
+
+    # ---- gates -----------------------------------------------------------
+
+    def gate(
+        self,
+        name: str,
+        prompt: str,
+        *,
+        data: Any = None,
+        channels: Optional[list] = None,
+        capability: Optional[dict] = None,
+        timeout_s: Optional[float] = None,
+        poll_s: float = 1.0,
+    ) -> GateDecision:
+        """Pause the run on a durable gate until a human decides. The decision
+        resolves exactly once and replays on resume."""
+        body: dict = {
+            "name": name,
+            "prompt": prompt,
+            "data": data if data is not None else {},
+            "channels": channels or [],
+            "capability": capability,
+        }
+        if timeout_s is not None:
+            body["timeoutMs"] = int(timeout_s * 1000)
+        begun = self._client.request("POST", f"/runs/{self.run_id}/gates/begin", body)
+
+        deadline = time.monotonic() + timeout_s if timeout_s else None
+        gate = begun["gate"]
+        while gate["status"] == "pending":
+            if deadline and time.monotonic() > deadline:
+                raise TimeoutError(f"Gate {name} timed out")
+            time.sleep(poll_s)
+            polled = self._client.request("GET", f"/runs/{self.run_id}/gates/{gate['id']}")
+            if polled.get("runStatus") == "cancelled":
+                raise RunCancelled(self.run_id)
+            gate = polled["gate"]
+
+        if gate["decision"] not in ("approved", "rejected", "canceled"):
+            raise RuntimeError(f"Gate {name} resolved with unsupported decision {gate['decision']}")
+        return GateDecision(gate)
+
+    # ---- children & fanout -------------------------------------------------
+
+    def child(
+        self,
+        workflow_name: str,
+        workflow: Callable[["RunContext", Any], Any],
+        *,
+        name: Optional[str] = None,
+        input: Any = None,
+        metadata: Optional[dict] = None,
+        recovery_webhook: Optional[str] = None,
+        channels: Optional[list] = None,
+        edge_type: str = "child",
+        edge_metadata: Optional[dict] = None,
+    ) -> Any:
+        """Run a child workflow. Child creation is idempotent by edge name, so a
+        resumed parent reuses the existing child run."""
+        body = {
+            "name": name or workflow_name,
+            "workflowName": workflow_name,
+            "input": input,
+            "metadata": metadata,
+            "recoveryWebhook": recovery_webhook,
+            "channels": channels,
+            "edgeType": edge_type,
+            "edgeMetadata": edge_metadata,
+        }
+        response = self._client.request(
+            "POST",
+            f"/runs/{self.run_id}/children",
+            {k: v for k, v in body.items() if v is not None},
+        )
+        return self._client.run(workflow_name, workflow, run_id=response["run"]["id"])
+
+    def fanout(self, name: str, children: list, *, checkpoint: Optional[str] = None) -> list:
+        """Run children in parallel as child runs and join durably. Each child
+        is a dict: {"name", "workflow", optional "workflow_name", "input"}."""
+        with ThreadPoolExecutor(max_workers=max(1, len(children))) as pool:
+            futures = [
+                pool.submit(
+                    self.child,
+                    child.get("workflow_name") or child["name"],
+                    child["workflow"],
+                    name=child["name"],
+                    input=child.get("input"),
+                    metadata=child.get("metadata"),
+                    edge_type="fanout",
+                    edge_metadata={"fanout": name},
+                )
+                for child in children
+            ]
+            results = [f.result() for f in futures]
+
+        return self.step(
+            f"join:{checkpoint or name}",
+            lambda: results,
+            input={
+                "fanout": name,
+                "join": "all",
+                "children": [child["name"] for child in children],
+            },
+            replay="auto",
+            checkpoint_invariant="all child run results were collected",
+        )
+
+
+class RunState:
+    def __init__(self, client: Tidebase, run_id: str):
+        self._client = client
+        self._run_id = run_id
+
+    def _write(self, method: str, value: Any, **options: Any) -> Any:
+        body = {"value": value, **_state_options(options)}
+        return self._client.request(method, f"/runs/{self._run_id}/state", body)
+
+    def set(self, value: Any, **options: Any) -> Any:
+        return self._write("PUT", value, **options)
+
+    def patch(self, value: dict, **options: Any) -> Any:
+        return self._write("PATCH", value, **options)
+
+    def save(self, label: str, **options: Any) -> dict:
+        body = {"label": label, **_state_options(options)}
+        return self._client.request("POST", f"/runs/{self._run_id}/state/save", body)
+
+    def versions(self, stream: Optional[str] = None, labeled: Optional[bool] = None) -> list:
+        params = []
+        if stream:
+            params.append(f"stream={urlparse.quote(stream)}")
+        if labeled is not None:
+            params.append(f"labeled={'true' if labeled else 'false'}")
+        suffix = "?" + "&".join(params) if params else ""
+        return self._client.request("GET", f"/runs/{self._run_id}/state/versions{suffix}")[
+            "stateVersions"
+        ]
+
+
+def _state_options(options: dict) -> dict:
+    mapping = {
+        "stream": "stream",
+        "label": "label",
+        "reason": "reason",
+        "importance": "importance",
+        "metadata": "metadata",
+        "created_by": "createdBy",
+    }
+    return {mapping[k]: v for k, v in options.items() if v is not None and k in mapping}
+
+
+class RunUsage:
+    def __init__(self, client: Tidebase, run_id: str):
+        self._client = client
+        self._run_id = run_id
+
+    def record(
+        self,
+        *,
+        step_id: Optional[str] = None,
+        kind: Optional[str] = None,
+        provider: Optional[str] = None,
+        model: Optional[str] = None,
+        label: Optional[str] = None,
+        quantity: Optional[float] = None,
+        unit: Optional[str] = None,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+        total_tokens: Optional[int] = None,
+        cost_usd: Optional[float] = None,
+        metadata: Optional[dict] = None,
+    ) -> Any:
+        body = {
+            "stepId": step_id,
+            "kind": kind,
+            "provider": provider,
+            "model": model,
+            "label": label,
+            "quantity": quantity,
+            "unit": unit,
+            "inputTokens": input_tokens,
+            "outputTokens": output_tokens,
+            "totalTokens": total_tokens,
+            "costUsd": cost_usd,
+            "metadata": metadata,
+        }
+        body = {k: v for k, v in body.items() if v is not None}
+        return self._client.request("POST", f"/runs/{self._run_id}/usage", body)
+
+
+class RunSnapshots:
+    def __init__(self, client: Tidebase, run_id: str):
+        self._client = client
+        self._run_id = run_id
+
+    def create(
+        self,
+        label: str,
+        state: Any,
+        *,
+        target: Optional[dict] = None,
+        reason: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        created_by: Optional[str] = None,
+    ) -> dict:
+        body: dict = {"label": label, "state": state}
+        if target is not None:
+            body["target"] = target
+        if reason is not None:
+            body["reason"] = reason
+        if metadata is not None:
+            body["metadata"] = metadata
+        if created_by is not None:
+            body["createdBy"] = created_by
+        return self._client.request("POST", f"/runs/{self._run_id}/snapshots", body)
+
+    def list(self) -> list:
+        return self._client.request("GET", f"/runs/{self._run_id}/snapshots")["snapshots"]

tidebase/aio.py

@@ -0,0 +1,263 @@
+"""Async support for the Tidebase Python SDK.
+
+`AsyncTidebase` mirrors `tidebase.Tidebase` for asyncio codebases: workflows
+and steps may be `async def`, HTTP calls run off the event loop via
+`asyncio.to_thread`, and cancellation (`tidebase.RunCancelled`) propagates
+through awaits like any other exception — no cleanup branch can miss it.
+
+    from tidebase.aio import AsyncTidebase
+
+    tide = AsyncTidebase()
+
+    @tide.workflow("generate-report")
+    async def generate_report(run, input):
+        plan = await run.step("plan", lambda: make_plan(input))      # sync step
+        text = await run.step("draft", draft_async)                   # async step
+        decision = await run.gate("approve", "Send it?")
+        return await run.step("send", lambda: send(text))
+
+    await tide.run("generate-report", generate_report, input={...})
+    # or: await tide.work(["default"])   # async worker loop
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Callable, Optional
+
+from . import (
+    GateDecision,
+    RunCancelled,
+    RunContext,
+    Tidebase,
+    _classify_resume_decision,
+    _hash_stable,
+    _serialize_error,
+)
+
+__all__ = ["AsyncTidebase", "AsyncRunContext"]
+
+
+async def _maybe_await(value: Any) -> Any:
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+class AsyncRunContext:
+    """Async run context: same checkpoint protocol as RunContext, but the
+    user's step function may be `async def` and is awaited on the event loop
+    (only the HTTP calls run in a thread)."""
+
+    def __init__(self, inner: RunContext):
+        self._inner = inner
+        self._client = inner._client  # noqa: SLF001 — same package
+        self.run_id = inner.run_id
+
+    async def _request(self, method: str, path: str, body: Any = None) -> Any:
+        return await asyncio.to_thread(self._client.request, method, path, body)
+
+    async def step(
+        self,
+        name: str,
+        fn: Callable[[], Any],
+        *,
+        input: Any = None,
+        input_hash: Optional[str] = None,
+        retries: int = 0,
+        side_effects: Optional[list] = None,
+        idempotency_key: Optional[str] = None,
+        replay: Optional[str] = None,
+        checkpoint_invariant: Any = None,
+    ) -> Any:
+        options: dict = {}
+        if input is not None:
+            options["input"] = input
+        if retries:
+            options["retries"] = retries
+        if side_effects is not None:
+            options["sideEffects"] = side_effects
+        if idempotency_key is not None:
+            options["idempotencyKey"] = idempotency_key
+        if replay is not None:
+            options["replay"] = replay
+        if checkpoint_invariant is not None:
+            options["checkpointInvariant"] = checkpoint_invariant
+
+        resolved_hash = input_hash or _hash_stable(input if input is not None else None)
+
+        async def begin() -> dict:
+            return await self._request(
+                "POST",
+                f"/runs/{self.run_id}/steps/begin",
+                {
+                    "name": name,
+                    "inputHash": resolved_hash,
+                    "input": input,
+                    "options": options,
+                    "leaseOwner": self._inner._lease_owner,  # noqa: SLF001
+                },
+            )
+
+        current = await begin()
+        if current["action"] == "return":
+            return current["output"]
+        if current["action"] == "cancelled":
+            raise RunCancelled(self.run_id)
+        if current["action"] in ("locked", "input_mismatch"):
+            raise RuntimeError(f"Step {name}: {current['action']}")
+
+        attempts = max(1, retries + 1)
+        for attempt in range(1, attempts + 1):
+            if attempt > 1:
+                current = await begin()
+                if current["action"] == "return":
+                    return current["output"]
+                if current["action"] == "cancelled":
+                    raise RunCancelled(self.run_id)
+                if current["action"] in ("locked", "input_mismatch"):
+                    raise RuntimeError(f"Step {name}: {current['action']}")
+            try:
+                result = await _maybe_await(fn())
+                await self._request(
+                    "POST",
+                    f"/runs/{self.run_id}/steps/{current['step']['id']}/complete",
+                    {"leaseOwner": current["leaseOwner"], "output": result},
+                )
+                return result
+            except BaseException as error:
+                retryable = attempt < attempts
+                try:
+                    await self._request(
+                        "POST",
+                        f"/runs/{self.run_id}/steps/{current['step']['id']}/fail",
+                        {
+                            "leaseOwner": current["leaseOwner"],
+                            "retryable": retryable,
+                            "resumeDecision": "auto_retry"
+                            if retryable
+                            else _classify_resume_decision(options),
+                            "error": _serialize_error(error),
+                        },
+                    )
+                except Exception:
+                    pass
+                if not retryable:
+                    raise
+        raise RuntimeError(f"Step {name} failed")
+
+    async def gate(self, name: str, prompt: str, **options: Any) -> GateDecision:
+        return await asyncio.to_thread(self._inner.gate, name, prompt, **options)
+
+    async def state_set(self, value: Any, **options: Any) -> Any:
+        return await asyncio.to_thread(self._inner.state.set, value, **options)
+
+    async def state_patch(self, value: dict, **options: Any) -> Any:
+        return await asyncio.to_thread(self._inner.state.patch, value, **options)
+
+    async def state_save(self, label: str, **options: Any) -> Any:
+        return await asyncio.to_thread(self._inner.state.save, label, **options)
+
+    async def usage_record(self, **options: Any) -> Any:
+        return await asyncio.to_thread(self._inner.usage.record, **options)
+
+
+class AsyncTidebase:
+    def __init__(self, url: Optional[str] = None, api_key: Optional[str] = None):
+        self._sync = Tidebase(url=url, api_key=api_key)
+        self._workflows: dict = {}
+        self.runs = self._sync.runs
+        self.queues = self._sync.queues
+        self.schedules = self._sync.schedules
+
+    def workflow(self, name: str, fn: Optional[Callable] = None):
+        if fn is None:
+            def decorator(f):
+                self._workflows[name] = f
+                return f
+            return decorator
+        self._workflows[name] = fn
+        return fn
+
+    async def run(
+        self,
+        workflow_name: str,
+        workflow: Optional[Callable] = None,
+        *,
+        run_id: Optional[str] = None,
+        input: Any = None,
+        **create_options: Any,
+    ) -> Any:
+        workflow = workflow or self._workflows.get(workflow_name)
+        if workflow is None:
+            raise ValueError(f"no workflow registered for {workflow_name}")
+
+        if run_id is None:
+            run = await asyncio.to_thread(
+                self._sync.runs.create, workflow_name, input=input, **create_options
+            )
+        else:
+            detail = await asyncio.to_thread(self._sync.runs.get, run_id)
+            run = detail["run"]
+        if run["status"] == "completed":
+            return run["result"]
+
+        begin = await asyncio.to_thread(self._sync.request, "POST", f"/runs/{run['id']}/begin")
+        return await self._execute(run["id"], run["input"], begin["leaseOwner"], workflow)
+
+    async def _execute(self, run_id: str, input: Any, lease_owner: str, workflow: Callable) -> Any:
+        context = AsyncRunContext(RunContext(self._sync, run_id, lease_owner))
+        try:
+            result = await _maybe_await(workflow(context, input))
+            await asyncio.to_thread(
+                self._sync.request, "POST", f"/runs/{run_id}/complete", {"result": result}
+            )
+            return result
+        except RunCancelled:
+            raise
+        except BaseException as error:
+            try:
+                await asyncio.to_thread(
+                    self._sync.request,
+                    "POST",
+                    f"/runs/{run_id}/fail",
+                    {"error": _serialize_error(error)},
+                )
+            except Exception:
+                pass
+            raise
+
+    async def enqueue(self, workflow_name: str, **options: Any) -> dict:
+        return await asyncio.to_thread(self._sync.enqueue, workflow_name, **options)
+
+    async def cancel(self, run_id: str, reason: Optional[str] = None, actor: Optional[str] = None) -> dict:
+        return await asyncio.to_thread(self._sync.runs.cancel, run_id, reason, actor)
+
+    async def work(
+        self,
+        queues: Optional[list] = None,
+        *,
+        poll_s: float = 1.0,
+        limit: int = 1,
+        on_error: Optional[Callable[[BaseException, dict], None]] = None,
+    ) -> None:
+        """Async worker loop. Cancel the surrounding task to stop."""
+        queues = queues or ["default"]
+        while True:
+            claim = await asyncio.to_thread(
+                self._sync.request, "POST", "/queues/claim", {"queues": queues, "limit": limit}
+            )
+            for run in claim["runs"]:
+                workflow = self._workflows.get(run["workflowName"])
+                if workflow is None:
+                    continue
+                try:
+                    await self._execute(run["id"], run["input"], claim["leaseOwner"], workflow)
+                except asyncio.CancelledError:
+                    raise
+                except BaseException as error:
+                    if on_error:
+                        on_error(error, run)
+            if not claim["runs"]:
+                await asyncio.sleep(poll_s)

tidebase-0.5.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: tidebase
+Version: 0.5.0
+Summary: Python SDK for Tidebase — the open-source checkpoint layer for AI agents. Wrap your steps, and failed runs resume from the last safe point, in your own Postgres.
+Project-URL: Homepage, https://tidebase.dev
+Project-URL: Repository, https://github.com/BlueprintLabIO/tidebase
+Project-URL: Documentation, https://tidebase.dev/docs/
+Author: BlueprintLab
+License-Expression: Apache-2.0
+Keywords: ai-agents,checkpoint,durable,human-in-the-loop,postgres,resume,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# tidebase (Python SDK)
+
+Python SDK for [Tidebase](https://tidebase.dev) — the open-source checkpoint layer for AI agents: wrap your steps, and failed runs resume from the last safe point — in your own Postgres, without moving execution into a new runtime.
+
+Zero dependencies (stdlib only), Python 3.9+.
+
+```python
+from tidebase import Tidebase
+
+tide = Tidebase()  # reads TIDEBASE_URL (default http://localhost:7373) and TIDEBASE_API_KEY
+
+def workflow(run, input):
+    plan = run.step("plan", lambda: make_plan(input))
+    sources = run.step("fetch-sources", lambda: fetch_sources(plan))
+
+    run.state.set({"status": "writing", "progress": 0.7})
+
+    decision = run.gate("approve-report", "Send the report to the customer?")
+    if not decision.approved:
+        raise RuntimeError("not approved")
+
+    return run.step("write-report", lambda: write_report(sources))
+
+tide.run("generate-report", workflow, run_id=run_id)
+```
+
+Re-invoke with the same `run_id` after a crash: completed steps return from their checkpoints instantly; only unfinished steps execute.
+
+## Surface
+
+| Call | Does |
+|---|---|
+| `tide.run(name, workflow, run_id=…, input=…)` | Create or resume a run |
+| `run.step(name, fn, side_effects=…, idempotency_key=…, retries=…)` | Checkpoint a unit of work; replays from storage on resume |
+| `run.state.set / patch / save / versions` | Live state + versioned history (snapshot = labeled version) |
+| `run.gate(name, prompt)` | Durable human approval; resolves exactly once |
+| `run.child(...)` / `run.fanout(name, children)` | Subagents as child runs, idempotent by edge name, durable join |
+| `run.usage.record(kind=…, input_tokens=…, cost_usd=…)` | Per-run token/cost ledger, no LLM proxy |
+| `tide.runs.create / get / list / recover / subscribe` | Run API + SSE event stream |
+| `tidebase.verify_webhook_signature(body, header, secret)` | Verify signed recovery/channel webhooks |
+
+External writes should declare `side_effects` and an `idempotency_key`; otherwise a final failure is classified `manual_review` instead of silently retrying — that's the [replay contract](https://tidebase.dev/docs/replay-contract-is-it-safe-to-rerun/).
+
+## Tests
+
+Integration tests assert the durability invariants against a real server:
+
+```bash
+docker compose up -d postgres && pnpm server   # in the repo root
+python3 -m unittest discover sdk-python/tests -v
+```
+
+## Status
+
+Alpha, like the rest of Tidebase. The step input hash matches the TypeScript SDK for common JSON types, so both SDKs can drive the same run (caveat: floats like `1.0` hash differently between the two — avoid mixing SDKs on steps whose input contains them).

tidebase-0.5.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+tidebase/__init__.py,sha256=QxmRjJGZlXgpZL_06cLYIBsT_P1IM5c7YZH684tzPKk,28678
+tidebase/aio.py,sha256=AnS5U-aunHYNOMqVyEaZsKtUjvnJKA-a9MkmqGdiDfM,9902
+tidebase-0.5.0.dist-info/METADATA,sha256=0G9XlrCyzqXiR7N-JGtuDFuvEPWPE1Sb9nohoyxls_k,3443
+tidebase-0.5.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tidebase-0.5.0.dist-info/RECORD,,

tidebase-0.5.0.dist-info/WHEEL

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