odysseys-py 0.0.3

Distributed durable execution engine and orchestrator
built on PostgreSQL.

What is Odyssey?

Odyssey is a PostgreSQL-native distributed durable execution engine and orchestrator.

It turns PostgreSQL into the coordination layer for distributed work, providing persistent execution state, ownership, fencing, and recovery without requiring a separate workflow infrastructure stack.

Applications define what should execute. Odyssey manages the durable execution of that work across services and failures.

Why Odyssey?

Distributed applications are built from processes and services that can fail independently. A function can finish after its caller disappears, a worker can crash halfway through an operation, or two workers can attempt to execute the same work.

Making this work reliable typically requires a dedicated orchestration system, durable state store, and coordination layer.

Odyssey takes a different approach:

Use PostgreSQL as the durable coordination layer.

If your application already runs on PostgreSQL, Odyssey lets you build durable workflows around the database you already operate.

How It Works

Odyssey turns application functions into durable executions.

1. Register your functions

Register the functions Odyssey is allowed to execute.

from odyssey import Odyssey

client = Odyssey()

client.register(target="payments",fn=charge_card, ttl_ms=10000)
client.register(target="notifications",fn=send_confirmation, ttl_ms=9000)

Each registered function represents an executable step in a workflow. the target is the stable name used to identify that function during execution. Together, the registered targets form Odyssey's function registry.

2. Define your workflow

from odyssey import Odyssey, Step

client = Odyssey()

steps = [
    Step(
        target="payments",
        amount=100,
        currency="USD",
    ),
    Step(
        target="reserve_items",
        delegate="inventory",
        product_id="prod_123",
        quantity=2,
    ),
    Step(
        target="notifications",
        user = "USR_U7rq6",
    ),
]

ledger = client.build_ledger(
    key="order_123",
    steps=steps,
)

Each Step represents an executable unit of the workflow and is executed in order.

• target identifies the function the step executes.
• delegate identifies a service configured in odyssey.yaml where the step should execute.
• Without a delegate, the step is treated as local and the target must exist in the local function registry.
• Additional keyword arguments become the step's execution input.

Every execution is uniquely identified by the (key, target) pair. A workflow can contain many different targets under the same key, and the same target can be used under different keys, but the same (key, target) pair cannot be defined more than once.

3. Configure your services

Odyssey uses odyssey.yaml to define services that can receive delegated execution.

services:
  payments: http://localhost:9001
  inventory: http://localhost:9002
  notifications: http://localhost:9003

registry:
  default:
    retry:
      policy: forever
      delay: 2s

  inventory:
    retry:
      policy: forever
      delay: 2s
    
  payments:
    retry:
      policy: fixed
      attempts: 5
      delay: 4s

The registry section defines execution policies for registered targets, including retry behavior.

Step(
    target="reserve_items",
    delegate="inventory",
    product_id="prod_123",
    quantity=2,
)

When no delegate is provided, Odyssey treats the step as a local execution and resolves the target against the local function registry. This allows the same workflow definition to contain both local and delegated execution.

A workflow can therefore begin entirely locally and introduce delegated steps as functionality is extracted into independent services.

...

What Odyssey manages

Once a workflow is defined, Odyssey manages the execution lifecycle and durability of each step.

• Durable execution state — execution state is persisted in PostgreSQL.
• Execution ownership — workers acquire ownership before executing a step.
• Fencing — stale workers are prevented from completing executions they no longer own.
• Recovery — unfinished executions can be picked up after a worker or process failure.
• Inputs and results — execution inputs and results are persisted with the execution state.
• Execution timeouts — each registered target can define a TTL for its execution ownership.
• Local execution — steps can execute directly against the local function registry.
• Delegated execution — steps can be sent to another configured service.
• Execution identity — (key, target) uniquely identifies an execution within a workflow. ...

SDKs

Odyssey currently provides SDKs for:

• Python
• Go
• TypeScript [planned]

Project Status

Odyssey is currently in early development.

The core execution engine, PostgreSQL coordination layer, and Python and Go SDKs are available. APIs and execution semantics may continue to evolve.

License

Odyssey is licensed under the MIT License.