dr-graph 0.1.0__py3-none-any.whl

dr_graph/__init__.py

@@ -0,0 +1,82 @@
+"""Hashable computation-graph configs and a pure deterministic interpreter."""
+
+from dr_graph.builders import as_node_input_source_ref, graph, node
+from dr_graph.compose import inline_subgraph
+from dr_graph.definition import GraphDefinition, NodeDefinition
+from dr_graph.errors import (
+    CompletedNodeError,
+    GraphExecutionError,
+    GraphValidationError,
+    InputResolutionError,
+    NodeExecutionError,
+)
+from dr_graph.execution import (
+    RunNode,
+    execute_graph,
+    resolve_node_inputs,
+)
+from dr_graph.hashing import (
+    GRAPH_CONFIG_IDENTITY_SCHEMA,
+    GRAPH_CONFIG_IDENTITY_SCHEMA_VERSION,
+    graph_config_identity_document,
+    graph_config_identity_payload,
+    graph_hash,
+)
+from dr_graph.refs import (
+    NodeInputSourceKind,
+    NodeInputSourceRef,
+)
+from dr_graph.results import (
+    ClassifiedFailure,
+    GraphRunResult,
+    GraphRunStatus,
+    NodeError,
+    NodeOutcome,
+    NodeOutcomeStatus,
+    NodeOutput,
+    TerminalError,
+)
+from dr_graph.spec import (
+    FieldRole,
+    GraphConfig,
+    NodeConfig,
+    NodeFieldSpec,
+)
+from dr_graph.validation import validate_graph_external_inputs
+
+__all__ = [
+    "GRAPH_CONFIG_IDENTITY_SCHEMA",
+    "GRAPH_CONFIG_IDENTITY_SCHEMA_VERSION",
+    "ClassifiedFailure",
+    "CompletedNodeError",
+    "FieldRole",
+    "GraphConfig",
+    "GraphDefinition",
+    "GraphExecutionError",
+    "GraphRunResult",
+    "GraphRunStatus",
+    "GraphValidationError",
+    "InputResolutionError",
+    "NodeConfig",
+    "NodeDefinition",
+    "NodeError",
+    "NodeExecutionError",
+    "NodeFieldSpec",
+    "NodeInputSourceKind",
+    "NodeInputSourceRef",
+    "NodeOutcome",
+    "NodeOutcomeStatus",
+    "NodeOutput",
+    "RunNode",
+    "TerminalError",
+    "as_node_input_source_ref",
+    "execute_graph",
+    "graph",
+    "graph_config_identity_document",
+    "graph_config_identity_payload",
+    "graph_hash",
+    "inline_subgraph",
+    "node",
+    "resolve_node_inputs",
+    "validate_graph_external_inputs",
+]

dr_graph/builders.py

