matrx-graph 0.1.0__tar.gz

matrx_graph-0.1.0/.gitignore

@@ -0,0 +1,271 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template

matrx_graph-0.1.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md — matrx-graph
+
+> **Operating Principle: Build the platform, not the artifact.** Every task is a probe that exposes a missing capability — build it, then consume it. Code that only serves one artifact is forbidden. Full doctrine: [/PRINCIPLES.md](../../PRINCIPLES.md).
+
+**Package:** `matrx-graph` (PyPI) — Python 3.13+ — currently v0.1.0 (alpha)
+**Role in the graph:** Tier 2. Depends on `matrx-utils` and `matrx-connect`. Optionally depends on `matrx-orm` (for Postgres-backed checkpointing). Used by `matrx-ai` and by the aidream app.
+
+---
+
+## Read this first
+
+matrx-graph is the canonical DAG workflow engine for the Matrx family: typed nodes + edges → compiled graph → Pregel-style super-step scheduler → channel-based state + checkpointing + optional human-in-the-loop interrupts. It **replaces** the legacy root-level `workflows/` and `workflows_v2/` directories. Do not add new code there; add it here.
+
+---
+
+## What this package provides
+
+- **Definition types** (`matrx_graph.types`): `Definition`, `NodeDef`, `EdgeDef`, `EdgeKind` (Data / Control / Conditional / Error / Stream), Pydantic input/output/config schemas per node.
+- **Compilation** (`matrx_graph.compile`): `compile_graph(definition)` → `CompiledGraph`, plus `validate_definition()`.
+- **Execution** (`matrx_graph.executor`): `Scheduler`, Pregel super-steps, `asyncio.TaskGroup` parallelism, reducer-based channel writes, `ctx.send(target, payload)` for dynamic routing, `GraphInterrupt` for human-in-the-loop.
+- **Channels** (`matrx_graph.channels` via `ChannelManager`): named typed channels with reducers.
+- **Checkpointing** (`matrx_graph.checkpoint`): `Checkpoint`, `Checkpointer`; in-memory default, Postgres backend via optional matrx-orm dependency.
+- **Node registry** (`matrx_graph.nodes`): `NodeRegistry`, `register_builtin_nodes()`, executors under `nodes/{http,llm,text,data,control,scraper,tool}/`. Host apps register their own executors via `@register("action.name")`.
+- **Node Result System** (`matrx_graph.types.result` + `canonical_payloads` + `value_objects`): every node returns **`NodeResult[T] = Success[T] | Failure`** via `success()`/`failure()`; the **scheduler unwraps** (consumers see bare `T`; `spec.output_schema` stays `T`); payload `T` must not carry `ok`/`success`/`error`; failures route ERROR edges or `on_item_failure='hole'` fan-out holes. Contract: [docs/workflow/NODE_RESULT_CONTRACT.md](../../docs/workflow/NODE_RESULT_CONTRACT.md) · authoring: [docs/node-authoring.md](docs/node-authoring.md).
+- **Kind-declared I/O** (`matrx_graph.kinds`): node I/O is declared as platform kinds (`content_ir.kind_definition` slugs) — `NodeSpec.input_kind`/`output_kind`, per-node `data.*_kind` overrides, scheduler input gate + loud output-drift check, `output_kind` stamped on every `NodeOutcome`. **Every non-dynamic node declares `output_kind`** (generic `"json"` at minimum). Read [docs/node-authoring.md](docs/node-authoring.md) §"Declare your I/O as platform kinds" before adding a node.
+- **Type-contract audit** (`matrx_graph.contracts`): `audit_registry()` walks every registered node's input/output/config schema recursively (versioned `Ruleset`, currently v3: `pydantic.JsonValue` blessed as the dynamic-JSON primitive; inputs excused from `extra="allow"`; justified-forever-open models declare `json_schema_extra={"x-contract-dynamic": "<why>"}` → `dynamic` state) and reports exactly where typing stops (`Any`, bare containers, `extra="allow"`, unknown leaf types) as `full` / `dynamic` / `partial` / `non_conformant` with exact leak paths + shared-model blast radius. Ratchet: `scripts/validate_type_contracts.py` (STRICT in release.sh). Computed live from model classes — never hand-maintained. Served admin-only at aidream `GET /workflow/contracts/audit` → dashboard `/node-contracts`.
+- **Observability** (`matrx_graph.observability`): optional OpenTelemetry integration behind an extra.
+- **Workers** (`matrx_graph.workers`): long-running execution / retry wrappers.
+- **Scheduling**: `croniter`-based cron triggers.
+
+Public API is the ~48 symbols exported from `matrx_graph/__init__.py`. Treat changes there as breaking.
+
+---
+
+## Configuration / injection pattern
+
+- Nodes declare a `config_schema` (Pydantic). Configuration is passed **in the node definition**, not read from env vars inside the executor.
+- Actions referenced by name (e.g. `"action.news_api.top_headlines"`) are resolved from a registry at compile/run time. The host app registers its actions at startup.
+- `AppContext` + `Emitter` from matrx-connect are passed into executors. If matrx-connect isn't installed in a lightweight use case, a console-only emitter fallback is provided — but the preferred path is that consumers have matrx-connect.
+- The graph **engine core** is pure in-memory and needs no database (the default checkpointer is in-memory). But **the moment matrx-graph touches Postgres, it uses matrx-orm — the ONLY DB access path, no exceptions.** `matrx_graph[postgres]` is about whether the DB layer is *installed*, never about whether the ORM may be *bypassed*: there is no non-ORM DB path and no hand-written SQL. `definition_store`, `trigger_store`, `run_store`, `event_store`, and `workers/queue.py` all run on host-injected ORM models — **zero raw `conn.fetch/execute` remains in this package.** Missing ORM capability (advisory locks, `SKIP LOCKED` claim, `LISTEN/NOTIFY`) → **build the primitive in matrx-orm** (celebrate), then convert. Canonical doctrine: [`.claude/skills/eliminate-raw-sql/SKILL.md`](../../.claude/skills/eliminate-raw-sql/SKILL.md).
+- Host DB models/bases/instances (`configure_db(...)`) are injected **declaratively** by the aidream host: what matrx-graph needs is declared in [`matrx_graph/db/db_requirements.py`](matrx_graph/db/db_requirements.py) (data-only manifest in THIS package) and resolved by `python db/generate.py`. Add a `workflow.*` table matrx-graph needs → that manifest, never aidream's `package_integration.py`.
+- **Matrx Envelope `reference` resolution** (`matrx_graph.references`) — graph data may carry a Matrx Envelope reference (a pure pointer to an internal resource: a udt row, a file, a record). The host injects its single `ReferenceOrchestrator` once at startup via `configure_reference_resolver(resolver)`; node code then calls `await resolve_references(payload, user_id=ctx.user_id)` to materialize embedded pointers into live, ownership-gated text. It is deliberately **opt-in** (a deterministic node usually wants the structured ids, not flattened text) and a **no-op passthrough** when unconfigured, so standalone graphs keep working. Detection is the generic protocol sentinel (`matrx_version` + `kind=="reference"`), never an aidream schema import; the injected resolver owns decode + per-type dispatch + the ownership gate. Wired in aidream by `package_integration.py::_configure_matrx_graph`.
+
+See `examples/self_validating_news.py` for the canonical full example.
+
+---
+
+## Dependency rules specific to this package
+
+- ✅ `from matrx_utils import …`, `from matrx_connect import …` — declared hard deps.
+- ✅ `from matrx_orm import …` — inside the DB layer (`matrx_graph/db/`, checkpointer, stores), behind the `[postgres]` extra and guarded so `import matrx_graph` still works for a DB-free in-memory graph. **Every DB access uses it — it is not optional *for code that touches Postgres*, only for installs that have no DB at all.**
+- ❌ No hand-written SQL and no raw `asyncpg` calls in new code (the raw statements left in the stores are debt — do not add to them).
+- ❌ No `from matrx_ai import …` (would be a cycle — matrx-ai depends on matrx-graph).
+- ❌ No `from matrx_scraper import …` at module top level. If a node needs scraping, it should be registered as an external action in the host app or accept a scraper callable via its `config_schema`.
+- ❌ No `from aidream import …`. No imports from root `workflows/`, `workflows_v2/`, `common/`, `config/`, `api_management/`.
+
+If a node type genuinely needs another sibling package, add it as an optional extra in `pyproject.toml` and lazy-import it inside the executor, not at module top.
+
+---
+
+## Python standards (same as root)
+
+- Full type hints. The node/edge/graph types are the public contract — Pydantic with strict validation.
+- No docstrings except on public API (`compile_graph`, `Scheduler`, `NodeDef`, `EdgeDef`, `register`).
+- Hot paths: scheduler step loop, channel reducer application, checkpoint serialization. Keep allocations low; prefer `orjson` / Pydantic v2 fast paths.
+- `GraphInterrupt` is part of the control flow, not an error — catch it in the scheduler, surface it through the emitter. Other exceptions terminate the run with an error event.
+
+---
+
+## Testing this package in isolation
+
+```bash
+uv run pytest packages/matrx-graph/tests
+```
+
+Tests must pass without matrx-orm installed — cover the in-memory checkpointer by default, gate the Postgres checkpointer tests behind an `importlib.util.find_spec("matrx_orm")` check.
+
+---
+
+## Relationship to legacy `workflows/` and `workflows_v2/`
+
+Both root-level directories are **deprecated**. Migration status is tracked in the root `PACKAGES_MIGRATION_PLAN.md`. Rules for the transition:
+
+- Do not add new workflow/node/edge code under `workflows/` or `workflows_v2/`.
+- When a feature in the legacy code is needed, port it into an appropriate `matrx_graph.nodes.*` module with a typed schema.
+- Host-specific actions (things that only make sense inside aidream) live in `aidream/graph_actions/` and are registered into matrx-graph's action registry at startup. They are NOT added to matrx-graph itself.
+
+---
+
+## Known issues
+
+Tracked in root `PACKAGES_MIGRATION_PLAN.md`. This package is currently clean (no known cross-package or root-module imports); the main open work is feature parity with legacy workflow code.

