resonate.Resonate

Create a Resonate client.

Begin remote execution of a registered function through Resonate.

This method initiates a remote execution on a Resonate worker and returns a Handle that can be used to track progress, await completion, or retrieve the result later. If a durable promise with the same id already exists, Resonate will reuse the existing execution state or subscribe to its result instead of starting a new one. This ensures consistent, idempotent, and fault-tolerant behavior in distributed environments.

Resonate guarantees that duplicate remote executions for the same id are prevented.

handle = resonate.begin_rpc("job-987", process_data, records)
# Do other work...
result = handle.result()

handle = resonate.begin_rpc("job-987", "aggregate_metrics", dataset)

result = await resonate.begin_rpc("job-987", "aggregate_metrics", dataset)

Begin execution of a registered function through Resonate.

This method starts the execution of a registered function and returns a Handle that can be used to track progress, await completion, or retrieve results later. If a durable promise with the same id already exists, Resonate will reuse the existing execution state or subscribe to its result rather than starting a new run. This ensures idempotent and fault-tolerant execution across distributed systems.

Resonate guarantees that duplicate executions for the same id are prevented.

handle = resonate.begin_run("job-123", process_data, records)
# Do other work...
result = handle.result()

handle = resonate.begin_run("job-123", "aggregate_metrics", dataset)

result = await resonate.begin_run("job-123", "aggregate_metrics", dataset)

Retrieve or subscribe to an existing execution by ID.

This method attaches to an existing durable promise identified by id. If the associated execution is still in progress, it returns a Handle that can be used to await or observe its completion. If the execution has already completed, the handle is resolved immediately with the stored result.

handle = resonate.get("job-42")
result = handle.result()

handle = resonate.get("job-42")
result = await handle

Configure options for the function.

• encoder: Configure your own data encoder.

• idempotency_key: Define the idempotency key invocation or a function that

  receives the promise id and creates an idempotency key.

• retry_policy: Define the retry policy: exponential | constant | linear | never
• tags: Add custom tags to the durable promise representing the invocation.
• target: Target to distribute the invocation.
• timeout: Number of seconds before the invocation timesout.
• version: Version of the function to invoke.

Register a function with Resonate for execution and version control.

This method makes a function available for top-level execution under a specific name and version. It can be used either directly by passing the target function, or as a decorator for more concise registration.

When used as a decorator without arguments, the function is registered automatically using its own name and the default version. Providing explicit name or version values allows precise control over function identification and versioning for repeatable, distributed invocation.

def greet(ctx: Context, name: str) -> str:
    return f"Hello, {name}!"

resonate.register(greet, name="greet_user", version=2)

@resonate.register(name="process_data", version=2)
def process(ctx: Context, data: dict) -> dict:
    ...

Execute a registered function remotely through Resonate and waits for its result.

This method invokes a registered function on a remote Resonate worker and blocks until the result is available. If a durable promise with the same id already exists, Resonate will reuse the existing execution or subscribe to its completion instead of executing it again, ensuring idempotent and consistent remote execution.

Resonate guarantees that duplicate remote executions for the same id are prevented.

result = resonate.rpc("remote-task-7", my_function, data)

result = resonate.rpc("remote-task-7", "process_order", order_id)

Run a registered function through Resonate and waits for its result.

This method executes a registered function by its identifier or reference and returns the computed result. If a durable promise with the same id already exists, Resonate will reuse the existing result or subscribe to its completion rather than executing the function again. This ensures idempotent and deterministic behavior across distributed executions.

Resonate guarantees that duplicate executions for the same id are prevented.

result = resonate.run("task-42", my_function, 10, flag=True)

result = resonate.run("task-42", "process_data", records)

Register a named dependency for use within function execution contexts.

Registers a dependency object that will be made available to all registered functions through their Context. Dependencies are typically shared resources such as database clients, configuration objects, or service interfaces that functions can access during execution.

client.set_dependency("db", DatabaseClient())

@client.register()
def fetch_user(ctx: Context, user_id: str):
    db = ctx.dependencies["db"]
    return db.get_user(user_id)

Explicitly start Resonate threads.

This happens automatically when calling .run() or .rpc(), but is generally recommended for all workers that have functions registered with Resonate.

Stop resonate.