@@ -0,0 +1,70 @@
+"""Neutral config-assembly helpers.
+
+These cover the common case — node input sources, one declared output field,
+open Variable assignments — without any prompt or provider awareness.
+Domain-aware builders belong app-side.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+from dr_graph.refs import NodeInputSourceRef
+from dr_graph.spec import FieldRole, GraphConfig, NodeConfig, NodeFieldSpec
+
+
+def as_node_input_source_ref(
+    ref: str | NodeInputSourceRef,
+) -> NodeInputSourceRef:
+    if isinstance(ref, NodeInputSourceRef):
+        return ref
+    return NodeInputSourceRef.model_validate(ref)
+
+
+def node(  # noqa: PLR0913 -- the config surface, not incidental knobs
+    node_id: str,
+    *,
+    node_type: str,
+    output_field: str,
+    input_sources: Mapping[str, str | NodeInputSourceRef] | None = None,
+    fields: Sequence[NodeFieldSpec] | None = None,
+    variables: Mapping[str, Any] | None = None,
+) -> NodeConfig:
+    sources = {
+        name: as_node_input_source_ref(ref)
+        for name, ref in (input_sources or {}).items()
+    }
+    if fields is None:
+        derived = [
+            NodeFieldSpec(name=name, role=FieldRole.INPUT) for name in sources
+        ]
+        derived.append(NodeFieldSpec(name=output_field, role=FieldRole.OUTPUT))
+        field_specs = tuple(derived)
+    else:
+        field_specs = tuple(fields)
+    return NodeConfig.model_validate(
+        {
+            "node_id": node_id,
+            "node_type": node_type,
+            "fields": field_specs,
+            "input_sources": sources,
+            "output_field": output_field,
+            "variables": dict(variables or {}),
+        }
+    )
+
+
+def graph(
+    nodes: Sequence[NodeConfig],
+    *,
+    terminal: str,
+) -> GraphConfig:
+    return GraphConfig.model_validate(
+        {
+            "nodes": tuple(nodes),
+            "terminal_node_id": terminal,
+        }
+    )

dr_graph/compose.py

@@ -0,0 +1,109 @@
+"""Inline subgraph composition.
+
+v1 represents composition by flattening: `inline_subgraph` returns the
+subgraph's nodes renamed under a prefix, with internal input sources rewired
+and external inputs optionally rebound to parent-side sources. The composed
+graph is an ordinary `GraphConfig`; its `graph_hash` is the hash of the
+flattened config.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dr_graph.builders import as_node_input_source_ref
+from dr_graph.refs import (
+    REF_SEPARATOR,
+    NodeInputSourceKind,
+    NodeInputSourceRef,
+)
+from dr_graph.spec import GraphConfig, NodeConfig
+from dr_graph.validation import external_input_fields
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+DEFAULT_SUBGRAPH_SEPARATOR = ":"
+
+
+def prefixed_node_id(
+    prefix: str,
+    node_id: str,
+    *,
+    separator: str = DEFAULT_SUBGRAPH_SEPARATOR,
+) -> str:
+    return f"{prefix}{separator}{node_id}"
+
+
+def inline_subgraph(
+    subgraph: GraphConfig,
+    *,
+    prefix: str,
+    input_sources: Mapping[str, str | NodeInputSourceRef] | None = None,
+    separator: str = DEFAULT_SUBGRAPH_SEPARATOR,
+) -> tuple[NodeConfig, ...]:
+    """Return the subgraph's nodes renamed and rewired for a parent graph.
+
+    ``input_sources`` maps external input fields of the subgraph to parent-side
+    sources (parent node outputs or parent external inputs). Unmapped external
+    inputs pass through unchanged and must be satisfied by the parent graph's
+    external inputs.
+    """
+    if not prefix:
+        raise ValueError("prefix must be non-empty")
+    if REF_SEPARATOR in prefix:
+        raise ValueError(f"prefix {prefix!r} cannot contain {REF_SEPARATOR!r}")
+    if not separator or REF_SEPARATOR in separator:
+        raise ValueError(
+            f"separator {separator!r} must be non-empty and cannot "
+            f"contain {REF_SEPARATOR!r}"
+        )
+    remapped = {
+        name: as_node_input_source_ref(ref)
+        for name, ref in (input_sources or {}).items()
+    }
+    unknown = sorted(set(remapped) - external_input_fields(subgraph))
+    if unknown:
+        unknown_list = ", ".join(repr(name) for name in unknown)
+        raise ValueError(
+            f"input source(s) {unknown_list} are not external inputs "
+            "of the subgraph"
+        )
+    nodes: list[NodeConfig] = []
+    for node in subgraph.nodes:
+        node_input_sources: dict[str, NodeInputSourceRef] = {}
+        for field_name, ref in node.input_sources.items():
+            if ref.kind is NodeInputSourceKind.GRAPH_EXTERNAL:
+                if ref.field is not None and ref.field in remapped:
+                    node_input_sources[field_name] = remapped[ref.field]
+                else:
+                    node_input_sources[field_name] = ref
+                continue
+            node_input_sources[field_name] = NodeInputSourceRef.model_validate(
+                {
+                    "kind": NodeInputSourceKind.NODE_OUTPUT,
+                    "node_id": prefixed_node_id(
+                        prefix,
+                        str(ref.node_id),
+                        separator=separator,
+                    ),
+                    "field": ref.field,
+                }
+            )
+        nodes.append(
+            NodeConfig.model_validate(
+                {
+                    "node_id": prefixed_node_id(
+                        prefix,
+                        node.node_id,
+                        separator=separator,
+                    ),
+                    "node_type": node.node_type,
+                    "fields": node.fields,
+                    "input_sources": node_input_sources,
+                    "output_field": node.output_field,
+                    "variables": dict(node.variables),
+                }
+            )
+        )
+    return tuple(nodes)

dr_graph/definition.py

