agent-workflow-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/.github/workflows/docs.yml

@@ -1,12 +1,18 @@
 name: Docs
 
-# Build the mkdocs site and deploy it to GitHub Pages on a version tag, or on
-# demand from the Actions tab. Enable Pages once (Settings -> Pages -> Source:
-# GitHub Actions) for the deploy step to publish.
+# Build the mkdocs site and deploy it to GitHub Pages when docs change on main,
+# or on demand from the Actions tab. Triggering on main (not a tag) matches the
+# github-pages environment's branch protection, which allows the default branch
+# — a tag push is rejected by that rule. Enable Pages once
+# (Settings -> Pages -> Source: GitHub Actions) for the deploy step to publish.
 on:
   push:
-    tags:
-      - "v*"
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "agentflow/**"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 # Allow one concurrent deploy; a newer run supersedes an in-flight one.

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `agent-workflow-sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project aims to follow [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-10-03
+
+### Added
+
+- Optional HTTP control-plane server (`server` extra): `agentflow.server.
+  create_app(queue)` returns a FastAPI ASGI app that maps 1:1 onto a
+  `RunQueue`, so runs can be enqueued and observed over the network. Routes:
+  `POST /runs`, `GET /runs/{id}`, `GET /runs`, `POST /runs/{id}/resume`,
+  `POST /runs/{id}/cancel`, `GET /stats`, `GET /healthz`. Request/response
+  bodies are Pydantic models, so FastAPI serves interactive OpenAPI docs at
+  `/docs`. `pool_health=` wires a `WorkerPool`'s health into `/healthz`. The
+  app adds no behavior of its own — each route forwards to one queue method.
+  See `examples/serve_control_plane.py` and the control-plane docs.
+- `server` install extra: `pip install 'agent-workflow-sdk[server]'`
+  (`fastapi>=0.110`). The core remains dependency-free; serve the returned
+  ASGI app with any ASGI server (e.g. `uvicorn`), installed separately.
+
+### Changed
+
+- The worker protocol (`claim` / `heartbeat` / `complete`) is deliberately not
+  exposed over HTTP; workers talk to the queue directly. The HTTP layer ships
+  no authentication, authorization, rate limiting, or multi-tenancy — those
+  stay out of scope and are the caller's responsibility (trust boundary /
+  reverse proxy). `DESIGN.md` updated accordingly.
+
 ## [0.3.0] - 2026-10-02
 
 ### Added

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/DESIGN.md

@@ -152,9 +152,11 @@ execution state; a store is cross-thread application data.
 
 ## Control plane
 
-The control plane manages runs from outside the process that created them. It
-is a library layer, not a service — there is no HTTP server (that is planned as
-a thin adapter over these methods).
+The control plane manages runs from outside the process that created them. The
+core is a library layer, not a service. An optional HTTP layer — the `server`
+extra, `agentflow.server.create_app` — is a thin FastAPI adapter mapping 1:1
+over the queue methods below; it adds no behavior of its own, and auth and
+multi-tenancy remain out of scope (see below).
 
 - `GraphRegistry` maps a graph name to a compiled-graph factory. Graphs are
   code and cannot be serialized, so a run request references a graph by name;
@@ -172,6 +174,13 @@ a thin adapter over these methods).
   concurrency.
 - Monitoring: `RunQueue.stats()` and `WorkerPool.health()` return plain values
   a caller can expose through its own `/healthz` and `/metrics`.
+- HTTP (optional, `server` extra): `agentflow.server.create_app(queue)` returns
+  a FastAPI ASGI app exposing the enqueue-and-observe plane — `POST /runs`,
+  `GET /runs/{id}`, `GET /runs`, `POST /runs/{id}/resume`,
+  `POST /runs/{id}/cancel`, `GET /stats`, `GET /healthz`. The worker protocol
+  (`claim` / `heartbeat` / `complete`) is deliberately not exposed; workers
+  talk to the queue directly. Each route forwards to one queue method, so the
+  HTTP layer carries no state of its own.
 
 ## Observability
 
@@ -197,10 +206,11 @@ See `SECURITY.md` for the reporting process and the operator-facing summary.
 
 ## What is intentionally out of scope
 
-- An HTTP/gRPC API over the control plane, and the auth/multi-tenancy that a
-  service layer implies. These are properties of a service, not this SDK, and
-  are deferred to a future `server` layer that adapts the existing queue
-  methods.
+- Authentication, authorization, and multi-tenancy over the HTTP layer. The
+  optional `server` extra adapts the queue to HTTP, but it ships no auth and no
+  per-tenant isolation — those are properties of a service, not this SDK. Run
+  it inside your own trust boundary, or behind a reverse proxy that supplies
+  them. A gRPC API is not provided.
 - Rate limiting and per-tenant quotas. `max_concurrency` /
   `max_node_concurrency` bound pressure within one process; per-tenant
   isolation is the caller's responsibility until the service layer exists.

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows.
 Project-URL: Homepage, https://github.com/dankosorkin/agent-workflow-sdk
 Project-URL: Repository, https://github.com/dankosorkin/agent-workflow-sdk
@@ -20,6 +20,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Provides-Extra: dev
 Requires-Dist: fakeredis>=2.20; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: prometheus-client>=0.20; extra == 'dev'
@@ -41,6 +43,8 @@ Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
 Provides-Extra: redis
 Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
 Description-Content-Type: text/markdown
 
 # agent-workflow-sdk

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/agentflow/__init__.py

@@ -97,7 +97,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",

agent_workflow_sdk-0.4.0/agentflow/server/__init__.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""An HTTP adapter over the control-plane run queue (optional ``server`` extra).
+
+This is the thin service layer DESIGN.md defers to: a FastAPI app that maps 1:1
+onto :class:`~agentflow.controlplane.queue.RunQueue` methods, so a run can be
+enqueued, inspected, resumed, or cancelled over HTTP from anywhere. It adds no
+behavior the queue does not already have.
+
+    from agentflow import PostgresRunQueue
+    from agentflow.server import create_app
+
+    app = create_app(PostgresRunQueue(dsn))   # an ASGI app; serve with uvicorn
+
+What it exposes is the *enqueue and observe* plane: ``POST /runs``, ``GET
+/runs/{id}``, ``GET /runs``, ``POST /runs/{id}/resume``, ``POST
+/runs/{id}/cancel``, ``GET /stats``, ``GET /healthz``. The worker protocol
+(``claim`` / ``heartbeat`` / ``complete``) is deliberately *not* exposed —
+those mutate run state and belong to workers, which talk to the queue directly
+(in-process or via the same Postgres queue), not over this API.
+
+Scope, stated plainly: there is no authentication, authorization, rate
+limiting, or multi-tenancy here — DESIGN.md defers those as properties of a
+service. Run this inside your own trust boundary, or behind a reverse proxy
+that supplies them. It is an adapter, not a hardened public endpoint.
+
+Requires the ``server`` extra: ``pip install 'agent-workflow-sdk[server]'``.
+Serve the returned ASGI app with any ASGI server (e.g. ``uvicorn``), which you
+install separately.
+"""
+
+from agentflow.server.app import create_app
+
+__all__ = ["create_app"]

agent_workflow_sdk-0.4.0/agentflow/server/app.py

@@ -0,0 +1,205 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""FastAPI app factory mapping HTTP routes onto a ``RunQueue``.
+
+Each route is a direct adapter over one queue method; see the package docstring
+for the exposed surface and the explicit non-goals (no auth, no worker
+protocol). Response/request shapes are Pydantic models so the generated OpenAPI
+docs (``/docs``) are accurate.
+
+Note: this module intentionally does NOT use ``from __future__ import
+annotations``. FastAPI resolves endpoint annotations with ``get_type_hints``,
+which cannot re-evaluate a stringized ``Depends(get_queue)`` that references a
+function-local dependency — real annotation objects are required.
+"""
+
+from collections.abc import Callable
+from typing import Annotated, Any
+
+try:
+    from fastapi import Depends, FastAPI, HTTPException, Query
+    from pydantic import BaseModel, Field
+except ModuleNotFoundError as exc:  # pragma: no cover - import-time guard
+    raise ModuleNotFoundError(
+        "agentflow.server requires FastAPI. Install the extra: "
+        "pip install 'agent-workflow-sdk[server]'"
+    ) from exc
+
+from agentflow.controlplane.queue import RunQueue
+from agentflow.controlplane.records import QueueStats, RunRecord
+from agentflow.errors import RunNotFound
+
+__all__ = ["create_app"]
+
+
+# ---------------------------------------------------------------------------
+# Wire models (what crosses the HTTP boundary)
+# ---------------------------------------------------------------------------
+
+
+class EnqueueRequest(BaseModel):
+    """Body for ``POST /runs`` — ask to run a registered graph."""
+
+    graph: str = Field(..., description="Name of a graph registered on the worker side.")
+    input: dict[str, Any] = Field(default_factory=dict, description="Initial state for the run.")
+    thread: str | None = Field(None, description="Checkpoint thread; defaults to the run id.")
+
+
+class ResumeRequest(BaseModel):
+    """Body for ``POST /runs/{run_id}/resume`` — answer an interrupted run."""
+
+    value: Any = Field(None, description="Value fed to the interrupted node on resume.")
+
+
+class RunResponse(BaseModel):
+    """One run's queue record."""
+
+    run_id: str
+    graph: str
+    thread: str
+    status: str
+    input: dict[str, Any] = Field(default_factory=dict)
+    resume_value: Any = None
+    error: str | None = None
+    attempt: int = 0
+    created_at: str = ""
+    updated_at: str = ""
+    lease_until: str | None = None
+    wake_at: str | None = None
+    cancel_requested: bool = False
+
+    @classmethod
+    def of(cls, rec: RunRecord) -> "RunResponse":
+        return cls(
+            run_id=rec.run_id,
+            graph=rec.graph,
+            thread=rec.thread,
+            status=rec.status,
+            input=dict(rec.input),
+            resume_value=rec.resume_value,
+            error=rec.error,
+            attempt=rec.attempt,
+            created_at=rec.created_at,
+            updated_at=rec.updated_at,
+            lease_until=rec.lease_until,
+            wake_at=rec.wake_at,
+            cancel_requested=rec.cancel_requested,
+        )
+
+
+class CancelResponse(BaseModel):
+    cancelled: bool = Field(
+        ..., description="True if the run existed and was not already terminal."
+    )
+
+
+class StatsResponse(BaseModel):
+    total: int = 0
+    by_status: dict[str, int] = Field(default_factory=dict)
+    expired_leases: int = 0
+
+    @classmethod
+    def of(cls, s: QueueStats) -> "StatsResponse":
+        return cls(total=s.total, by_status=dict(s.by_status), expired_leases=s.expired_leases)
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def create_app(
+    queue: RunQueue,
+    *,
+    pool_health: Callable[[], Any] | None = None,
+    title: str = "AgentFlow control plane",
+) -> FastAPI:
+    """Build a FastAPI app over ``queue``.
+
+    ``queue`` is any :class:`~agentflow.controlplane.queue.RunQueue` (Memory for
+    a single process, Postgres for a shared/durable one). ``pool_health``, if
+    given, is a zero-arg callable returning a
+    :class:`~agentflow.controlplane.records.PoolHealth` (typically
+    ``pool.health``); ``GET /healthz`` reports it when present. The app adds no
+    behavior of its own — every route forwards to a queue method.
+    """
+    app = FastAPI(title=title, version="1")
+
+    def get_queue() -> RunQueue:
+        return queue
+
+    # FastAPI dependency injected via the Annotated form (the modern idiom:
+    # keeps Depends() out of the parameter default, so no ruff B008). Inlined in
+    # each signature rather than aliased to a local var, because FastAPI
+    # resolves annotations by name and would not see a function-local alias.
+    @app.post("/runs", response_model=RunResponse, status_code=201, tags=["runs"])
+    async def enqueue_run(
+        body: EnqueueRequest, q: Annotated[RunQueue, Depends(get_queue)]
+    ) -> RunResponse:
+        rec = await q.enqueue(body.graph, body.input, thread=body.thread)
+        return RunResponse.of(rec)
+
+    @app.get("/runs/{run_id}", response_model=RunResponse, tags=["runs"])
+    async def get_run(run_id: str, q: Annotated[RunQueue, Depends(get_queue)]) -> RunResponse:
+        rec = await q.get(run_id)
+        if rec is None:
+            raise HTTPException(status_code=404, detail=f"no run with id {run_id!r}")
+        return RunResponse.of(rec)
+
+    @app.get("/runs", response_model=list[RunResponse], tags=["runs"])
+    async def list_runs(
+        q: Annotated[RunQueue, Depends(get_queue)],
+        status: Annotated[str | None, Query()] = None,
+        graph: Annotated[str | None, Query()] = None,
+        limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+        offset: Annotated[int, Query(ge=0)] = 0,
+    ) -> list[RunResponse]:
+        recs = await q.list(status=status, graph=graph, limit=limit, offset=offset)
+        return [RunResponse.of(r) for r in recs]
+
+    @app.post("/runs/{run_id}/resume", response_model=RunResponse, tags=["runs"])
+    async def resume_run(
+        run_id: str, body: ResumeRequest, q: Annotated[RunQueue, Depends(get_queue)]
+    ) -> RunResponse:
+        try:
+            rec = await q.enqueue_resume(run_id, body.value)
+        except RunNotFound:
+            raise HTTPException(status_code=404, detail=f"no run with id {run_id!r}") from None
+        return RunResponse.of(rec)
+
+    @app.post("/runs/{run_id}/cancel", response_model=CancelResponse, tags=["runs"])
+    async def cancel_run(run_id: str, q: Annotated[RunQueue, Depends(get_queue)]) -> CancelResponse:
+        cancelled = await q.request_cancel(run_id)
+        return CancelResponse(cancelled=cancelled)
+
+    @app.get("/stats", response_model=StatsResponse, tags=["monitoring"])
+    async def get_stats(q: Annotated[RunQueue, Depends(get_queue)]) -> StatsResponse:
+        return StatsResponse.of(await q.stats())
+
+    @app.get("/healthz", tags=["monitoring"])
+    async def healthz() -> dict[str, Any]:
+        body: dict[str, Any] = {"status": "ok"}
+        if pool_health is not None:
+            h = pool_health()
+            body["pool"] = {
+                "workers": h.workers,
+                "alive": h.alive,
+                "busy": h.busy,
+                "idle": h.idle,
+                "healthy": h.healthy,
+            }
+        return body
+
+    return app

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/docs/durability/control-plane.md

@@ -4,7 +4,7 @@
 
 ## What it is, and is not
 
-The control plane is a library layer, not a service. There is no bundled HTTP server, auth, or tenancy — those are properties of a service you build on top, and are deliberately out of scope. What you get is the durable machinery: a queue, a registry, and workers, all as plain objects you drive.
+The control plane is a library layer first. What you get is the durable machinery: a queue, a registry, and workers, all as plain objects you drive. An optional HTTP layer (the `server` extra) wraps the queue so you can drive it over the network — covered at the end of this chapter. There is still no auth or tenancy anywhere in it; those are properties of a service you put in front, and stay out of scope.
 
 ## The pieces
 
@@ -105,6 +105,67 @@ if not health.healthy:
 
 A rising `expired_leases` is the signal that workers are dying or falling behind their heartbeat. `health.healthy` is False when any configured worker loop is not alive — a readiness signal you can expose directly.
 
+## Over HTTP
+
+Everything so far drives the queue from Python. The optional `server` extra wraps the same queue in a FastAPI app, so you can enqueue and observe runs over the network — from a different language, a web UI, or a `curl` in a shell.
+
+```bash
+pip install 'agent-workflow-sdk[server]'
+```
+
+`create_app` takes a `RunQueue` and returns an ASGI app. It adds no behavior of its own; each route forwards to one queue method.
+
+```python
+from agentflow import PostgresRunQueue
+from agentflow.server import create_app
+
+queue = PostgresRunQueue(dsn)
+app = create_app(queue)        # an ASGI app
+```
+
+Serve it with any ASGI server. `uvicorn` is a common choice and you install it yourself:
+
+```bash
+uvicorn myapp:app --port 8000
+```
+
+The routes map 1:1 onto the queue methods from earlier in this chapter:
+
+- `POST /runs` enqueues a run. Body: `{"graph": "...", "input": {...}, "thread": "..."}` (thread optional). Returns `201` with the run record.
+- `GET /runs/{id}` returns one run record, or `404` if there is no such run.
+- `GET /runs` lists runs. Query params: `status`, `graph`, `limit` (1–1000), `offset`.
+- `POST /runs/{id}/resume` re-queues an interrupted run. Body: `{"value": ...}`. `404` if there is no such run.
+- `POST /runs/{id}/cancel` requests cancellation. Returns `{"cancelled": true}` unless the run was unknown or already terminal.
+- `GET /stats` returns the `QueueStats` snapshot (`total`, `by_status`, `expired_leases`).
+- `GET /healthz` returns `{"status": "ok"}`, plus a `pool` block when you pass `pool_health`.
+
+Because the models are typed, FastAPI serves interactive OpenAPI docs at `/docs` and the raw schema at `/openapi.json` with no extra work.
+
+A quick enqueue over HTTP:
+
+```bash
+curl -X POST localhost:8000/runs \
+  -H 'content-type: application/json' \
+  -d '{"graph": "summarize", "input": {"text": "..."}}'
+```
+
+Wire the pool's health into `/healthz` by passing the callable:
+
+```python
+pool = WorkerPool(queue, registry, concurrency=4)
+app = create_app(queue, pool_health=lambda: pool.health())
+```
+
+### What it does not expose
+
+The worker protocol — `claim`, `heartbeat`, `complete` — is deliberately absent from the HTTP surface. Those methods mutate run state and belong to workers, which talk to the queue directly (in-process, or via the same `PostgresRunQueue`), not over this API. The HTTP layer is the enqueue-and-observe plane only.
+
+### Trust boundary
+
+There is no authentication, authorization, rate limiting, or multi-tenancy in this app. It is an adapter over the queue, not a hardened public endpoint. Run it inside your own trust boundary, or behind a reverse proxy or gateway that supplies those. Anyone who can reach it can enqueue, cancel, and resume any run.
+
+See the [HTTP server API reference](../reference/api/server.md) for the request and response models.
+
 ## When to use the control plane
 
 - Use inline `invoke`/`stream` when the run belongs to the calling process — a request handler, a script, a test.

agent_workflow_sdk-0.4.0/docs/reference/api/server.md

@@ -0,0 +1,23 @@
+# HTTP server
+
+The optional FastAPI adapter over a run queue. See the [Control plane over HTTP](../../durability/control-plane.md#over-http) guide.
+
+Requires the `server` extra: `pip install 'agent-workflow-sdk[server]'`.
+
+::: agentflow.server
+    options:
+      members:
+        - create_app
+
+## Wire models
+
+The request and response bodies that cross the HTTP boundary. These are Pydantic models, so they also drive the generated OpenAPI schema served at `/openapi.json` and the interactive docs at `/docs`.
+
+::: agentflow.server.app
+    options:
+      members:
+        - EnqueueRequest
+        - ResumeRequest
+        - RunResponse
+        - CancelResponse
+        - StatsResponse

agent_workflow_sdk-0.4.0/examples/serve_control_plane.py

@@ -0,0 +1,89 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Drive the control plane over HTTP.
+
+Run: python examples/serve_control_plane.py
+Needs the server extra: pip install 'agent-workflow-sdk[server]'
+
+``create_app(queue)`` returns a FastAPI ASGI app that maps 1:1 onto the run
+queue: POST /runs enqueues, GET /runs[/{id}] observes, resume/cancel manage,
+/stats and /healthz monitor. The app adds no behavior of its own — every route
+forwards to one queue method.
+
+To keep this offline and self-contained, it exercises the app through FastAPI's
+TestClient (no socket, no running server). In a real deployment you would skip
+the client and serve the module-level ``app`` with an ASGI server instead:
+
+    uvicorn examples.serve_control_plane:app --port 8000
+
+and a worker (usually a separate process) would drain the same queue. Here the
+queue is a MemoryRunQueue, so there is nothing to actually execute the run — we
+only demonstrate the HTTP surface and the run lifecycle up to "queued".
+"""
+
+from __future__ import annotations
+
+from agentflow import MemoryRunQueue, PoolHealth
+from agentflow.server import create_app
+
+# A module-level ASGI app, so `uvicorn examples.serve_control_plane:app` works.
+# pool_health is optional; here it is a static stand-in for a WorkerPool's
+# health, which /healthz surfaces as a readiness signal.
+queue = MemoryRunQueue()
+app = create_app(queue, pool_health=lambda: PoolHealth(workers=4, alive=4, busy=1))
+
+
+def main() -> None:
+    try:
+        from fastapi.testclient import TestClient
+    except ModuleNotFoundError:
+        raise SystemExit(
+            "this example needs the server extra: pip install 'agent-workflow-sdk[server]'"
+        ) from None
+
+    client = TestClient(app)
+
+    print("POST /runs")
+    created = client.post("/runs", json={"graph": "summarize", "input": {"text": "..."}})
+    run = created.json()
+    print(f"  -> {created.status_code} {run['status']} id={run['run_id']}")
+
+    print("GET /runs/{id}")
+    got = client.get(f"/runs/{run['run_id']}").json()
+    print(f"  -> status={got['status']} graph={got['graph']}")
+
+    print("GET /runs?graph=summarize")
+    listed = client.get("/runs", params={"graph": "summarize"}).json()
+    print(f"  -> {len(listed)} run(s)")
+
+    print("GET /stats")
+    stats = client.get("/stats").json()
+    print(f"  -> total={stats['total']} by_status={stats['by_status']}")
+
+    print("GET /healthz")
+    print(f"  -> {client.get('/healthz').json()}")
+
+    print("POST /runs/{id}/cancel")
+    rid = run["run_id"]
+    cancelled = client.post(f"/runs/{rid}/cancel").json()
+    print(f"  -> cancelled={cancelled['cancelled']}")
+    now = client.get(f"/runs/{rid}").json()["status"]
+    print(f"  -> status now: {now}")
+
+    print("\ninteractive OpenAPI docs would be at /docs; schema at /openapi.json")
+
+
+if __name__ == "__main__":
+    main()

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/mkdocs.yml

@@ -144,6 +144,7 @@ nav:
           - Checkpointing: reference/api/checkpoint.md
           - Store: reference/api/store.md
           - Control plane: reference/api/controlplane.md
+          - HTTP server: reference/api/server.md
           - Observability: reference/api/observability.md
           - Prebuilt patterns: reference/api/prebuilt.md
           - Quality gates: reference/api/gate.md

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-workflow-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,6 +31,7 @@ otel = ["opentelemetry-api>=1.20", "opentelemetry-sdk>=1.20"]
 redis = ["redis>=5"]
 postgres = ["asyncpg>=0.29"]
 prometheus = ["prometheus-client>=0.20"]
+server = ["fastapi>=0.110"]
 docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.26"]
 dev = [
     "pytest>=8",
@@ -41,6 +42,8 @@ dev = [
     "pip-audit>=2.7",
     "fakeredis>=2.20",
     "prometheus-client>=0.20",
+    "fastapi>=0.110",
+    "httpx>=0.27",
 ]
 
 [project.urls]

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.4.0}/tests/test_otel.py

@@ -21,8 +21,10 @@ from typing import Annotated
 import pytest
 from agentflow import END, START, Graph, State, add
 
-# Skip the whole module if the otel extra isn't installed.
-otel = pytest.importorskip("opentelemetry")
+# Skip the whole module if the otel extra isn't installed. Guard on
+# opentelemetry.sdk, not the bare opentelemetry namespace: the API package can
+# be present transitively while the SDK (the otel extra) is not.
+otel = pytest.importorskip("opentelemetry.sdk")
 
 from agentflow.otel import OtelHooks  # noqa: E402
 from opentelemetry.sdk.trace import TracerProvider  # noqa: E402