pgflows 0.1.0__py3-none-any.whl

pgflows-0.1.0.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.3
+Name: pgflows
+Version: 0.1.0
+Summary: Durable workflow engine SDK for Python + Postgres
+Keywords: workflow,durable,postgres,async
+Author: Nir Adler
+Author-email: Nir Adler <me@niradler.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: pydantic
+Requires-Dist: asyncpg
+Requires-Dist: tembo-pgmq-python
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc
+Requires-Dist: fastapi ; extra == 'fastapi'
+Requires-Dist: uvicorn[standard] ; extra == 'fastapi'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/niradler/pyflows
+Project-URL: Repository, https://github.com/niradler/pyflows
+Project-URL: Issues, https://github.com/niradler/pyflows/issues
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# pyflows
+
+[![PyPI](https://img.shields.io/pypi/v/pyflows)](https://pypi.org/project/pyflows/)
+[![Python](https://img.shields.io/pypi/pyversions/pyflows)](https://pypi.org/project/pyflows/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> Durable workflow engine SDK for Python + Postgres
+
+pyflows lets you write long-running, fault-tolerant workflows as plain async Python functions — backed entirely by your existing Postgres database. No extra infrastructure, no separate orchestration service, no new runtime to operate.
+
+> [!WARNING]
+> **Early development (alpha).** The core API is stabilizing but not yet 1.0. Expect breaking changes before the first stable release.
+
+## How it works
+
+Each workflow step is persisted to Postgres before execution. If the process crashes mid-run, the worker replays from the last checkpoint — re-executing only the steps that haven't completed. All state, retries, and scheduling live in the database.
+
+```text
+@workflow fn  →  WorkflowApp.start()
+                     ↓  enqueues to pgmq
+              Python async worker
+                     ↓  executes steps
+              PgStateBackend  ←→  Postgres
+```
+
+## Quick start
+
+```bash
+docker compose up -d   # start Postgres with pgmq
+uv add pyflows
+```
+
+```python
+import asyncio
+from pydantic import BaseModel
+from pyflows import PyflowsConfig, RetryConfig, StepContext, WorkflowApp, WorkflowContext
+
+config = PyflowsConfig(
+    dsn="postgresql://pyflows:pyflows@127.0.0.1:5433/pyflows_test",
+    otel_enabled=False,
+    db_ssl=False,
+)
+app = WorkflowApp(config=config)
+
+
+class OrderInput(BaseModel):
+    order_id: str
+    amount: float
+
+
+class OrderResult(BaseModel):
+    charged: bool
+    confirmation: str
+
+
+@app.step(retry=RetryConfig(max_retries=3, initial_delay_seconds=1.0))
+async def charge_payment(ctx: StepContext, input: OrderInput) -> OrderResult:
+    # call your payment API here
+    return OrderResult(charged=True, confirmation=f"CHG-{input.order_id}")
+
+
+@app.workflow()
+async def process_order(ctx: WorkflowContext, input: OrderInput) -> OrderResult:
+    return await ctx.step(charge_payment, input)
+
+
+async def main() -> None:
+    await app.initialize()
+    instance_id = await app.start(process_order, OrderInput(order_id="ORD-1", amount=99.0))
+    await app.process_once()
+    status = await app.get_status(instance_id)
+    print(status.state, status.output)
+    await app.close()
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Checkpoint replay** — workflows survive crashes; completed steps are never re-executed
+- **Typed end-to-end** — step inputs and outputs are Pydantic models; no `dict[str, Any]` at the boundary
+- **Configurable retries** — per-step `RetryConfig` with exponential or linear backoff and jitter
+- **Plugin hooks** — `before_workflow`, `after_workflow`, `on_workflow_error`, `before_step`, `after_step`, `on_step_error`
+- **Automatic migrations** — `await app.initialize()` applies schema migrations; no manual SQL required
+- **Cron scheduler** — trigger recurring workflows via `PgCronBackend` (backed by pg_durable `df.wait_for_schedule`)
+- **Dead-letter queue** — failed workflows are archived to `pgmq.a_{queue}` instead of being re-queued indefinitely
+- **Worker coordination** — atomic `pending→running` claim prevents duplicate processing when multiple workers race on the same instance
+- **Swappable backends** — orchestrator, queue, and scheduler implement ABCs; swap without touching workflow code
+- **OpenTelemetry** — built-in span management for workflows and steps
+
+## Plugin system
+
+```python
+from pyflows import LoggingPlugin, PyflowsPlugin, StepEvent, WorkflowEvent
+
+# Built-in: log all lifecycle events
+app.register_plugin(LoggingPlugin())
+
+# Custom: implement any subset of hooks
+class MetricsPlugin(PyflowsPlugin):
+    async def after_step(self, event: StepEvent, result: object) -> None:
+        metrics.record("step.completed", tags={"step": event.step_name})
+
+    async def on_workflow_error(self, event: WorkflowEvent, error: Exception) -> None:
+        metrics.record("workflow.failed", tags={"workflow": event.workflow_name})
+
+app.register_plugin(MetricsPlugin())
+```
+
+Plugins are called in registration order. A plugin that raises never affects other plugins or the workflow itself.
+
+## Retry configuration
+
+```python
+from pyflows import RetryConfig
+
+# Per-step retry (backoff can be "exponential" or "linear")
+@app.step(retry=RetryConfig(max_retries=5, initial_delay_seconds=2.0, max_delay_seconds=60.0, backoff="exponential"))
+async def my_step(ctx, input: MyInput) -> MyOutput: ...
+
+# Workflow-level defaults (applied to all steps unless overridden)
+@app.workflow(step_defaults=RetryConfig(max_retries=2))
+async def my_workflow(ctx, input: MyInput) -> MyOutput: ...
+```
+
+## SQL export and runtime workflows
+
+pyflows can export any registered workflow to a [pg_durable](https://github.com/microsoft/pg_durable) SQL DSL. Use this to:
+
+- Transfer workflow definitions from dev → prod without code deployment
+- Create workflows at runtime from config, API payloads, or external systems
+- Inspect the step sequence of any workflow before executing it
+
+### Export a Python workflow to SQL
+
+```python
+from pyflows import SqlExporter
+
+exporter = SqlExporter(registry=app.registry, base_url="http://my-app:8000")
+
+# Full SQL ready to run against a Postgres database with pg_durable
+sql = exporter.export_workflow("process_order")
+
+# Dry-run: inspect steps without producing runnable SQL
+result = exporter.dry_run("process_order")
+print(result.steps)   # [StepSql(step_name='charge_payment', ...)]
+print(result.sql)     # pg_durable DSL
+```
+
+### Compose a workflow at runtime from step names
+
+When you want to define a workflow without writing a Python function — from a config file, an API request, or a database record — use `compose()`. Each step name must already be registered with the app.
+
+```python
+# No Python workflow function needed — compose step sequences dynamically
+sql = exporter.compose(
+    workflow_name="on_call_response",
+    steps=["check_service_health", "diagnose_incident", "apply_remediation"],
+)
+
+# Execute sql against Postgres with pg_durable to start the workflow
+```
+
+The `compose()` call validates that every step name is registered, so typos raise a `KeyError` immediately rather than failing silently at runtime.
+
+### Export all workflows
+
+```python
+# All registered workflows in one SQL file (dev → prod migration)
+sql = exporter.export_all()
+```
+
+## Scheduling
+
+`PgCronBackend` schedules recurring workflows using pg_durable's `df.wait_for_schedule()` — no `pg_cron` extension required, only the `df` extension from [pg_durable](https://github.com/microsoft/pg_durable).
+
+```python
+from pyflows import PgCronBackend
+
+scheduler = PgCronBackend(dsn=config.dsn)
+await scheduler.initialize()
+
+# Schedule a workflow to run every hour (job_id is a pg_durable instance ID string)
+job_id = await scheduler.schedule(
+    job_name="hourly_health_check",
+    cron="0 * * * *",
+    command="SELECT pyflows.enqueue_workflow('health_check', '{}')",
+)
+
+jobs = await scheduler.list_jobs()
+await scheduler.unschedule(job_id)
+```
+
+Check whether pg_durable is installed at runtime:
+
+```python
+await app.initialize()
+if app.pg_durable_available:
+    # scheduler and push-mode SQL export are usable
+    ...
+```
+
+## Backend abstraction
+
+Every infrastructure concern is behind an ABC in `backends/base.py`. Swap backends without touching workflow code:
+
+| Component | Default | Interface |
+| --------- | ------- | --------- |
+| State + checkpoints | `PgStateBackend` | `OrchestratorBackend` |
+| Step queue | `PgmqBackend` | `QueueBackend` |
+| Cron scheduling | `PgCronBackend` | `SchedulerBackend` |
+
+```python
+# Bring your own queue backend
+class RedisQueueBackend(QueueBackend):
+    ...
+
+app = WorkflowApp(config=config)
+# Use custom backend by injecting into WorkflowWorker directly
+```
+
+## Requirements
+
+**Python:** 3.13+
+
+**Postgres extensions** (15+):
+
+| Extension | Purpose | Required |
+| --------- | ------- | -------- |
+| [`pgmq`](https://github.com/tembo-io/pgmq) | Step queue | Yes |
+| [`pg_durable` (`df`)](https://github.com/microsoft/pg_durable) | Cron scheduling, push-mode SQL export | Optional |
+
+The bundled `docker-compose.yml` starts a Postgres instance with `pgmq` pre-installed:
+
+```bash
+docker compose up -d
+```
+
+## Installation
+
+```bash
+pip install pyflows
+# or
+uv add pyflows
+```
+
+## Development
+
+```bash
+uv sync                          # install deps
+uv run pytest tests/unit/        # unit tests (no DB needed)
+docker compose up -d             # start Postgres
+uv run pytest tests/e2e/         # E2E tests
+uv run ruff check src/ tests/    # lint
+```
+
+## AI SRE example
+
+See [`examples/ai_sre/workflow.py`](examples/ai_sre/workflow.py) for a full incident response workflow: health check → AI diagnosis → auto-remediation, with retries, plugin hooks, and typed I/O.
+
+## Roadmap
+
+- [x] M1 — Project scaffold: backend ABCs, Pydantic types, exception hierarchy
+- [x] M2 — Core SDK: `WorkflowApp`, `@step`, `@workflow`, `WorkflowContext`, replay engine
+- [x] M3 — SqlExporter: Python workflow → pg_durable DSL (AST-based)
+- [x] M4 — E2E test suite: basic, retry, monitor/cancel (Docker-based)
+- [x] M6 — Plugin system: `PyflowsPlugin` ABC, `LoggingPlugin`, lifecycle hooks
+- [x] M7 — Migrations + scheduler: versioned schema migrations, `PgCronBackend` via pg_durable
+- [x] M8 — AI SRE example, README, production hardening: DLQ, worker coordination, linear backoff, pg_durable detection
+- [ ] M5 — FastAPI integration: push endpoint (deferred; pull mode works without it)
+- [ ] M9 — PyPI release + full documentation
+
+## License
+
+MIT

pgflows-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+pyflows/__init__.py,sha256=z9Sclcgd5OWyuQsppxZWH2eDwG84cM2qHjxSZu7UnKE,2191
+pyflows/app.py,sha256=iUnC_YfG2Ga7cOI_DHtfvKkJBB6Z6TnyLM4hJgvS9Hk,5902
+pyflows/backends/__init__.py,sha256=pPWf7S-HmjOy4mcTh9uGGoU2h7pFW3x3ELH8nK06szI,157
+pyflows/backends/base.py,sha256=Zl7UHlCE2ubjIphrnXGG1evJt8p4NSDgMVjB6IWkAWw,3292
+pyflows/backends/pg_cron.py,sha256=APXO_lC853mWfo0VE2eRmlMAIdp85DW8WcQKDsqVJB0,3136
+pyflows/backends/pg_durable.py,sha256=bVYcnrK6wDZgS0-u4X07Yd949w-zttQf3MrpSAtlAGM,1642
+pyflows/backends/pg_state.py,sha256=eJl1KDoGMhiayU89PiKRipkVZJRWw9THqcWC8WZQS0A,9913
+pyflows/backends/pgmq.py,sha256=vlLAEPN9eEPmEZ6QNUXWr3XBDbgK4mFkOZpxfJamji8,4400
+pyflows/config.py,sha256=zndsVOAi0MBN30MZbF4KlgHwfF_lCsaXVgQLSVj-X_w,371
+pyflows/context.py,sha256=9ttwWU8IRsATGHSBn4255uAcUmUVXK9NeTIVsPDAS1c,6027
+pyflows/exceptions.py,sha256=ahSRjq5LCdkldkgGMCqRJOCIApXEyZJNUbXcU2cwYLU,1174
+pyflows/logger.py,sha256=6Y0NRBfRIPGlPN3QewlUdReAvTgj4mztWT6nEgqYva8,1052
+pyflows/migrations.py,sha256=iP_jLMakah0MFI4Cys_8NwYj_xgY5vClvhud6XnVRck,3235
+pyflows/plugins.py,sha256=J5QUitkSh4hsMdIo2IdzZHT9JoCYlAXNiFs3dxglq-w,3140
+pyflows/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyflows/registry.py,sha256=-QH59xWBlK2KQCk0yvmhgGbNVmv3kL0nfjVhtmDj60M,3262
+pyflows/schema.sql,sha256=8wqGYgUjgHmgmrrdaF4kkewE5xEdX-ri36R36k5Suvs,1550
+pyflows/sql_exporter.py,sha256=flitEX9_RGw3d_bGHwNYq5a8ADcalyLT-OF2CAHsELM,6175
+pyflows/telemetry.py,sha256=CR0-H1weY3P-j0q5-q8M9dHbWu0tylbkFY1oqnZCbjo,2711
+pyflows/types.py,sha256=Li9EDMo9qdg8HdirXOCcru7Gf_fEWcCt0U7dp7tEtf0,1188
+pyflows/worker.py,sha256=tK2DrYYkZPSWltKbzaUYOELJ0dswfwu2XjxGH04rg9s,4727
+pgflows-0.1.0.dist-info/WHEEL,sha256=jROcLULcdzropX2J55opKw4UHhPFREZax2XzS-Mvpxs,80
+pgflows-0.1.0.dist-info/METADATA,sha256=JCS3If463lRhZmquJggN8S96w9mspXHks2VAl-OLAxs,10778
+pgflows-0.1.0.dist-info/RECORD,,

pgflows-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyflows/__init__.py

@@ -0,0 +1,82 @@
+"""pyflows — durable workflow engine SDK for Python + Postgres."""
+
+from pyflows.app import WorkflowApp
+from pyflows.backends import OrchestratorBackend, QueueBackend, SchedulerBackend
+from pyflows.backends.pg_cron import PgCronBackend
+from pyflows.backends.pg_durable import PgDurableBackend
+from pyflows.backends.pg_state import PgStateBackend
+from pyflows.backends.pgmq import PgmqBackend
+from pyflows.config import PyflowsConfig
+from pyflows.context import StepContext, WorkflowContext
+from pyflows.exceptions import (
+    BackendNotInitializedError,
+    PyflowsError,
+    SchedulerJobNotFoundError,
+    StepExecutionError,
+    WorkflowAlreadyExistsError,
+    WorkflowNotFoundError,
+)
+from pyflows.logger import configure_default_logging, get_logger
+from pyflows.plugins import LoggingPlugin, PyflowsPlugin, StepEvent, WorkflowEvent
+from pyflows.registry import WorkflowRegistry
+from pyflows.sql_exporter import DryRunResult, SqlExporter, StepSql
+from pyflows.telemetry import PyflowsTelemetry
+from pyflows.types import (
+    QueueMessage,
+    RetryConfig,
+    ScheduledJob,
+    StepConfig,
+    WorkflowState,
+    WorkflowStatus,
+)
+from pyflows.worker import WorkflowWorker
+
+__all__ = [
+    # Main entry point
+    "WorkflowApp",
+    # Context
+    "WorkflowContext",
+    "StepContext",
+    # Registry
+    "WorkflowRegistry",
+    # Config + telemetry
+    "PyflowsConfig",
+    "PyflowsTelemetry",
+    # Worker
+    "WorkflowWorker",
+    # SQL exporter
+    "SqlExporter",
+    "DryRunResult",
+    "StepSql",
+    # Plugin system
+    "PyflowsPlugin",
+    "LoggingPlugin",
+    "WorkflowEvent",
+    "StepEvent",
+    # Logger
+    "get_logger",
+    "configure_default_logging",
+    # ABCs
+    "OrchestratorBackend",
+    "QueueBackend",
+    "SchedulerBackend",
+    # Concrete backends
+    "PgCronBackend",
+    "PgDurableBackend",
+    "PgmqBackend",
+    "PgStateBackend",
+    # Types
+    "WorkflowState",
+    "WorkflowStatus",
+    "QueueMessage",
+    "ScheduledJob",
+    "RetryConfig",
+    "StepConfig",
+    # Exceptions
+    "PyflowsError",
+    "WorkflowNotFoundError",
+    "WorkflowAlreadyExistsError",
+    "StepExecutionError",
+    "BackendNotInitializedError",
+    "SchedulerJobNotFoundError",
+]

pyflows/app.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import urllib.parse
+from collections.abc import Callable
+
+from pydantic import BaseModel
+
+from pyflows.backends.pg_state import PgStateBackend
+from pyflows.backends.pgmq import PgmqBackend
+from pyflows.config import PyflowsConfig
+from pyflows.migrations import run_migrations
+from pyflows.plugins import PyflowsPlugin
+from pyflows.registry import WorkflowRegistry
+from pyflows.telemetry import PyflowsTelemetry
+from pyflows.types import RetryConfig, WorkflowState, WorkflowStatus
+from pyflows.worker import WorkflowWorker
+
+
+class WorkflowApp:
+    """Main entry point for the pyflows SDK."""
+
+    def __init__(self, config: PyflowsConfig) -> None:
+        self.config = config
+        self.registry = WorkflowRegistry()
+        self._plugins: list[PyflowsPlugin] = []
+        self._telemetry: PyflowsTelemetry | None = None
+        self._state: PgStateBackend | None = None
+        self._queue: PgmqBackend | None = None
+        self._worker: WorkflowWorker | None = None
+        self._initialized = False
+        self._pg_durable_available: bool = False
+
+    async def initialize(self) -> None:
+        """Apply pending DB migrations, open connection pools, register workflows."""
+        await run_migrations(self.config.dsn, ssl=self.config.db_ssl)
+
+        self._state = PgStateBackend(dsn=self.config.dsn, ssl=self.config.db_ssl)
+        await self._state.initialize()
+
+        for name in self.registry.list_workflows():
+            await self._state.register_workflow(name, config={})
+
+        parsed = urllib.parse.urlparse(self.config.dsn)
+        self._queue = PgmqBackend(
+            host=parsed.hostname or "localhost",
+            port=str(parsed.port or 5432),
+            database=(parsed.path or "/postgres").lstrip("/"),
+            username=parsed.username or "postgres",
+            password=parsed.password or "postgres",
+        )
+        await self._queue.initialize()
+        await self._queue._ensure_queue(self.config.workflow_queue)
+
+        self._telemetry = (
+            PyflowsTelemetry.from_env(self.config.otel_service_name)
+            if self.config.otel_enabled
+            else PyflowsTelemetry.noop()
+        )
+
+        self._pg_durable_available = await self._state.check_extension("df")
+
+        self._worker = WorkflowWorker(
+            registry=self.registry,
+            state_backend=self._state,
+            queue_backend=self._queue,
+            telemetry=self._telemetry,
+            queue_name=self.config.workflow_queue,
+            plugins=self._plugins,
+        )
+        self._initialized = True
+
+    @property
+    def pg_durable_available(self) -> bool:
+        """True if the pg_durable (df) extension is installed in the connected database."""
+        return self._pg_durable_available
+
+    async def start(self, workflow_fn: Callable, input_model: BaseModel) -> str:
+        """Enqueue a workflow run. Returns instance_id."""
+        self._assert_initialized()
+        defn = self.registry.get_workflow(
+            getattr(workflow_fn, "_pyflows_name", workflow_fn.__name__)
+        )
+        input_dict = input_model.model_dump()
+        instance_id = await self._state.create_instance(defn.name, input_dict)  # type: ignore[union-attr]
+        await self._queue.enqueue(  # type: ignore[union-attr]
+            self.config.workflow_queue,
+            {"workflow_name": defn.name, "instance_id": instance_id, "input": input_dict},
+        )
+        return instance_id
+
+    async def get_status(self, instance_id: str) -> WorkflowStatus:
+        self._assert_initialized()
+        return await self._state.get_instance(instance_id)  # type: ignore[union-attr]
+
+    async def list_workflows(
+        self,
+        workflow_name: str | None = None,
+        state: WorkflowState | None = None,
+        limit: int = 100,
+    ) -> list[WorkflowStatus]:
+        self._assert_initialized()
+        return await self._state.list_instances(workflow_name, state, limit)  # type: ignore[union-attr]
+
+    async def cancel(self, instance_id: str) -> None:
+        self._assert_initialized()
+        await self._state.cancel_workflow(instance_id)  # type: ignore[union-attr]
+
+    async def run_worker(self) -> None:
+        """Run the worker loop (blocking). Use asyncio.create_task for background."""
+        self._assert_initialized()
+        await self._worker.run()  # type: ignore[union-attr]
+
+    async def process_once(self) -> int:
+        """Process one batch of pending workflows. Useful for tests."""
+        self._assert_initialized()
+        return await self._worker.process_batch()  # type: ignore[union-attr]
+
+    async def close(self) -> None:
+        if self._worker:
+            self._worker.shutdown()
+        if self._state:
+            await self._state.close()
+        if self._queue:
+            await self._queue.close()
+        self._initialized = False
+
+    def workflow(
+        self,
+        name: str | None = None,
+        step_defaults: RetryConfig | None = None,
+    ) -> Callable:
+        def decorator(fn: Callable) -> Callable:
+            self.registry.register_workflow(fn, name=name, step_defaults=step_defaults)
+            return fn
+
+        return decorator
+
+    def register_plugin(self, plugin: PyflowsPlugin) -> None:
+        """Register a plugin to receive workflow and step lifecycle hooks."""
+        self._plugins.append(plugin)
+
+    def step(
+        self,
+        name: str | None = None,
+        retry: RetryConfig | None = None,
+        timeout_seconds: float | None = None,
+    ) -> Callable:
+        def decorator(fn: Callable) -> Callable:
+            self.registry.register_step(fn, name=name, retry=retry, timeout_seconds=timeout_seconds)
+            return fn
+
+        return decorator
+
+    def _assert_initialized(self) -> None:
+        if not self._initialized:
+            raise RuntimeError("WorkflowApp not initialized — call await app.initialize() first")

pyflows/backends/__init__.py

@@ -0,0 +1,3 @@
+from pyflows.backends.base import OrchestratorBackend, QueueBackend, SchedulerBackend
+
+__all__ = ["OrchestratorBackend", "QueueBackend", "SchedulerBackend"]

pyflows/backends/base.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pyflows.types import QueueMessage, ScheduledJob, WorkflowStatus
+
+
+class OrchestratorBackend(ABC):
+    """Drives durable workflow execution (start, signal, query, cancel)."""
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Set up extensions, schemas, and connection pools."""
+
+    @abstractmethod
+    async def start_workflow(
+        self,
+        workflow_id: str,
+        name: str,
+        payload: dict[str, Any],
+    ) -> str:
+        """Enqueue a new workflow run. Returns the workflow_id."""
+
+    @abstractmethod
+    async def signal_workflow(
+        self,
+        workflow_id: str,
+        signal: str,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Send a signal to a running workflow (e.g. step-completed)."""
+
+    @abstractmethod
+    async def get_workflow_status(self, workflow_id: str) -> WorkflowStatus:
+        """Return the current status of a workflow."""
+
+    @abstractmethod
+    async def cancel_workflow(self, workflow_id: str) -> None:
+        """Request cancellation of a running workflow."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release connections and clean up resources."""
+
+
+class QueueBackend(ABC):
+    """Manages the Python step queue (enqueue, dequeue, ack/nack, listen)."""
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Create queues and install extensions if needed."""
+
+    @abstractmethod
+    async def enqueue(
+        self,
+        queue: str,
+        message: dict[str, Any],
+        delay_seconds: int = 0,
+    ) -> str:
+        """Push a message onto the queue. Returns the message_id."""
+
+    @abstractmethod
+    async def dequeue(self, queue: str, batch_size: int = 1) -> list[QueueMessage]:
+        """Pull up to batch_size messages from the queue."""
+
+    @abstractmethod
+    async def ack(self, queue: str, message_id: str) -> None:
+        """Acknowledge successful processing of a message."""
+
+    @abstractmethod
+    async def nack(self, queue: str, message_id: str) -> None:
+        """Return a message to the queue for redelivery."""
+
+    @abstractmethod
+    async def archive(self, queue: str, message_id: str) -> None:
+        """Move a message to the dead-letter archive (permanently removes from live queue)."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release connections and clean up resources."""
+
+
+class SchedulerBackend(ABC):
+    """Manages recurring workflow triggers via cron scheduling."""
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Install pg_cron extension and create schema if needed."""
+
+    @abstractmethod
+    async def schedule(
+        self,
+        job_name: str,
+        cron: str,
+        command: str,
+    ) -> str:
+        """Register a cron job. Returns the job_id (pg_durable instance_id)."""
+
+    @abstractmethod
+    async def unschedule(self, job_id: str) -> None:
+        """Remove a previously registered cron job."""
+
+    @abstractmethod
+    async def list_jobs(self) -> list[ScheduledJob]:
+        """Return all registered cron jobs."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release connections and clean up resources."""