@@ -0,0 +1,166 @@
+"""Versioned, variable-bearing Graph Definition artifact.
+
+A Graph Definition declares the Node Definitions, Variables, DAG shape,
+input/output contracts, and exactly one terminal Node. It materializes one
+or more fully-set Graph Configs by binding concrete Variable assignments to
+each declared Node.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictInt,
+    StrictStr,
+    model_validator,
+)
+
+from dr_graph.errors import GraphValidationError
+from dr_graph.refs import NodeInputSourceRef, validate_ref_identifier
+from dr_graph.spec import (
+    GraphConfig,
+    NodeConfig,
+    NodeFieldSpec,
+    validate_node_fields,
+)
+from dr_graph.validation import (
+    topological_order_ids,
+    validate_single_terminal_ids,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class NodeDefinition(BaseModel):
+    """Declares one Node's Definition, DAG wiring, and required Variables.
+
+    ``variable_names`` are the declared Variables a Graph Config must set for
+    this Node; ``input_sources`` fix the DAG shape and input contract;
+    ``fields`` and ``output_field`` declare the input/output contract.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    node_id: StrictStr
+    node_type: StrictStr = Field(min_length=1)
+    fields: tuple[NodeFieldSpec, ...] = ()
+    input_sources: dict[str, NodeInputSourceRef] = Field(default_factory=dict)
+    output_field: StrictStr
+    variable_names: frozenset[str] = frozenset()
+
+    def dependencies(self) -> set[str]:
+        return {
+            node_id
+            for ref in self.input_sources.values()
+            if (node_id := ref.dependency_node_id) is not None
+        }
+
+    @model_validator(mode="after")
+    def validate_definition(self) -> NodeDefinition:
+        validate_ref_identifier(self.node_id, kind="node id")
+        validate_node_fields(
+            self.fields,
+            self.input_sources,
+            self.output_field,
+        )
+        return self
+
+
+class GraphDefinition(BaseModel):
+    """Versioned, variable-bearing DAG shape materializing Graph Configs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: StrictInt = 1
+    nodes: tuple[NodeDefinition, ...]
+    terminal_node_id: StrictStr
+
+    def node_ids(self) -> list[str]:
+        return [node.node_id for node in self.nodes]
+
+    @model_validator(mode="after")
+    def validate_definition(self) -> GraphDefinition:
+        if not self.nodes:
+            raise GraphValidationError(
+                "graph definition must have at least one node"
+            )
+        node_ids = self.node_ids()
+        if len(node_ids) != len(set(node_ids)):
+            raise GraphValidationError("duplicate node ids")
+        known = set(node_ids)
+        if self.terminal_node_id not in known:
+            raise GraphValidationError(
+                f"terminal_node_id {self.terminal_node_id!r} not in "
+                "graph definition"
+            )
+        dependencies = {
+            node.node_id: node.dependencies() for node in self.nodes
+        }
+        for node_id, deps in dependencies.items():
+            unknown = sorted(deps - known)
+            if unknown:
+                joined = ", ".join(repr(dep) for dep in unknown)
+                raise GraphValidationError(
+                    f"node {node_id!r} depends on unknown node(s) {joined}"
+                )
+        # Enforce acyclicity and exactly one terminal/sink at Definition level.
+        topological_order_ids(node_ids, dependencies)
+        validate_single_terminal_ids(
+            node_ids,
+            dependencies,
+            terminal_node_id=self.terminal_node_id,
+        )
+        return self
+
+    def materialize(
+        self,
+        variable_assignments: Mapping[str, Mapping[str, Any]] | None = None,
+    ) -> GraphConfig:
+        """Materialize one fully-set Graph Config.
+
+        ``variable_assignments`` maps each ``node_id`` to that Node's concrete
+        Variable values. Every declared Variable for every Node must be set.
+        """
+        assignments = variable_assignments or {}
+        unknown = sorted(set(assignments) - set(self.node_ids()))
+        if unknown:
+            joined = ", ".join(repr(node_id) for node_id in unknown)
+            raise ValueError(
+                f"variable assignment(s) {joined} reference unknown node id(s)"
+            )
+        nodes: list[NodeConfig] = []
+        for definition in self.nodes:
+            values = dict(assignments.get(definition.node_id, {}))
+            missing = sorted(definition.variable_names - set(values))
+            if missing:
+                joined = ", ".join(repr(name) for name in missing)
+                raise ValueError(
+                    f"node {definition.node_id!r} is missing required "
+                    f"variable assignment(s) {joined}"
+                )
+            extra = sorted(set(values) - definition.variable_names)
+            if extra:
+                joined = ", ".join(repr(name) for name in extra)
+                raise ValueError(
+                    f"node {definition.node_id!r} sets undeclared "
+                    f"variable(s) {joined}"
+                )
+            nodes.append(
+                NodeConfig(
+                    node_id=definition.node_id,
+                    node_type=definition.node_type,
+                    fields=definition.fields,
+                    input_sources=dict(definition.input_sources),
+                    output_field=definition.output_field,
+                    variables=values,
+                )
+            )
+        return GraphConfig(
+            nodes=tuple(nodes),
+            terminal_node_id=self.terminal_node_id,
+        )

dr_graph/errors.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+class GraphExecutionError(Exception):
+    """Base exception for pure graph execution errors."""
+
+
+class GraphValidationError(GraphExecutionError, ValueError):
+    pass
+
+
+class InputResolutionError(GraphExecutionError):
+    pass
+
+
+class NodeExecutionError(GraphExecutionError):
+    pass
+
+
+class CompletedNodeError(GraphExecutionError):
+    """Raised when a supplied completed-node output cannot be used."""

dr_graph/execution.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from pydantic import ValidationError
+
+from dr_graph.errors import (
+    CompletedNodeError,
+    InputResolutionError,
+    NodeExecutionError,
+)
+from dr_graph.hashing import graph_hash
+from dr_graph.refs import NodeInputSourceKind
+from dr_graph.results import (
+    GraphRunResult,
+    GraphRunStatus,
+    NodeOutcome,
+    NodeOutcomeStatus,
+    NodeOutput,
+    TerminalError,
+)
+from dr_graph.spec import GraphConfig, NodeConfig
+
+type RunNode = Callable[
+    [NodeConfig, Mapping[str, Any]],
+    NodeOutput | Mapping[str, Any],
+]
+
+
+def execute_graph(
+    *,
+    graph: GraphConfig,
+    inputs: Mapping[str, Any],
+    run_node: RunNode,
+    completed: Mapping[str, NodeOutput | Mapping[str, Any]] | None = None,
+) -> GraphRunResult:
+    computed_graph_hash = graph_hash(graph)
+    completed_outputs = _validated_completed_outputs(
+        graph=graph,
+        completed=completed,
+    )
+    outcomes: dict[str, NodeOutcome] = {}
+    execution_order: list[str] = []
+
+    for node in graph.topological_order():
+        execution_order.append(node.node_id)
+        if node.node_id in completed_outputs:
+            outcomes[node.node_id] = NodeOutcome.success(
+                node_id=node.node_id,
+                output=completed_outputs[node.node_id],
+            )
+            continue
+        blocked_by = _blocked_dependencies(node, outcomes)
+        if blocked_by:
+            outcomes[node.node_id] = NodeOutcome.blocked(
+                node_id=node.node_id,
+                blocked_by=blocked_by,
+            )
+            continue
+
+        try:
+            node_inputs = resolve_node_inputs(
+                node=node,
+                inputs=inputs,
+                outcomes=outcomes,
+                graph=graph,
+            )
+            output = _run_node(
+                node=node,
+                node_inputs=node_inputs,
+                run_node=run_node,
+            )
+        except Exception as error:  # noqa: BLE001 -- outcomes absorb node failures
+            outcomes[node.node_id] = NodeOutcome.from_error(
+                node_id=node.node_id,
+                error=error,
+            )
+            continue
+
+        outcomes[node.node_id] = NodeOutcome.success(
+            node_id=node.node_id,
+            output=output,
+        )
+
+    return _build_result(
+        graph=graph,
+        outcomes=outcomes,
+        execution_order=tuple(execution_order),
+        inputs=inputs,
+        graph_hash_value=computed_graph_hash,
+    )
+
+
+def resolve_node_inputs(
+    *,
+    node: NodeConfig,
+    inputs: Mapping[str, Any],
+    outcomes: Mapping[str, NodeOutcome],
+    graph: GraphConfig,
+) -> dict[str, Any]:
+    resolved: dict[str, Any] = {}
+    for field_name, ref in node.input_sources.items():
+        if ref.kind is NodeInputSourceKind.GRAPH_EXTERNAL:
+            if ref.field is None or ref.field not in inputs:
+                raise InputResolutionError(
+                    f"missing external input {ref.field!r} "
+                    f"for node {node.node_id!r}"
+                )
+            resolved[field_name] = inputs[ref.field]
+            continue
+
+        if ref.node_id is None:
+            raise InputResolutionError(
+                f"node input source {ref.ref!r} has no node id"
+            )
+        upstream = outcomes.get(ref.node_id)
+        if (
+            upstream is None
+            or upstream.status is not NodeOutcomeStatus.SUCCESS
+        ):
+            raise InputResolutionError(
+                f"upstream node {ref.node_id!r} did not succeed"
+            )
+        if upstream.output is None:
+            raise InputResolutionError(
+                f"upstream node {ref.node_id!r} has no output"
+            )
+        output_field = ref.field or graph.node(ref.node_id).output_field
+        if output_field not in upstream.output.values:
+            raise InputResolutionError(
+                f"upstream node {ref.node_id!r} output missing "
+                f"field {output_field!r}"
+            )
+        resolved[field_name] = upstream.output.values[output_field]
+    return resolved
+
+
+def _validated_completed_outputs(
+    *,
+    graph: GraphConfig,
+    completed: Mapping[str, NodeOutput | Mapping[str, Any]] | None,
+) -> dict[str, NodeOutput]:
+    if not completed:
+        return {}
+    node_ids = set(graph.node_ids())
+    outputs: dict[str, NodeOutput] = {}
+    for node_id, raw_output in completed.items():
+        if node_id not in node_ids:
+            raise CompletedNodeError(
+                f"completed node {node_id!r} is not in the graph"
+            )
+        try:
+            output = NodeOutput.model_validate(raw_output)
+        except ValidationError as error:
+            raise CompletedNodeError(
+                f"completed output for node {node_id!r} is invalid: {error}"
+            ) from error
+        output_field = graph.node(node_id).output_field
+        if output_field not in output.values:
+            raise CompletedNodeError(
+                f"completed output for node {node_id!r} missing "
+                f"field {output_field!r}"
+            )
+        outputs[node_id] = output
+    return outputs
+
+
+def _run_node(
+    *,
+    node: NodeConfig,
+    node_inputs: Mapping[str, Any],
+    run_node: RunNode,
+) -> NodeOutput:
+    output = NodeOutput.model_validate(run_node(node, node_inputs))
+    if node.output_field not in output.values:
+        raise NodeExecutionError(
+            f"node {node.node_id!r} output missing field {node.output_field!r}"
+        )
+    return output
+
+
+def _blocked_dependencies(
+    node: NodeConfig,
+    outcomes: Mapping[str, NodeOutcome],
+) -> tuple[str, ...]:
+    return tuple(
+        sorted(
+            dependency
+            for dependency in node.dependencies()
+            if outcomes[dependency].status is not NodeOutcomeStatus.SUCCESS
+        )
+    )
+
+
+def _build_result(
+    *,
+    graph: GraphConfig,
+    outcomes: dict[str, NodeOutcome],
+    execution_order: tuple[str, ...],
+    inputs: Mapping[str, Any],
+    graph_hash_value: str,
+) -> GraphRunResult:
+    terminal = outcomes[graph.terminal_node_id]
+    terminal_output: Any | None = None
+    terminal_error: TerminalError | None = None
+
+    if terminal.status is NodeOutcomeStatus.SUCCESS:
+        if terminal.output is not None:
+            terminal_output = terminal.output.values[
+                graph.node(graph.terminal_node_id).output_field
+            ]
+    else:
+        terminal_error = TerminalError(
+            node_id=terminal.node_id,
+            status=terminal.status,
+            error=terminal.error,
+            blocked_by=terminal.blocked_by,
+        )
+
+    return GraphRunResult(
+        graph_hash=graph_hash_value,
+        external_inputs=dict(inputs),
+        status=_graph_status(
+            terminal=terminal,
+            outcomes=outcomes,
+        ),
+        outcomes=outcomes,
+        execution_order=execution_order,
+        terminal_node_id=graph.terminal_node_id,
+        terminal_output=terminal_output,
+        terminal_error=terminal_error,
+    )
+
+
+def _graph_status(
+    *,
+    terminal: NodeOutcome,
+    outcomes: Mapping[str, NodeOutcome],
+) -> GraphRunStatus:
+    if terminal.status is not NodeOutcomeStatus.SUCCESS:
+        if terminal.status is NodeOutcomeStatus.BLOCKED:
+            return GraphRunStatus.BLOCKED
+        return GraphRunStatus.ERROR
+    if any(
+        outcome.status is not NodeOutcomeStatus.SUCCESS
+        for outcome in outcomes.values()
+    ):
+        return GraphRunStatus.PARTIAL
+    return GraphRunStatus.SUCCESS