matrx-graph
Channel-based, super-step workflow orchestration engine for the Matrx ecosystem. Think of it as a typed DAG + Pregel scheduler designed for mixing deterministic nodes with agent-style nodes in the same graph, with durable checkpoints and optional human-in-the-loop interrupts.
Install
pip install matrx-graph # core engine, in-memory checkpointer
pip install "matrx-graph[postgres]" # + durable Postgres checkpointer (via matrx-orm)
pip install "matrx-graph[otel]" # + OpenTelemetry instrumentation
Python 3.13+ required. Depends on matrx-connect (for AppContext and Emitter), matrx-utils, pydantic.
For standalone Postgres, apply
matrx_graph/db/migrations/0100_baseline_post_reorg.sql, register the database
with matrx-orm, then call
matrx_graph.db.configure_standalone_db("<registered-name>"). Aidream hosts use
their generated package wiring instead.
Design pillars
- Channels + reducers, not mutable state. Nodes return partial updates; a reducer merges them into typed channels. Safe under parallel writes.
- Pregel super-steps. Each step: active nodes run in parallel via
asyncio.TaskGroup→ writes reduced into state → next wave scheduled. Predictable and debuggable. - Durable checkpoints. Every super-step produces a checkpoint. Resume, fork, or time-travel from any point.
MemoryCheckpointerfor tests,PostgresCheckpointer(viamatrx-graph[postgres]) for prod. - JSON-only channel values. Pydantic models are dumped at write. Checkpoints round-trip losslessly.
- Typed nodes. Every
NodeSpecdeclaresinput_schema,output_schema,config_schema(Pydantic). JSON Schema is auto-exported for UI form generation. - Explicit edge semantics. Data / Control / Conditional / Error / Stream edges — no guessing from topology.
- Interrupts + Send. First-class primitives for human-in-the-loop pauses and dynamic fanout.
Design principle
Choose where to be deterministic and where to delegate to an agent.
A workflow can do everything an agent can (branch, loop, dispatch tools) but is more predictable, debuggable, and cheaper. An agent can do everything a workflow can but adapts to unexpected input. matrx-graph exists so authors draw that line consciously per node.
Usage sketch
from matrx_graph import (
Definition, NodeDef, EdgeDef, EdgeKind,
compile_graph, Scheduler, register, register_builtin_nodes,
)
register_builtin_nodes()
# A custom action — registered once, referenced by name in node definitions
@register("greet")
async def greet(ctx, inputs, config):
return {"message": f"Hello, {inputs['name']}!"}
definition = Definition(
nodes=[
NodeDef(id="start", action="noop"),
NodeDef(id="greet", action="greet"),
],
edges=[
EdgeDef(source="start", target="greet", kind=EdgeKind.Data),
],
)
graph = compile_graph(definition)
scheduler = Scheduler(graph)
result = await scheduler.run(inputs={"name": "world"})
print(result.channels["greet"]) # {"message": "Hello, world!"}
For a full example including conditional edges, dynamic ctx.send(...) fanout, checkpoints, and resume, see examples/self_validating_news.py.
Dependency posture
matrx-graph is a generic engine. It depends only on matrx-connect, matrx-utils, and pydantic. Optional postgres extra adds matrx-orm for durable checkpointing.
Domain-specific node packs (LLM, agent, scraper) live in their sibling packages (matrx-ai, matrx-scraper) and register executors with the engine at runtime via matrx_graph.registry. No hard import cycles.
Status
Phase 1 in progress — foundation + in-process executor. Not yet production-ready. The legacy root-level workflows/ and workflows_v2/ directories in the monorepo are being consolidated into this package.
Contributing
See CLAUDE.md for package-specific rules. This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.
License
MIT.
1 maintainer
Release files for matrx-graph 0.2.181
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrx_graph-0.2.181.tar.gz | 973.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrx_graph-0.2.181-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / matrx_graph-0.2.181.tar.gz
| Download URL | matrx_graph-0.2.181.tar.gz |
|---|---|
| Size | 973.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0a02fbc8c4763e49d986e65f56cac070e3ee26b0f7de450429e6c513efa392f8
|
|
BLAKE2b-256 checksum How to use checksums |
59b5a0c4972cda920bba8a453ea5ee82776121e1931c7ea0b3681d10e83c3673
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / matrx_graph-0.2.181-py3-none-any.whl
| Download URL | matrx_graph-0.2.181-py3-none-any.whl |
|---|---|
| Size | 716.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd515ccf209610bcd2a54d85a2035be42687da6d39f5233513309c1ddcccb356
|
|
BLAKE2b-256 checksum How to use checksums |
7afdc7daf259da4e96760552165ca85416476fa6424c3dee5aa8a83127e2a298
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
