Skip to main content

roomkit-graph

A workflow graph engine for Python. A workflow is a directed graph of nodes and edges, stored as plain data (JSON); the engine walks it step by step, routes on serializable conditions, pauses on steps that wait for a person, and resumes later, in the same process or another one.

The engine does the walking. The steps that do real work — calling an AI agent, asking a person, sending a notification — run through handlers: your own, or those of roomkit_graph.roomkit, which run them with RoomKit agents and rooms. The engine has no runtime dependencies.

Install

pip install roomkit-graph              # the engine alone
pip install "roomkit-graph[roomkit]"   # with the RoomKit handlers

What the engine does, what you bring

roomkit-graph provides Your application provides
Graph model, validation, JSON round-trip Handlers for agent, human, notification, orchestration and any custom node type — or RoomKit's for the first three
Condition DSL for edge routing, also serializable Where trigger data comes from: webhooks, schedules and events are descriptions, the engine fires nothing
{{...}} templates over previous step outputs Where the engine state is stored between a pause and a resume
Step-by-step execution, pause and resume Real delays, retries and timeouts
State serialization (to_dict / from_dict)
Streaming of execution events
Built-in start, end, function, condition, switch, log, parallel nodes

Quick start

Two handlers stand in for an AI agent and a notifier; the graph routes on what the first one returns.

import asyncio

from roomkit_graph import (
    Condition, Edge, Graph, Node, NodeHandler, NodeResult, WebhookTrigger, WorkflowEngine,
)


class TriageHandler(NodeHandler):
    """Stands in for an AI agent: replace the body with your model call."""

    async def execute(self, node, context, engine):
        prompt = engine.template_resolver.resolve(node.config["prompt"])
        severity = "critical" if "down" in prompt.lower() else "low"
        return NodeResult(output={"severity": severity})


class NotifyHandler(NodeHandler):
    """Stands in for Slack, email or SMS: replace the body with your sender."""

    async def execute(self, node, context, engine):
        message = engine.template_resolver.resolve(node.config["template"])
        print(f"[notify] {message}")
        return NodeResult(output={"sent": message})


graph = Graph(id="bug-triage", name="Bug Triage", trigger=WebhookTrigger(source_type="github"))
graph.add_nodes(
    Node("start", type="start"),
    Node("triage", type="agent", config={"prompt": "Classify: {{trigger.title}}"}),
    Node("page", type="notification", config={"template": "Critical: {{trigger.title}}"}),
    Node("end", type="end"),
)
graph.add_edges(
    Edge("start", "triage"),
    Edge("triage", "page", condition=Condition.field("input.severity").equals("critical")),
    Edge("triage", "end", condition=Condition.otherwise()),
    Edge("page", "end"),
)
graph.validate_or_raise()


async def main():
    engine = WorkflowEngine(
        graph, handlers={"agent": TriageHandler(), "notification": NotifyHandler()}
    )
    context = await engine.run(trigger_data={"title": "Checkout is down"})
    print(context.get("triage.output.severity"))  # critical


asyncio.run(main())

The graph is data: graph.to_dict() gives JSON you can store, version or edit in a UI, and Graph.from_dict(...) reads it back.

Node types

Type Built in What it does
start yes Entry point. The trigger data is its output
end yes Completes the run
function yes set_context, json_transform, delay, custom — see Function nodes
condition yes Evaluates one condition, outputs {"result": bool}. A missing or invalid condition gives False
switch yes Reads a context path, outputs {"value": ...} for outgoing edges to match
log yes Copies context paths into its output, for inspection
parallel yes Runs its child nodes concurrently — see Parallel nodes
agent no Yours: run an AI agent
orchestration no Yours: run several agents together
human no Yours: ask a person, usually returning waiting
notification no Yours: send a message and continue

Any other string is a valid node type as long as a handler is registered for it. A node whose type has no handler fails the run with ExecutionError.

Writing a handler

A handler implements one method and returns a NodeResult:

class MyHandler(NodeHandler):
    async def execute(self, node, context, engine) -> NodeResult:
        ...
  • node.config holds the node's settings from the graph.
  • engine.template_resolver.resolve(text) fills {{...}} templates from the context.
  • NodeResult.output is stored as the node's output, readable by later steps.
  • NodeResult.status is "completed" (default, the engine moves on), "waiting" (the run pauses on this node) or "failed" (the run stops with ExecutionError, carrying NodeResult.error).

