matrx-graph 0.1.0__py3-none-any.whl

matrx_graph/__init__.py

@@ -0,0 +1,236 @@
+"""matrx-graph — channel-based, super-step workflow orchestration engine."""
+
+from matrx_graph.actions import (
+    ActionRegistry,
+    ActionSpec,
+    action,
+    default_action_registry,
+    iter_registered_action_specs,
+    resolve_action_executor,
+)
+from matrx_graph.checkpoint import (
+    Checkpoint,
+    Checkpointer,
+    MemoryCheckpointer,
+    NextInvocation,
+    NodeOutcome,
+    PendingBinding,
+    PendingEdgeBinding,
+)
+from matrx_graph.compile import compile as compile_graph
+from matrx_graph.dry_run import (
+    DryRunEdgeReport,
+    DryRunNodeReport,
+    DryRunReport,
+    DryRunSample,
+    MappingIssue,
+    MissingBinding,
+    dry_run,
+)
+from matrx_graph.errors import (
+    ActionAuthorizationError,
+    ChannelError,
+    CheckpointError,
+    CompilationError,
+    DefinitionError,
+    EdgeRoutingError,
+    ExecutionError,
+    GraphInterrupt,
+    MatrxGraphError,
+    NodeFailureError,
+    NodeInputValidationError,
+    NodeRegistryError,
+    UnresolvedVariableError,
+)
+from matrx_graph.executor import (
+    ChannelManager,
+    Invocation,
+    NodeExecutor,
+    NodeRegistry,
+    RunResult,
+    Scheduler,
+    Send,
+    default_registry,
+    register,
+)
+from matrx_graph.kinds import (
+    KindEntry,
+    get_kind,
+    invalidate_kind_catalog_cache,
+    validate_against_kind,
+)
+from matrx_graph.nodes import register_builtin_nodes
+from matrx_graph.references import (
+    ReferenceResolver,
+    configure_reference_resolver,
+    is_reference_envelope,
+    is_reference_resolver_configured,
+    resolve_references,
+)
+from matrx_graph.types import (
+    ActionTier,
+    BackoffStrategy,
+    ChannelSpec,
+    ChannelView,
+    CompiledEdge,
+    CompiledGraph,
+    CompiledNode,
+    Definition,
+    EdgeDef,
+    EdgeKind,
+    RESERVED_PAYLOAD_FIELDS,
+    ARCHETYPES,
+    BasePayload,
+    BulkItem,
+    BulkResult,
+    EmptyConfig,
+    EmptyInput,
+    EmptyOutput,
+    Failure,
+    HandleDirection,
+    HandleSpec,
+    InterpretedResult,
+    Items,
+    NodeCategory,
+    NodeDef,
+    NodeError,
+    NodeExecutionContext,
+    NodeResult,
+    NodeSpec,
+    OperationResult,
+    Page,
+    Position,
+    Success,
+    Timing,
+    Value,
+    Reducer,
+    RetryPolicy,
+    Run,
+    RunStatus,
+    USLFieldHints,
+    VariableSpec,
+    Viewport,
+    coerce_to_json,
+    field_extras,
+    model_usl_descriptor,
+    failure,
+    interpret_node_result,
+    success,
+    var_ref,
+)
+from matrx_graph.validation import (
+    ValidationIssue,
+    ValidationResult,
+    validate_definition,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ARCHETYPES",
+    "ActionAuthorizationError",
+    "ActionRegistry",
+    "ActionSpec",
+    "ActionTier",
+    "BackoffStrategy",
+    "BasePayload",
+    "BulkItem",
+    "BulkResult",
+    "ChannelError",
+    "ChannelManager",
+    "ChannelSpec",
+    "ChannelView",
+    "Checkpoint",
+    "CheckpointError",
+    "Checkpointer",
+    "CompilationError",
+    "CompiledEdge",
+    "CompiledGraph",
+    "CompiledNode",
+    "Definition",
+    "DefinitionError",
+    "DryRunEdgeReport",
+    "DryRunNodeReport",
+    "DryRunReport",
+    "DryRunSample",
+    "EdgeDef",
+    "EdgeKind",
+    "EdgeRoutingError",
+    "EmptyConfig",
+    "EmptyInput",
+    "EmptyOutput",
+    "ExecutionError",
+    "Failure",
+    "GraphInterrupt",
+    "HandleDirection",
+    "HandleSpec",
+    "InterpretedResult",
+    "Invocation",
+    "Items",
+    "KindEntry",
+    "MappingIssue",
+    "MatrxGraphError",
+    "MemoryCheckpointer",
+    "MissingBinding",
+    "NextInvocation",
+    "NodeCategory",
+    "NodeDef",
+    "NodeError",
+    "NodeExecutionContext",
+    "NodeExecutor",
+    "NodeFailureError",
+    "NodeInputValidationError",
+    "NodeOutcome",
+    "NodeRegistry",
+    "NodeRegistryError",
+    "NodeResult",
+    "NodeSpec",
+    "OperationResult",
+    "Page",
+    "PendingBinding",
+    "PendingEdgeBinding",
+    "Position",
+    "RESERVED_PAYLOAD_FIELDS",
+    "Reducer",
+    "ReferenceResolver",
+    "RetryPolicy",
+    "Run",
+    "RunResult",
+    "RunStatus",
+    "Scheduler",
+    "Send",
+    "Success",
+    "Timing",
+    "USLFieldHints",
+    "UnresolvedVariableError",
+    "Value",
+    "ValidationIssue",
+    "ValidationResult",
+    "VariableSpec",
+    "Viewport",
+    "__version__",
+    "action",
+    "coerce_to_json",
+    "compile_graph",
+    "configure_reference_resolver",
+    "default_action_registry",
+    "default_registry",
+    "dry_run",
+    "failure",
+    "field_extras",
+    "get_kind",
+    "invalidate_kind_catalog_cache",
+    "is_reference_envelope",
+    "interpret_node_result",
+    "is_reference_resolver_configured",
+    "iter_registered_action_specs",
+    "model_usl_descriptor",
+    "register",
+    "register_builtin_nodes",
+    "resolve_action_executor",
+    "resolve_references",
+    "success",
+    "validate_against_kind",
+    "validate_definition",
+    "var_ref",
+]