matrx_graph-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: matrx-graph
+Version: 0.1.0
+Summary: Channel-based, super-step workflow orchestration engine for the Matrx ecosystem
+Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
+Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
+Project-URL: Issues, https://github.com/AI-Matrix-Engine/aidream-current/issues
+Author-email: Matrx <admin@aimatrx.com>
+Maintainer-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: agentic,checkpoint,dag,matrx,orchestration,workflow
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: croniter>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: matrx-connect>=0.1.1
+Requires-Dist: matrx-utils>=1.0.20
+Requires-Dist: pydantic>=2.12
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Provides-Extra: postgres
+Requires-Dist: matrx-orm>=3.0.32; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+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`.
+
+## 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. `MemoryCheckpointer` for tests, `PostgresCheckpointer` (via `matrx-graph[postgres]`) for prod.
+- **JSON-only channel values.** Pydantic models are dumped at write. Checkpoints round-trip losslessly.
+- **Typed nodes.** Every `NodeSpec` declares `input_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
+
+```python
+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`](matrx_graph/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](CLAUDE.md) for package-specific rules. This package lives in the aidream monorepo at [github.com/AI-Matrix-Engine/aidream-current](https://github.com/AI-Matrix-Engine/aidream-current/tree/main/packages/matrx-graph).
+
+## License
+
+MIT.

matrx_graph-0.1.0/README.md

@@ -0,0 +1,80 @@
+# 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
+
+```bash
+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`.
+
+## 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. `MemoryCheckpointer` for tests, `PostgresCheckpointer` (via `matrx-graph[postgres]`) for prod.
+- **JSON-only channel values.** Pydantic models are dumped at write. Checkpoints round-trip losslessly.
+- **Typed nodes.** Every `NodeSpec` declares `input_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
+
+```python
+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`](matrx_graph/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](CLAUDE.md) for package-specific rules. This package lives in the aidream monorepo at [github.com/AI-Matrix-Engine/aidream-current](https://github.com/AI-Matrix-Engine/aidream-current/tree/main/packages/matrx-graph).
+
+## License
+
+MIT.