resonate-sdk 0.7.0

Distributed Async Await by Resonate HQ, Inc

Resonate Python SDK

About this component

The Resonate Python SDK enables developers to build reliable and scalable cloud applications across a wide variety of use cases.

• How to contribute to this SDK
• Evaluate Resonate for your next project
• Example application library
• Distributed Async Await — the concepts that power Resonate
• Join the Discord
• Subscribe to the Journal
• Follow on X
• Follow on LinkedIn
• Subscribe on YouTube

Requirements

• Python ≥3.12
• Resonate Server: The Python SDK works with the latest Resonate server (v0.9.x and up).

Quickstart

1. Install the Resonate Server & CLI

brew install resonatehq/tap/resonate

2. Install the Resonate SDK

pip install resonate-sdk

3. Write your first Resonate Function

A countdown as a loop. Simple, but the function can run for minutes, hours, or days, despite restarts.

import asyncio
from datetime import timedelta

from resonate.context import Context
from resonate.resonate import Resonate


async def countdown(ctx: Context, count: int, delay: int) -> None:
    for i in range(count, 0, -1):
        # Run a function durably, awaiting its persisted result
        await ctx.run(ntfy, i)
        # Sleep durably -- the worker holds no state while suspended
        await ctx.sleep(timedelta(seconds=delay))
    print("Done!")


async def ntfy(ctx: Context, i: int) -> None:
    print(f"Countdown: {i}")


async def main() -> None:
    # Connect to the Resonate server and register the functions
    resonate = Resonate(url="http://localhost:8001")
    resonate.register(countdown)
    resonate.register(ntfy)

    try:
        # Invoke with execution id "countdown.1"; run() returns a handle
        # immediately, result() awaits the durable outcome
        handle = resonate.run("countdown.1", countdown, 5, 1)
        await handle.result()
    finally:
        await resonate.stop()


if __name__ == "__main__":
    asyncio.run(main())

4. Start the server

resonate dev

5. Run the worker

python countdown.py

Result

You will see the countdown in the terminal

python countdown.py
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
Done!

What to try

While the function is running, inspect the current state of the execution using the resonate tree command. The tree command visualizes the call graph of the function execution as a graph of durable promises.

resonate tree countdown.1

Now try killing the worker mid-countdown and restarting python countdown.py. Because the invocation id is the same (countdown.1), the worker reattaches to the existing durable promise and the countdown picks up right where it left off without missing a beat.

Examples

The examples/ directory contains runnable programs covering the core patterns. Start a server (resonate dev) on localhost:8001, then run any of them, for example:

uv run python examples/hello-world
uv run python examples/fibonacci --mode rpc --n 10

Example	What it shows
hello-world	A minimal ctx.run / ctx.rpc chain
fibonacci	Recursive durable invocations via run, rpc, or a mix
pipeline	A multi-stage DAG with stages running in parallel
structured-concurrency	The runtime never leaks an unawaited durable child
recovery	Typed serialize/deserialize across the durability boundary
retries	Resonate retrying a flaky leaf function until it succeeds
error-handling	How a failure crosses the boundary and is re-raised
detached	Fire-and-forget invocations decoupled from the parent
human-in-the-loop	Suspending on a promise an external party resolves
polling	Non-blocking progress tracking with handle.done()
rpc	One worker dispatching to another by group
versioning	Running several versions of one function side by side
saga	Compensating completed steps when a later step fails