dr-graph 0.1.0__tar.gz

dr_graph-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+.worktrees
+.DS_Store
+*.swp
+.env
+.env.*
+!.env.example
+.cache/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.pyre/
+.pyright/
+.venv/
+build/
+dist/
+*.egg-info/
+htmlcov/
+.coverage
+.coverage.*
+.hypothesis/
+.nox/
+.tox/
+.docs/
+**/__pycache__/
+*.py[cod]
+graphify-out/

dr_graph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 danielle rothermel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dr_graph-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: dr-graph
+Version: 0.1.0
+Summary: Hashable graph configs plus a pure, deterministic interpreter.
+Project-URL: Repository, https://github.com/danielle-rothermel/dr-graph
+Project-URL: Issues, https://github.com/danielle-rothermel/dr-graph/issues
+Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: dr-serialize<0.2.0,>=0.1.0
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# dr-graph
+
+Hashable computation-graph configs plus a pure, deterministic
+interpreter. Not a workflow engine.
+
+The rule this library exists to serve: **whatever is searched over must
+be data; whatever does the searching is code.** Graph configs are the
+searched-over layer — the motivating use case is experiment conditions
+and optimizer genomes. Optimizers and durable workflows are ordinary
+code that read and write these configs.
+
+The [vocabulary sheet](https://danielle-rothermel.github.io/dr-graph/)
+(source: `.defs/vocab.html`) is the authoritative contract: the terms,
+guarantees, scope boundaries, and the mapping from each term to the
+exported names. This README orients; the sheet decides.
+
+## What it provides
+
+- **`GraphDefinition` / `NodeDefinition`** — a versioned,
+  variable-bearing DAG shape that `materialize()`s fully-set
+  `GraphConfig`s from per-node Variable assignments.
+- **`GraphConfig` / `NodeConfig`** — the flat, validated config that a
+  graph hash identifies; construction enforces the structural
+  guarantees (acyclicity, exactly one terminal node, input-source
+  legality).
+- **`graph_hash()`** — the config's identity, computed through
+  dr-serialize's identity API; the sheet defines its exact coverage
+  and format.
+- **`execute_graph()`** — pure sequential execution: resolves each
+  node's inputs, calls the injected `run_node` callback, and returns a
+  `GraphRunResult`. An optional `completed` mapping skips
+  already-paid-for nodes on resume.
+- **`node()` / `graph()` / `inline_subgraph()`** — neutral builders and
+  composition by flattening.
+
+Everything else — durability, retries, scheduling, persistence,
+prompts, providers — belongs to the caller; the sheet draws the exact
+line. Sequential execution is a feature: deterministic order is what
+makes durable-workflow replay line up.
+
+## Ecosystem
+
+Part of the `dr-*` family: depends on `dr-serialize` (identity
+hashing); consumed by `whetstone-ai`. Neighbor repos are
+`dr-providers`, `dr-platform`, `dr-code`, and `unitbench`.
+
+## Example
+
+```python
+from dr_graph import execute_graph, graph, node
+
+config = graph(
+    [
+        node(
+            "encoder",
+            node_type="llm_call",
+            input_sources={"prompt": "task.prompt"},
+            output_field="description",
+        ),
+        node(
+            "decoder",
+            node_type="llm_call",
+            input_sources={"description": "encoder.description"},
+            output_field="code",
+        ),
+    ],
+    terminal="decoder",
+)
+
+result = execute_graph(
+    graph=config,
+    inputs={"prompt": "write an add function"},
+    run_node=lambda node_config, inputs: {
+        "values": {node_config.output_field: "..."}
+    },
+)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ty check
+```

dr_graph-0.1.0/README.md

@@ -0,0 +1,86 @@
+# dr-graph
+
+Hashable computation-graph configs plus a pure, deterministic
+interpreter. Not a workflow engine.
+
+The rule this library exists to serve: **whatever is searched over must
+be data; whatever does the searching is code.** Graph configs are the
+searched-over layer — the motivating use case is experiment conditions
+and optimizer genomes. Optimizers and durable workflows are ordinary
+code that read and write these configs.
+
+The [vocabulary sheet](https://danielle-rothermel.github.io/dr-graph/)
+(source: `.defs/vocab.html`) is the authoritative contract: the terms,
+guarantees, scope boundaries, and the mapping from each term to the
+exported names. This README orients; the sheet decides.
+
+## What it provides
+
+- **`GraphDefinition` / `NodeDefinition`** — a versioned,
+  variable-bearing DAG shape that `materialize()`s fully-set
+  `GraphConfig`s from per-node Variable assignments.
+- **`GraphConfig` / `NodeConfig`** — the flat, validated config that a
+  graph hash identifies; construction enforces the structural
+  guarantees (acyclicity, exactly one terminal node, input-source
+  legality).
+- **`graph_hash()`** — the config's identity, computed through
+  dr-serialize's identity API; the sheet defines its exact coverage
+  and format.
+- **`execute_graph()`** — pure sequential execution: resolves each
+  node's inputs, calls the injected `run_node` callback, and returns a
+  `GraphRunResult`. An optional `completed` mapping skips
+  already-paid-for nodes on resume.
+- **`node()` / `graph()` / `inline_subgraph()`** — neutral builders and
+  composition by flattening.
+
+Everything else — durability, retries, scheduling, persistence,
+prompts, providers — belongs to the caller; the sheet draws the exact
+line. Sequential execution is a feature: deterministic order is what
+makes durable-workflow replay line up.
+
+## Ecosystem
+
+Part of the `dr-*` family: depends on `dr-serialize` (identity
+hashing); consumed by `whetstone-ai`. Neighbor repos are
+`dr-providers`, `dr-platform`, `dr-code`, and `unitbench`.
+
+## Example
+
+```python
+from dr_graph import execute_graph, graph, node
+
+config = graph(
+    [
+        node(
+            "encoder",
+            node_type="llm_call",
+            input_sources={"prompt": "task.prompt"},
+            output_field="description",
+        ),
+        node(
+            "decoder",
+            node_type="llm_call",
+            input_sources={"description": "encoder.description"},
+            output_field="code",
+        ),
+    ],
+    terminal="decoder",
+)
+
+result = execute_graph(
+    graph=config,
+    inputs={"prompt": "write an add function"},
+    run_node=lambda node_config, inputs: {
+        "values": {node_config.output_field: "..."}
+    },
+)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ty check
+```

dr_graph-0.1.0/pyproject.toml

@@ -0,0 +1,106 @@
+[project]
+name = "dr-graph"
+version = "0.1.0"
+description = "Hashable graph configs plus a pure, deterministic interpreter."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Danielle Rothermel", email = "danielle.rothermel@gmail.com" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    # dr-serialize's canonicalization defines graph_hash; bound to the tested
+    # 0.1.x range so an upgrade cannot change identities without a golden
+    # review.
+    "dr-serialize>=0.1.0,<0.2.0",
+    "pydantic>=2.13.4",
+]
+
+[project.urls]
+Repository = "https://github.com/danielle-rothermel/dr-graph"
+Issues = "https://github.com/danielle-rothermel/dr-graph/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pytest>=9.1.1",
+    "ruff>=0.15.18",
+    "ty>=0.0.51",
+]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+include = ["src/**/*.py", "tests/**/*.py"]
+line-length = 79
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "DTZ",
+    "E",
+    "F",
+    "FA",
+    "FBT",
+    "FLY",
+    "FURB",
+    "G",
+    "I",
+    "ICN",
+    "ISC",
+    "LOG",
+    "N",
+    "NPY",
+    "PD",
+    "PERF",
+    "PIE",
+    "PL",
+    "PTH",
+    "PT",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "SLOT",
+    "T10",
+    "TC",
+    "TID",
+    "TRY",
+    "UP",
+    "W",
+    "YTT",
+]
+ignore = ["PLR1711", "S101", "TRY003"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["PLR2004", "PLC0415", "ARG001", "ARG005", "S603", "TC003"]
+
+[tool.ty.src]
+include = ["src", "tests"]

dr_graph-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)