Handlers are passed per engine and override the built-in ones for the same type: WorkflowEngine(graph, handlers={"agent": MyHandler()}).

Context and templates

Each node's output is stored under <node_id>.output. Templates and conditions read it with dot paths:

{{triage.output.severity}}       # a field of a previous step's output
{{start.output.input.title}}     # the trigger data, long form

Three reserved prefixes shorten the common reads:

Prefix Reads
trigger.<path> The trigger data (trigger.title)
steps.<id>.<path> A node's output without the output hop (steps.triage.severity)
input.<path> In a node's templates: the output of the node the run came from — the branch taken at a merge, what sent the run back in a loop. In a node's outgoing edge conditions: that node's own output

A node named trigger, steps or input is shadowed by these prefixes.

A path that is not there raises TemplateError. When it may legitimately be missing — a step on the other branch, a loop's first pass — default(...) names what stands in for it, as a JSON value:

{{steps.page.text | default("not paged")}}
{{input.feedback | default("none yet")}}
{{steps.count.total | default(0)}}

resolve() always returns a string. resolve_value() keeps the type when the template is exactly one placeholder: "{{triage.output.tags}}" returns the list, "Tags: {{triage.output.tags}}" returns a string.

Edges and conditions

Condition.field("triage.output.severity").equals("critical")
Condition.field("triage.output.severity").not_equals("low")
Condition.field("extract.output.amount").gt(1000)          # also .lt()
Condition.field("extract.output.tags").contains("urgent")
Condition.field("extract.output.status").in_(["approved", "accepted"])  # also .not_in()
Condition.field("review.output.manager").exists()

Condition.all_(cond_a, cond_b)
Condition.any_(cond_a, cond_b)
Condition.not_(cond_a)
Condition.otherwise()

When a node has several outgoing edges, the engine picks, in this order:

  1. the first conditional edge, in definition order, whose condition is true;
  2. otherwise the edge with no condition;
  3. otherwise the Condition.otherwise() edge.

If none applies, the run stops with NoValidTransitionError. A node other than end with no outgoing edge completes the run.

Edges may point back to an earlier node (a revise → review loop). The engine has no iteration limit; a loop ends when a condition sends the run elsewhere.

Conditions serialize with the graph:

{"type": "field", "path": "triage.output.severity", "op": "eq", "value": "critical"}
{"type": "all", "conditions": [
    {"type": "field", "path": "extract.output.amount", "op": "gt", "value": 1000},
    {"type": "field", "path": "extract.output.category", "op": "eq", "value": "travel"}
]}
{"type": "otherwise"}

Pause and resume

A handler that returns status="waiting" pauses the run on its node. The engine state serializes to JSON, so the answer can arrive hours later in another process:

class ApprovalHandler(NodeHandler):
    """Asks a person, then pauses: the answer comes back through resume()."""

    async def execute(self, node, context, engine):
        send_question(engine.template_resolver.resolve(node.config["question"]))
        return NodeResult(status="waiting")


engine = WorkflowEngine(graph, handlers=handlers)
await engine.run(trigger_data={"amount": 120})
engine.waiting                    # True: paused on engine.current_node_id, "approve"
save(engine.to_dict())            # {"context": {...}, "current_node_id": ..., "waiting": True}

# Later, possibly in another process
engine = WorkflowEngine.from_dict(graph, load(), handlers=handlers)
await engine.resume("approve", {"action": "approve"})
while await engine.step():
    pass

resume(node_id, data) stores data as the waiting node's output and moves to the next node; edges leaving the waiting node route on it (Condition.field("approve.output.action").equals("approve")).

engine.start() then engine.step() run one node at a time; engine.run() is both, until the run completes or pauses.

Seeing what a run does

verbose() prints every run's progress on stderr as it happens — each step, each agent's turn with its duration, tokens and tools, each message sent, each pause:

from roomkit_graph import verbose

verbose()                 # content=False hides prompts, answers and message texts
[research-crew bec462ed] ▶ research (agent)
[research-crew bec462ed]   researcher · Senior research analyst · working…
[research-crew bec462ed]   asked: Research AI agents in customer support. List the ten most…
[research-crew bec462ed]   researcher answered · 12.8 s · 84 → 1,596 tokens
[research-crew bec462ed]   answer: **AI agents in customer support: ten things that matter** 1…
[research-crew bec462ed] ✓ research · 13.8 s
[support-triage b3da3aaf] ⏸ page · waiting for an answer

