tidebase (Python SDK)

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, without moving execution into a new runtime.

Zero dependencies (stdlib only), Python 3.9+.

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

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.

Tests

Integration tests assert the durability invariants against a real server:

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).