Python SDK
Write workflows and tasks as plain async Python functions. The engine journals each step, and a run that is interrupted resumes on any worker from the last step it completed.
Installation
1# pip2pip install orcher-sdk34# poetry5poetry add orcher-sdk67# uv8uv add orcher-sdkThe package is orcher-sdk and it imports as orcher. The package named orcher on PyPI is the command-line tool, not the SDK.
Requirements
- Python 3.11 or later (CPython).
- An Orcher engine to connect to. The quickstart starts one on your machine.
- pip installs a prebuilt wheel on macOS (arm64 and x86_64) and Linux (x86_64 and aarch64, glibc or musl). Anywhere else it builds the SDK's native core from source, which needs a Rust toolchain.
The SDK is pre-1.0 (this guide covers orcher-sdk 0.4): its API may change between minor releases, and each breaking change is listed in the changelog.
Quick start
1. Define tasks
A task is an async function decorated with @task. Tasks are where side effects go: calls to other services, database writes, emails. The engine retries a failed task according to its retry policy.
1from datetime import timedelta23from orcher import RetryPolicy, TaskContext, task456@task(7 name="charge-payment",8 retry_policy=RetryPolicy(9 max_attempts=3,10 initial_interval=timedelta(seconds=1),11 backoff_coefficient=2.0,12 ),13)14async def charge_payment(ctx: TaskContext, amount: int, token: str) -> dict:15 # Call your payment provider here, passing an idempotency key.16 # A failure is retried: 3 attempts in all, 1s then 2s apart.17 charge_id = f"ch_{token}_{amount}"18 return {"charge_id": charge_id, "amount": amount, "status": "succeeded"}192021@task(name="reserve-inventory")22async def reserve_inventory(ctx: TaskContext, order_id: str) -> dict:23 # Call your inventory service here.24 return {"reservation_id": f"res_{order_id}"}2. Define a workflow
A workflow is an async function decorated with @workflow. It decides which tasks run and in what order. Its code is replayed from the journal every time it resumes, so it must be deterministic: do I/O in tasks, not in the workflow.
1from orcher import WorkflowContext, workflow23from tasks import charge_payment, reserve_inventory456@workflow(name="process-order", version="1.0", description="Process customer order")7async def process_order(ctx: WorkflowContext, order_id: str, amount: int, token: str) -> dict:8 payment = await ctx.execute_task(charge_payment, amount=amount, token=token)9 inventory = await ctx.execute_task(reserve_inventory, order_id=order_id)1011 return {12 "order_id": order_id,13 "status": "completed",14 "charge_id": payment["charge_id"],15 "reservation_id": inventory["reservation_id"],16 }3. Run a worker
A worker connects to the engine, registers every workflow and task whose module has been imported, and runs them.
1import asyncio2import signal34from orcher import Worker56# Importing the modules registers their @workflow and @task functions.7import workflows # noqa: F4018import tasks # noqa: F40191011async def main() -> None:12 worker = (13 Worker.builder()14 .server_url("http://localhost:50051")15 .namespace("default")16 .task_queue("orders")17 .build()18 )1920 # Drain in-flight work on Ctrl-C or SIGTERM.21 loop = asyncio.get_running_loop()22 for sig in (signal.SIGTERM, signal.SIGINT):23 loop.add_signal_handler(sig, lambda: asyncio.create_task(worker.shutdown()))2425 await worker.run()262728if __name__ == "__main__":29 asyncio.run(main())If the engine requires an API key, set ORCHER_API_KEY in the worker's environment; the builder reads it.
4. Start a workflow
1import asyncio2import os34from orcher import Client, ClientConfig567async def main() -> None:8 config = ClientConfig(9 server_url="http://localhost:50051",10 namespace="default",11 api_key=os.environ.get("ORCHER_API_KEY"), # only if the engine requires one12 )1314 async with Client(config) as client:15 handle = await client.start_workflow(16 "process-order",17 workflow_id="order-123",18 task_queue="orders",19 # A dict reaches the workflow as keyword arguments.20 args=({"order_id": "ord_123", "amount": 9999, "token": "tok_visa"},),21 )2223 print(f"Started workflow: {handle.workflow_id}")24 result = await handle.result(timeout=60.0)25 print("Order completed:", result)262728if __name__ == "__main__":29 asyncio.run(main())Next steps
- Workflows: the
WorkflowContextAPI, determinism and replay - Tasks: retries, heartbeats, cancellation and payload limits
- Client: start, query and manage workflows
- Worker: configuration, authentication and shutdown
- Actors: keyed objects with durable state
- Sessions: run several tasks on one worker
- Testing: run workflows in memory with mocked tasks
- Patterns: compensation, fan-out, approvals and batches