verbose(messages=True) prints each agent's text as the agent writes it, instead of its answer cut to one line, a ✎ line per line of text:

[research-crew d5c72753]   researcher · Senior research analyst · working…
[research-crew d5c72753]   ✎ **AI agents in customer support: ten things that matter**
[research-crew d5c72753]   ✎ 1. **Fact: Assistive AI has the best evidence.** A large NBER study…

It reads the TEXT_DELTA ephemerals RoomKit publishes in a delegated task's child room, for an agent that asks for it; for another agent, no text arrives and nothing else changes:

kit.register_channel(Agent("writer", provider=provider, publish_text_deltas=True))

RoomKit 0.110.0, which roomkit-graph requires, publishes that text only for a delegated task's trace: the text of an answer a BEFORE_BROADCAST hook blocks or redacts never reaches a subscriber. On 0.109.0 the flag published the text of every turn of the agent, that answer's included.

Each line names its graph and run (engine.run_id), so runs that interleave stay apart. The roomkit_graph logger then prints there only; close() on the handler verbose() returns gives it back.

The same records go to the roomkit_graph loggers for your own handlers: steps, durations and pauses at INFO, a failed node at WARNING. What a person or a model wrote — a prompt, an answer, a message — is logged at DEBUG only. Each record carries its fields in record.roomkit_graph (event, run, graph, node, and the event's own: seconds, tokens_in, tools...).

Streaming execution events

engine.stream() yields typed events as the run progresses — for dashboards, webhooks or audit logs. Pick one or more modes:

Mode Emitted when Payload
values Before start and after each step Full context snapshot
updates After each step Outputs written that step, keyed by node id
lifecycle Before and after each node {phase, node_id, status} (status: completed / waiting / failed)
custom When a handler calls engine.emit(...) Handler-defined payload
async for event in engine.stream(trigger_data, modes=("updates", "lifecycle")):
    if event["mode"] == "lifecycle" and event["payload"]["phase"] == "start":
        print(f"→ {event['node_id']}")
    elif event["mode"] == "updates":
        await websocket.send_json(event["payload"])

A handler reports progress inside its node with engine.emit(payload); outside stream() the call does nothing, so the same handler works in both modes.

When a handler fails, a last lifecycle event with status="failed" is yielded before ExecutionError propagates. When a node waits, the stream ends; after resume(...), start a new stream().

Parallel nodes

A parallel node runs the nodes that name it as parent, concurrently, and continues once all of them are done:

graph.add_nodes(
    Node("checks", type="parallel"),
    Node("security", type="agent", config={...}, parent="checks"),
    Node("compliance", type="agent", config={...}, parent="checks"),
    Node("summarize", type="agent", config={...}),
)
graph.add_edges(Edge("analyze", "checks"), Edge("checks", "summarize"))

# After the parallel node:
#   security.output    → that child's output
#   checks.output      → {"security": ..., "compliance": ...}

Children are run by their parallel node only: give them no edges. If one child fails, the parallel node fails. A child cannot pause: waiting inside a parallel node is a failure. Waiting for the first child only (join: "any") is not implemented.

Function nodes

# Write fixed values as the node's output
Node("tag", type="function", config={
    "action": "set_context", "values": {"status": "in_progress"},
})

# Build a structure from templates (types kept for single placeholders)
Node("reshape", type="function", config={
    "action": "json_transform",
    "template": {"name": "{{extract.output.first}} {{extract.output.last}}"},
})

# Call your own function by name
Node("prioritize", type="function", config={
    "action": "custom", "function": "calculate_priority",
})

custom functions are looked up in graph_registry:

from roomkit_graph import graph_registry


@graph_registry.function("calculate_priority")
async def calculate_priority(context, config):
    return {"priority": "P1" if context.get("trigger.tier") == "enterprise" else "P2"}

To keep a set of functions apart — per tenant, per test — pass your own registry instead: handlers={"function": FunctionHandler(registry=FunctionRegistry())}.

The built-in delay action does not wait: it outputs {"delayed": "<duration>"}. A real delay — usually a pause the application resumes later — belongs in your own handler.

Triggers

WebhookTrigger, ScheduledTrigger, EventTrigger and ManualTrigger describe how a workflow is meant to start, and serialize with the graph. The engine does not listen to anything: your application reads graph.trigger, receives the webhook or runs the schedule, and calls engine.run(trigger_data=...).

Validation

graph.validate() returns a list of errors (empty when valid); graph.validate_or_raise() raises GraphValidationError. It checks: exactly one start node, at least one end node, edges pointing to existing nodes, no edge into start, no edge out of an end, every node reachable from start.

With RoomKit

roomkit_graph.roomkit (pip install "roomkit-graph[roomkit]") runs nodes with RoomKit. Every run works in a room, named by its trigger data's room_id:

Node Config What happens
agent agent, prompt, optional structured, room The RoomKit agent works on the prompt in a child room of the run's room; the output is {"text": ...}, or with structured the agent's submit_result call ({"status", "summary", "data", ...})
notification text, optional room The text is written into the room in the application's name, so its transports deliver it — an SMS to the room's correspondent — and none of its agents answers it
human text, optional room Sent the same way, then the run pauses until the answer arrives in that room
from roomkit_graph.roomkit import RoomRuns, room_handlers

runs = RoomRuns()
engine = WorkflowEngine(graph, handlers=room_handlers(kit))
await runs.start(engine, {"room_id": room.id, "topic": "..."})

# Where your app receives a message (an SMS webhook, say):
result = await kit.process_inbound(message)
await runs.answer(result.event.room_id, {"text": message.content.body})

Resume from what people send, as above: a hook that sees every message of the room also sees the workflow's own questions, which come from the host channel (event.source.channel_type == ChannelType.HOST).

RoomRuns.answer() resumes the run paused on that room, if any; when several wait there, the one that asked first. It holds paused runs in memory; to survive a restart, store engine.to_dict() and rebuild with WorkflowEngine.from_dict().

The workflow writes in a room as the application, with RoomKit's kit.post(): the room's transports deliver its messages, they solicit none of the room's agents, and each one's metadata names the graph, run and node that sent it ({"workflow": {"graph": ..., "run": ..., "node": ...}}). A room a Discussion runs takes them like any other.

A host that serves several organizations names the one a run acts for in its trigger data's organization_id. Each room the run reaches is checked against it, as RoomKit checks a caller's organization_id: an agent, notification or human node aimed at another organization's room raises RoomNotFoundError, and nothing is asked or sent.

await runs.start(engine, {"room_id": room.id, "organization_id": "acme"})

Examples

Runnable examples are in examples/:

uv run python examples/graph_definition.py   # build, validate, serialize
uv run python examples/workflow_engine.py    # conditions, templates, execution
uv run python examples/streaming.py          # the four stream modes and emit()

# With RoomKit agents: uv sync --extra examples, and ANTHROPIC_API_KEY set
uv run python examples/research_crew.py "AI agents in customer support"
uv run python examples/support_triage.py     # SMS in, page the on-call, SMS out
uv run python examples/review_loop.py        # draft, editor's feedback by SMS, until OK
uv run python examples/order_desk.py         # agents with their own tools and a skill

Status

Alpha. The API may change between minor versions until 1.0; breaking changes are listed in the changelog.

License

MIT

Metadata

Release files for roomkit-graph 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for roomkit-graph 0.4.1
File Size Uploaded Provenance Actions
roomkit_graph-0.4.1.tar.gz 55.7 kB Without provenance Details for roomkit_graph-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for roomkit-graph 0.4.1
File Interpreter ABI Platform Actions
roomkit_graph-0.4.1-py3-none-any.whl Python 3 none any Details for roomkit_graph-0.4.1-py3-none-any.whl

Total release size: 97.4 kB

Release files / roomkit_graph-0.4.1.tar.gz

Download URL roomkit_graph-0.4.1.tar.gz
Size 55.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b10fb668820bfdc93c5c4aa35405c57af52f6aeb11fd01bb9f3dcc77cd8c6068
BLAKE2b-256 checksum
How to use checksums
b4213e811c5f195e429e54ca9a1eb3fd5e48d23040e60b5ad913214fd9b89e01
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / roomkit_graph-0.4.1-py3-none-any.whl

Download URL roomkit_graph-0.4.1-py3-none-any.whl
Size 41.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6f64f314636caa962b35b4464f0f23e38c016e9971eaadb1176b71f871891876
BLAKE2b-256 checksum
How to use checksums
16e7d5ededc15d9b8f6068793b19e815ad60915a056cce9947c76326e1255688
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for roomkit-graph 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page