matrx_graph/actions/ACTION_STANDARDS.md

@@ -0,0 +1,165 @@
+# Action / Node Standards — the contract every `@action` and `NodeExecutor` MUST follow
+
+> Written after an audit found `aidream/graph_actions/web/{brave,google,news}.py` had drifted
+> from the standard the built-in `http.*` nodes (and the in-package `ai.search.brave` action)
+> already establish. Concretely: `brave.py` was silently turning a **search failure**
+> (`async_brave_search` returning `None` on rate-limit/exhaustion/error — see its own comment,
+> "caller MUST treat as a failure, not an empty result set") into a **successful empty result**
+> (`results: []`). `google.py`/`news.py` let raw provider exceptions kill the whole graph run
+> instead of reporting a structured failure. None of the three had a timeout, an `error` field,
+> or `elapsed_ms`. These rules exist so that class of bug cannot ship again, in either direction.
+
+These rules are not style preference — they are the reason `control.branch` /
+`data.transform` can gate on a single field without parsing bodies, the reason a flaky
+third-party API can't take down an entire workflow run, and the reason "it returned nothing"
+and "it broke" stay distinguishable events downstream. **Every new action/node PR is reviewed
+against this list. Every existing one should be brought into compliance opportunistically.**
+
+> **2026-07-08 — the Node Result System supersedes the old per-payload
+> `ok`/`success` booleans.** The contract of record is
+> [docs/workflow/NODE_RESULT_CONTRACT.md](../../../../docs/workflow/NODE_RESULT_CONTRACT.md).
+> Every node returns `NodeResult[T] = Success[T] | Failure`
+> (`matrx_graph.types.result`, via the `success()`/`failure()` factories);
+> the scheduler unwraps it. Rules below marked **(superseded)** describe the
+> pre-envelope convention still present on unmigrated nodes — do NOT copy
+> them into new or migrated code.
+
+Reference implementations to copy from, in order of relevance:
+- [`nodes/http/_shared.py`](../nodes/http/_shared.py) + [`get.py`](../nodes/http/get.py) /
+  [`post.py`](../nodes/http/post.py) / [`graphql.py`](../nodes/http/graphql.py) /
+  [`custom_api.py`](../nodes/http/custom_api.py) — canonical MIGRATED raw
+  `NodeExecutor`s: `NodeResult[HttpResponse]`, transport failure →
+  `failure("http_transport_error", ...)`, retry/timeout guardrails.
+- [`aidream/graph_actions/admin/sql.py`](../../../../aidream/graph_actions/admin/sql.py) —
+  canonical MIGRATED `@action` family: stable failure codes, composition via
+  pass-through of the inner action's `NodeResult`.
+- [`matrx_ai/graph_nodes/llm_action.py`](../../../matrx-ai/matrx_ai/graph_nodes/llm_action.py) +
+  `shared.py::normalize_completed_result` — MIGRATED AI action: failed turn →
+  `Failure("ai_turn_failed")` with billed usage under `error.details.usage`.
+- [`aidream/graph_actions/_shared.py`](../../../../aidream/graph_actions/_shared.py) —
+  `gather_partial` / `run_with_fallback` / `require_any` for multi-item fan-outs.
+
+---
+
+## 1. I/O contract
+
+1. **Pydantic models for every input and every result — success AND failure.** No raw dicts
+   crossing the node boundary, ever.
+2. **Input models default to `ConfigDict(extra="forbid")`.** Unknown keys are almost always a
+   typo or a stale caller — fail loud, not silently. `extra="allow"` is an exception that must
+   be justified in a comment (e.g. `ToolCallInput`/`ToolCallOutput` are deliberately passthrough
+   envelopes; result-item models like `BraveSearchResult` allow extra because the upstream API's
+   shape is loosely specified) — never the default choice out of laziness.
+3. **Return `NodeResult[T]`: `success(payload)` on success, `failure(code, message,
+   details=...)` when the node cannot do its job.** The payload T must NOT carry a
+   top-level `ok`, `success`, or `error` field (reserved — CI-guarded); failure semantics
+   live ONLY in the envelope. `NodeError.code` is a stable snake_case key sharing the
+   `RetryPolicy.retry_on` namespace with exception class names. *(Superseded rule: the
+   old per-payload `ok: bool`/`success: bool` + `error: str|None` convention — present
+   only on unmigrated nodes.)*
+4. **Never let a failure signal from the wrapped function get silently coerced into a
+   "successful empty" result.** If the thing you're calling can return `None`/`{}`/an empty
+   collection to mean *"it broke"* as well as to mean *"it genuinely found nothing,"* you MUST
+   preserve that distinction — return `failure(...)`, never an empty `success(...)`. When in
+   doubt, read the wrapped function's own docstring/comments for exactly this warning
+   (several already document it explicitly).
+5. **Every field gets `Field(..., description=...)`.** The schema is user-facing — it renders in
+   the Studio palette.
+6. **Known nested shapes get their own Pydantic model**, not `dict[str, Any]`. `extra="allow"`
+   on a *result-item* model (e.g. `BraveSearchResult`) is fine when the upstream API's schema is
+   loose but you still want the fields you rely on typed.
+7. **The action must return a `BaseModel` instance**, never a dict — `tool.call` raises
+   `ExecutionError` if it doesn't, and the output must `model_dump(mode="json")` cleanly (no
+   non-JSON-serializable types) since checkpointing and `tool.call`'s field-spreading both
+   depend on it.
+
+## 2. Error handling — the node's job is to never let the run die of surprise
+
+8. **Every call to an external system (HTTP, SDK, subprocess) is wrapped in its own
+   `try/except`.** The `@action` executor boundary does **not** catch for you —
+   `_ActionExecutor.execute` calls `await self._fn(ctx, inputs)` bare. An uncaught exception
+   propagates straight to the scheduler and fails the node/run outright.
+9. **On failure, return `failure(code, message, details=...)` — don't raise** — unless the
+   failure is a genuine authoring/programming error (bad config, an invariant your own code
+   controls). Both paths land in the SAME scheduler ladder (retry → ERROR-edge route /
+   fan-out hole / park), but a returned Failure carries a stable `code` and structured
+   `details` — strictly better for consumers. A failed PAID call puts its usage under
+   `details["usage"]` so cost settlement survives.
+10. **Time the call and report it: `elapsed_ms: int`** (canonical name — the `Timing` value
+    object in `matrx_graph.types.value_objects`). Every built-in `http.*` node does this;
+    it's the first thing you want when debugging a slow/failed run.
+
+## 3. Timeouts & size guardrails
+
+11. **Every network/external call has an explicit, bounded timeout** — never rely on the
+    underlying library's default (which may be "wait forever"). Expose it as a field
+    (`timeout_s`/`timeout`) with `ge=`/`le=` bounds via Pydantic `Field`, and if the wrapped
+    callable doesn't accept a timeout itself, wrap the call in `asyncio.wait_for(...)`.
+12. **Anything that can return an unbounded-size payload caps it** (`max_bytes`/`max_items`/
+    similar, sane default + bounds) — same doctrine as `TOOL_RESULT_SIZE_GATE.md` for LLM tools
+    applies equally here: the action that can return something big owns its own truncation.
+
+## 4. Config vs. business input
+
+13. Where the framework supports a real `config_schema` (raw `NodeExecutor`s), split infra
+    concerns (timeout, retries, max_bytes) from business input (query, url, payload).
+    `@action`-decorated functions don't get a separate config today — timeout-style fields go on
+    the input model instead — but they must still **exist**, not be silently omitted.
+
+## 5. Metadata that must not default-drift
+
+14. **`determinism` must be accurate**, not left at whatever's convenient: `NON_DETERMINISTIC`
+    for anything hitting a live external API/search, `IDEMPOTENT` for side-effect-free GETs,
+    `SIDE_EFFECT` for anything that mutates external state or can double-apply on retry, `PURE`
+    only for actions with zero external I/O.
+15. **`category` set to the real semantic value** (`IO`, `TOOL`, `DATA`, …), never left at the
+    `CUSTOM` default out of not thinking about it.
+16. **`icon` + `tags` set** for palette discoverability; **`description`** on the `@action(...)`
+    call itself, not just on individual fields.
+
+## 6. Signature & registration safety (already enforced at import time — don't fight it)
+
+17. Exact shape: `async def fn(ctx: NodeExecutionContext, inputs: InputModel) -> OutputModel`.
+    The decorator's `_validate_action_signature` already rejects non-async functions and the
+    `(inputs, ctx)` parameter swap at import time — never route around this by decorating a
+    mis-shaped helper.
+18. Unused `ctx`? Discard explicitly with `_ = ctx` — signals "checked, don't need it" instead
+    of "forgot."
+19. Dotted, lowercase, namespaced action name matching `ActionSpec.name`'s pattern
+    (`^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$`, e.g. `web.brave.search`) — never a bare function name.
+20. `admin_only=True` on anything with no built-in ownership/RLS scoping (raw SQL, cross-user
+    reads, filesystem access) — mirrors the `tool_def.admin_only` gate in matrx-ai.
+
+## 7. Fan-out / multi-item actions
+
+21. Multi-item fan-outs use `gather_partial` (never a hand-rolled `asyncio.gather` without
+    `return_exceptions=True`) — **partial success ships**, one item's failure never destroys its
+    siblings' finished work; **total failure raises** via `require_any`. See
+    `aidream/graph_actions/_shared.py` (BS-6 doctrine).
+
+## 8. Testing
+
+22. Every action gets a test on the **failure path**, not just the happy path — assert the
+    return is a `Failure` with the documented `code` when the dependency fails. A
+    structured-error contract nobody tests is worthless — this is exactly how the Brave bug
+    shipped.
+23. Where the dependency is flaky/paid (Brave, SerpAPI, NewsAPI, any billed provider), the
+    failure-path test mocks it to return its documented "I failed" sentinel (e.g. `None`) and
+    asserts the action does **not** report false success.
+
+---
+
+## Enforcement
+
+`scripts/validate_action_standards.py` (repo root, run `--strict` in `release.sh`) walks
+every registered node/action and enforces the Node Result System:
+
+- a MIGRATED node (return annotation `NodeResult[...]`) whose payload T carries a reserved
+  top-level field (`ok`/`success`/`error`) is a **hard failure**;
+- UNMIGRATED nodes are ratcheted against the list in
+  `scripts/node_result_baseline.json` — the list only shrinks
+  (`--update-baseline` after migrating); a NEW pre-envelope node **fails the release**.
+
+The baseline is empty (ratchet zero, 2026-07-09): the legacy bare-BaseModel branch in
+`matrx_graph/types/result.py::interpret_node_result` (and the scheduler) is DELETED — a bare
+payload return is a hard `ExecutionError`/`TypeError` at dispatch, and the guard is fully strict.

matrx_graph/actions/__init__.py

@@ -0,0 +1,36 @@
+"""Actions — typed, registered units of work that become graph nodes.
+
+Author via::
+
+    @action(
+        name="news_api.top_headlines",
+        input_schema=NewsInputs,
+        output_schema=NewsOutputs,
+        determinism=ActionTier.NON_DETERMINISTIC,
+    )
+    async def top_headlines(ctx, inputs: NewsInputs) -> NewsOutputs: ...
+
+Every decorated function is registered in both the node registry (so the
+scheduler can dispatch ``action.<name>``) and the action registry (so the
+Studio palette can list it and ``tool.call`` can resolve it by name).
+"""
+
+from matrx_graph.actions.decorator import (
+    ActionSignatureError,
+    action,
+    iter_registered_action_specs,
+    resolve_action_executor,
+)
+from matrx_graph.actions.registry import ActionRegistry, default_action_registry
+from matrx_graph.actions.spec import ActionSpec, build_action_node_spec
+
+__all__ = [
+    "ActionRegistry",
+    "ActionSignatureError",
+    "ActionSpec",
+    "action",
+    "build_action_node_spec",
+    "default_action_registry",
+    "iter_registered_action_specs",
+    "resolve_action_executor",
+]