Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Add graph provenance mode metadata (#1038)

Louis Choquel76477238b6b7
diff --git a/docs/under-the-hood/execution-graph-tracing.md b/docs/under-the-hood/execution-graph-tracing.md
index 95d197c1f..c7b430a03 100644
--- a/docs/under-the-hood/execution-graph-tracing.md
+++ b/docs/under-the-hood/execution-graph-tracing.md
@@ -173,6 +173,8 @@ class GraphSpec(BaseModel):
return self.model_dump_json(by_alias=True, indent=2)
```
+`meta.format` is always `"mthds"` on newly emitted Pipelex graphs. `meta.mode` records provenance for renderers and shared tooling: Pipelex execution graphs emit `"dry"` for dry-run/mock execution and `"live"` for real execution. The shared renderer also accepts `"static"` for graphs produced by a static MTHDS graph builder.
+
### Node Types
| NodeKind | Description |
diff --git a/pipelex/graph/graph_tracer.py b/pipelex/graph/graph_tracer.py
index 37e96b228..64d61b1ca 100644
--- a/pipelex/graph/graph_tracer.py
+++ b/pipelex/graph/graph_tracer.py
@@ -12,6 +12,7 @@ from pipelex.graph.graphspec import (
EdgeSpec,
ErrorSpec,
GraphSpec,
+ GraphSpecMode,
IOSpec,
NodeIOSpec,
NodeKind,
@@ -19,6 +20,7 @@ from pipelex.graph.graphspec import (
NodeStatus,
PipelineRef,
TimingSpec,
+ make_graphspec_meta,
output_digest_is_optional,
)
from pipelex.graph.trace_context import TraceContext
@@ -154,6 +156,7 @@ class GraphTracer(GraphTracerProtocol):
# Registries for pipe and concept data (keyed by pipe_ref and concept_ref)
self._pipe_registry: dict[str, dict[str, Any]] = {}
self._concept_registry: dict[str, dict[str, Any]] = {}
+ self._mode: GraphSpecMode = GraphSpecMode.LIVE
@property
def is_active(self) -> bool:
@@ -227,6 +230,7 @@ class GraphTracer(GraphTracerProtocol):
pipeline_run_id: str | None = None,
emit_graph_events: bool = True,
emit_usage_events: bool = True,
+ mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> TraceContext:
"""Initialize tracing for a new pipeline run.
@@ -244,6 +248,7 @@ class GraphTracer(GraphTracerProtocol):
teardown skips the discarded spec build; the returned TraceContext carries the flag.
emit_usage_events: Whether this run emits usage (cost) events. Stamped onto the returned
TraceContext so it is born with the correct flag.
+ mode: Provenance mode to stamp onto generated GraphSpecs.
"""
self._is_active = True
self._emit_graph_events = emit_graph_events
@@ -267,6 +272,7 @@ class GraphTracer(GraphTracerProtocol):
self._event_sequence = 0
self._pipe_registry = {}
self._concept_registry = {}
+ self._mode = mode
return TraceContext(
graph_id=graph_id,
@@ -314,6 +320,7 @@ class GraphTracer(GraphTracerProtocol):
pipeline_ref=self._pipeline_ref or PipelineRef(),
nodes=nodes,
edges=self._edges,
+ meta=make_graphspec_meta(mode=self._mode),
pipe_registry=dict(self._pipe_registry),
concept_registry=dict(self._concept_registry),
)
@@ -338,6 +345,7 @@ class GraphTracer(GraphTracerProtocol):
self._event_sequence = 0
self._pipe_registry = {}
self._concept_registry = {}
+ self._mode = GraphSpecMode.LIVE
return graph
diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.py
index 4431370b8..a4a6c3bfc 100644
--- a/pipelex/graph/graph_tracer_manager.py
+++ b/pipelex/graph/graph_tracer_manager.py
@@ -7,7 +7,7 @@ from pipelex import log
from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graph_tracer import GraphTracer
from pipelex.graph.graph_tracer_protocol import GraphTracerProtocol
-from pipelex.graph.graphspec import GraphSpec, IOSpec, NodeKind
+from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, IOSpec, NodeKind
from pipelex.graph.trace_context import TraceContext
from pipelex.system.registries.singleton import ABCSingletonMeta, MetaSingleton
from pipelex.tracing.event_log_protocol import EventLogProtocol # noqa: TC001 - used in open_tracer signature
@@ -104,6 +104,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
tracer_key: str | None = None,
emit_graph_events: bool = True,
emit_usage_events: bool = True,
+ mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> TraceContext:
"""Create and initialize a new tracer for a pipeline run.
@@ -124,6 +125,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
(no post-hoc model_copy needed at the call site).
emit_usage_events: Whether this run emits usage (cost) events. Threaded into setup
so the returned TraceContext is born with the correct flag.
+ mode: Provenance mode to stamp onto generated GraphSpecs.
Returns:
Initial TraceContext to pass through JobMetadata.
@@ -161,6 +163,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
pipeline_run_id=pipeline_run_id,
emit_graph_events=emit_graph_events,
emit_usage_events=emit_usage_events,
+ mode=mode,
)
# Set the tracer_key on the TraceContext so downstream lookups use the same key
if tracer_key is not None:
diff --git a/pipelex/graph/graph_tracer_protocol.py b/pipelex/graph/graph_tracer_protocol.py
index d4dd6c097..186b8bc98 100644
--- a/pipelex/graph/graph_tracer_protocol.py
+++ b/pipelex/graph/graph_tracer_protocol.py
@@ -4,7 +4,7 @@ from typing import Any, Protocol
from typing_extensions import override
from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.graphspec import EdgeKind, GraphSpec, IOSpec, NodeKind
+from pipelex.graph.graphspec import EdgeKind, GraphSpec, GraphSpecMode, IOSpec, NodeKind
from pipelex.graph.trace_context import TraceContext
from pipelex.tracing.event_log_protocol import EventLogProtocol # noqa: TC001 - used in setup signature
@@ -28,6 +28,7 @@ class GraphTracerProtocol(Protocol):
pipeline_run_id: str | None = None,
emit_graph_events: bool = True,
emit_usage_events: bool = True,
+ mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> TraceContext:
"""Initialize tracing for a new pipeline run.
@@ -43,6 +44,7 @@ class GraphTracerProtocol(Protocol):
Stamped onto the returned TraceContext so it is born with the correct flag.
emit_usage_events: Whether usage (cost) trace events should be emitted for this run.
Stamped onto the returned TraceContext so it is born with the correct flag.
+ mode: Provenance mode to stamp onto generated GraphSpecs.
Returns:
Initial TraceContext to pass through JobMetadata.
@@ -292,6 +294,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
pipeline_run_id: str | None = None,
emit_graph_events: bool = True,
emit_usage_events: bool = True,
+ mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> TraceContext:
return TraceContext(
graph_id=graph_id,
diff --git a/pipelex/graph/graphspec.py b/pipelex/graph/graphspec.py
index eedaea58d..59303b572 100644
--- a/pipelex/graph/graphspec.py
+++ b/pipelex/graph/graphspec.py
@@ -22,6 +22,22 @@ MAX_STACK_LENGTH = 2000
GRAPHSPEC_FORMAT = "mthds"
+class GraphSpecMode(StrEnum):
+ """Provenance mode for a GraphSpec."""
+
+ DRY = "dry"
+ LIVE = "live"
+ STATIC = "static"
+
+
+def make_graphspec_meta(*, mode: GraphSpecMode, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+ """Build canonical GraphSpec metadata while preserving caller extras."""
+ meta = dict(extra or {})
+ meta["format"] = GRAPHSPEC_FORMAT
+ meta["mode"] = mode
+ return meta
+
+
class NodeKind(StrEnum):
"""Types of nodes in the execution graph."""
@@ -307,13 +323,21 @@ class GraphSpec(BaseModel):
concept_registry: dict[str, dict[str, Any]] = Field(default_factory=dict)
@model_validator(mode="after")
- def ensure_format_meta(self) -> Self:
+ def ensure_meta_contract(self) -> Self:
existing_format = self.meta.get("format")
if existing_format is None:
self.meta["format"] = GRAPHSPEC_FORMAT
elif existing_format != GRAPHSPEC_FORMAT:
msg = f"GraphSpec.meta['format'] must be '{GRAPHSPEC_FORMAT}', got '{existing_format}'"
raise ValueError(msg)
+ if "mode" in self.meta:
+ existing_mode = self.meta["mode"]
+ try:
+ self.meta["mode"] = GraphSpecMode(existing_mode)
+ except ValueError as exc:
+ allowed_modes = ", ".join(mode for mode in GraphSpecMode)
+ msg = f"GraphSpec.meta['mode'] must be one of: {allowed_modes}; got '{existing_mode}'"
+ raise ValueError(msg) from exc
return self
def to_json(self) -> str:
diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.py
index 067c1359c..34e42ff98 100644
--- a/pipelex/pipe_run/dry_run_in_process.py
+++ b/pipelex/pipe_run/dry_run_in_process.py
@@ -17,7 +17,7 @@ from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.config import get_config
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.graph.graph_tracer_manager import GraphTracerManager
-from pipelex.graph.graphspec import GraphSpec
+from pipelex.graph.graphspec import GraphSpec, GraphSpecMode
from pipelex.hub import get_library_manager, scoped_content_generator, scoped_event_log, scoped_pipe_router
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_run.exceptions import DryRunGraphNotProducedError
@@ -128,6 +128,7 @@ async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> Gra
pipeline_run_id=pipeline_run_id,
emit_graph_events=True,
emit_usage_events=False,
+ mode=GraphSpecMode.DRY,
)
try:
with scoped_event_log(event_log), scoped_pipe_router(pipe_router), scoped_content_generator(content_generator):
diff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.py
index 3119fdca4..c1b0de44a 100644
--- a/pipelex/pipe_run/pipe_run.py
+++ b/pipelex/pipe_run/pipe_run.py
@@ -81,6 +81,7 @@ class PipeRun(PipeRunProtocol):
assemble_usage=trace_context.emit_usage_events,
domain_code=pipe_job.pipe.domain_code,
main_pipe_code=pipe_job.pipe.code,
+ run_mode=pipe_job.pipe_run_params.run_mode,
)
if delivery_assignment is not None:
diff --git a/pipelex/pipe_run/pipe_run_mode.py b/pipelex/pipe_run/pipe_run_mode.py
index 14f6b0acc..1b49ad674 100644
--- a/pipelex/pipe_run/pipe_run_mode.py
+++ b/pipelex/pipe_run/pipe_run_mode.py
@@ -2,6 +2,8 @@ from __future__ import annotations
from enum import StrEnum
+from pipelex.graph.graphspec import GraphSpecMode
+
class PipeRunMode(StrEnum):
LIVE = "live"
@@ -22,3 +24,11 @@ class PipeRunMode(StrEnum):
return True
case PipeRunMode.DRY:
return False
+
+ @property
+ def graphspec_mode(self) -> GraphSpecMode:
+ match self:
+ case PipeRunMode.DRY:
+ return GraphSpecMode.DRY
+ case PipeRunMode.LIVE:
+ return GraphSpecMode.LIVE
diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.py
index 544406bdb..357df0ebe 100644
--- a/pipelex/pipe_run/tracing_assembly.py
+++ b/pipelex/pipe_run/tracing_assembly.py
@@ -20,6 +20,7 @@ from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.graph.graphspec import GraphSpec, PipelineRef
from pipelex.hub import get_event_log_override
+from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.reporting.reporting_types import AnyTokensUsage
from pipelex.system.exceptions import MissingDependencyError
from pipelex.tracing.event_log_factory import make_event_log
@@ -55,6 +56,7 @@ def assemble_tracing(
assemble_usage: bool,
domain_code: str | None = None,
main_pipe_code: str | None = None,
+ run_mode: PipeRunMode = PipeRunMode.LIVE,
) -> TracingAssembly:
"""Read the trace events for ``pipeline_run_id`` once and assemble the requested artifacts.
@@ -76,6 +78,7 @@ def assemble_tracing(
assemble_usage: Whether to aggregate token usage from the events.
domain_code: Domain code for the graph's pipeline ref.
main_pipe_code: Main pipe code for the graph's pipeline ref.
+ run_mode: Final pipe run mode used to stamp GraphSpec provenance.
Returns:
A TracingAssembly carrying whichever artifacts were requested and succeeded.
@@ -129,6 +132,7 @@ def assemble_tracing(
domain=domain_code,
main_pipe=main_pipe_code,
),
+ mode=run_mode.graphspec_mode,
)
log.debug(f"Graph assembled from {len(events)} events for pipeline_run_id={pipeline_run_id}")
except ValidationError as validation_error:
@@ -147,6 +151,7 @@ def assemble_tracing_on_output(
assemble_usage: bool,
domain_code: str | None = None,
main_pipe_code: str | None = None,
+ run_mode: PipeRunMode = PipeRunMode.LIVE,
) -> None:
"""Assemble graph and/or usage from trace events and set them on pipe_output (DIRECT mode).
@@ -161,6 +166,7 @@ def assemble_tracing_on_output(
assemble_usage: Whether to aggregate and set token usage.
domain_code: Domain code for the graph's pipeline ref.
main_pipe_code: Main pipe code for the graph's pipeline ref.
+ run_mode: Final pipe run mode used to stamp GraphSpec provenance.
"""
result = assemble_tracing(
pipeline_run_id=pipeline_run_id,
@@ -168,6 +174,7 @@ def assemble_tracing_on_output(
assemble_usage=assemble_usage,
domain_code=domain_code,
main_pipe_code=main_pipe_code,
+ run_mode=run_mode,
)
if result.graph_spec is not None:
pipe_output.graph_spec = result.graph_spec
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index 8caf32cf0..f92a54419 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -149,6 +149,13 @@ async def pipeline_run_setup(
msg = "Either pipe_code or mthds_contents must be provided to the pipeline API."
raise ValueError(msg)
+ # TODO: rethink this, it's not forcing
+ if pipe_run_mode is None:
+ if run_mode_from_env := get_optional_env(key=FORCE_DRY_RUN_MODE_ENV_KEY):
+ pipe_run_mode = PipeRunMode(run_mode_from_env)
+ else:
+ pipe_run_mode = PipeRunMode.LIVE
+
pipeline = get_pipeline_manager().add_new_pipeline(pipe_code=pipe_code, pipeline_run_id=pipeline_run_id)
pipeline_run_id = pipeline.pipeline_run_id
@@ -231,15 +238,9 @@ async def pipeline_run_setup(
pipeline_run_id=pipeline_run_id,
emit_graph_events=is_generate_graph,
emit_usage_events=is_generate_usage,
+ mode=pipe_run_mode.graphspec_mode,
)
- # TODO: rethink this, it's not forcing
- if pipe_run_mode is None:
- if run_mode_from_env := get_optional_env(key=FORCE_DRY_RUN_MODE_ENV_KEY):
- pipe_run_mode = PipeRunMode(run_mode_from_env)
- else:
- pipe_run_mode = PipeRunMode.LIVE
-
# Register the event log on the report delegate for usage event emission — only when cost reporting
# is on. In graph-only mode (--graph --no-costs) the tracer owns the event_log for graph events, but
# no usage-event context is registered, so usage events are suppressed (the runner fallback also
diff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.py
index 1cf619d54..1c05825f1 100644
--- a/pipelex/tracing/graphspec_assembler.py
+++ b/pipelex/tracing/graphspec_assembler.py
@@ -16,6 +16,7 @@ from pipelex.graph.graphspec import (
EdgeSpec,
ErrorSpec,
GraphSpec,
+ GraphSpecMode,
IOSpec,
NodeIOSpec,
NodeKind,
@@ -23,6 +24,7 @@ from pipelex.graph.graphspec import (
NodeStatus,
PipelineRef,
TimingSpec,
+ make_graphspec_meta,
output_digest_is_optional,
)
from pipelex.tracing.trace_events import (
@@ -122,6 +124,7 @@ class GraphSpecAssembler:
*,
graph_id: str,
pipeline_ref: PipelineRef | None = None,
+ mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> GraphSpec:
"""Assemble a GraphSpec from a flat list of trace events.
@@ -129,11 +132,12 @@ class GraphSpecAssembler:
events: Flat list of trace events, pre-sorted by (workflow_id, sequence).
graph_id: The graph identifier for the assembled GraphSpec.
pipeline_ref: Optional pipeline reference metadata.
+ mode: Provenance mode to stamp onto the assembled GraphSpec.
Returns:
A complete GraphSpec with nodes and edges.
"""
- assembler = _AssemblerState(graph_id=graph_id, pipeline_ref=pipeline_ref or PipelineRef())
+ assembler = _AssemblerState(graph_id=graph_id, pipeline_ref=pipeline_ref or PipelineRef(), mode=mode)
assembler.pass_one(events)
assembler.pass_two()
return assembler.build_graph_spec()
@@ -142,9 +146,10 @@ class GraphSpecAssembler:
class _AssemblerState:
"""Mutable state for a single assembler invocation."""
- def __init__(self, graph_id: str, pipeline_ref: PipelineRef) -> None:
+ def __init__(self, graph_id: str, pipeline_ref: PipelineRef, mode: GraphSpecMode) -> None:
self._graph_id = graph_id
self._pipeline_ref = pipeline_ref
+ self._mode = mode
self._earliest_timestamp: datetime | None = None
# Pass 1 accumulation
@@ -215,6 +220,7 @@ class _AssemblerState:
pipeline_ref=self._pipeline_ref,
nodes=nodes,
edges=all_edges,
+ meta=make_graphspec_meta(mode=self._mode),
pipe_registry=dict(self._pipe_registry),
concept_registry=dict(self._concept_registry),
)
diff --git a/tests/data/graphs/cv_batch.json b/tests/data/graphs/cv_batch.json
index f3195c191..8a76c9566 100644
--- a/tests/data/graphs/cv_batch.json
+++ b/tests/data/graphs/cv_batch.json
@@ -818,5 +818,8 @@
"meta": {}
}
],
- "meta": {}
-}
\ No newline at end of file
+ "meta": {
+ "format": "mthds",
+ "mode": "live"
+ }
+}
diff --git a/tests/data/graphs/cv_job_match.json b/tests/data/graphs/cv_job_match.json
index 5748e7a9b..b0f60b258 100644
--- a/tests/data/graphs/cv_job_match.json
+++ b/tests/data/graphs/cv_job_match.json
@@ -940,5 +940,8 @@
"meta": {}
}
],
- "meta": {}
-}
\ No newline at end of file
+ "meta": {
+ "format": "mthds",
+ "mode": "live"
+ }
+}
diff --git a/tests/e2e/pipelex/pipes/optionals/test_lift_parity_dry_live.py b/tests/e2e/pipelex/pipes/optionals/test_lift_parity_dry_live.py
index ee667198e..55a94f828 100644
--- a/tests/e2e/pipelex/pipes/optionals/test_lift_parity_dry_live.py
+++ b/tests/e2e/pipelex/pipes/optionals/test_lift_parity_dry_live.py
@@ -10,7 +10,7 @@ import pytest
from pipelex.config import get_config
from pipelex.core.memory.absence import AbsenceRecord
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME
-from pipelex.graph.graphspec import GraphSpec, NodeStatus
+from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, NodeStatus
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.pipeline_response import RunState
from pipelex.pipeline.runner import PipelexMTHDSProtocol
@@ -60,6 +60,8 @@ class TestLiftedChainDryLiveParity:
dry_graph = dry_response.pipe_output.graph_spec
assert live_graph is not None
assert dry_graph is not None
+ assert live_graph.meta["mode"] == GraphSpecMode.LIVE
+ assert dry_graph.meta["mode"] == GraphSpecMode.DRY
live_skips = _skipped_nodes(live_graph)
dry_skips = _skipped_nodes(dry_graph)
assert set(live_skips.keys()) == set(dry_skips.keys()) == {"opar_make_analysis", "opar_summarize"}
diff --git a/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py b/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py
index 2f4f8ef39..1ad9d5ae5 100644
--- a/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py
+++ b/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py
@@ -19,6 +19,7 @@ from pytest_mock import MockerFixture
from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.graph.graphspec import GraphSpecMode
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend
@@ -73,6 +74,7 @@ class TestDirectTracingAssembly:
assert pipe_output.tokens_usages is not None
assert len(pipe_output.tokens_usages) >= 1
assert pipe_output.graph_spec is not None
+ assert pipe_output.graph_spec.meta["mode"] == GraphSpecMode.DRY
assert pipe_output.usage_assembly_error is None
async def test_costs_only_leaves_graph_spec_none(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:
diff --git a/tests/integration/pipelex/pipeline/test_dry_run_pipeline_graph.py b/tests/integration/pipelex/pipeline/test_dry_run_pipeline_graph.py
index bfae6df92..19ccb8375 100644
--- a/tests/integration/pipelex/pipeline/test_dry_run_pipeline_graph.py
+++ b/tests/integration/pipelex/pipeline/test_dry_run_pipeline_graph.py
@@ -16,6 +16,7 @@ from pytest_mock import MockerFixture
from pipelex.config import get_config
from pipelex.core.interpreter.exceptions import PipelexInterpreterError
+from pipelex.graph.graphspec import GraphSpecMode
from pipelex.pipeline.dry_run_pipeline import dry_run_pipeline
from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
@@ -59,6 +60,7 @@ class TestDryRunPipelineGraphTransport:
graph_spec, pipe_code = await dry_run_pipeline(mthds_contents=[_DRY_RUN_GRAPH_MTHDS])
assert pipe_code == f"{_DRY_RUN_GRAPH_DOMAIN}.echo_subject"
+ assert graph_spec.meta["mode"] == GraphSpecMode.DRY
traced_pipe_codes = {node.pipe_code for node in graph_spec.nodes if node.pipe_code}
assert "echo_subject" in traced_pipe_codes
assert "source" not in graph_spec.pipe_registry[f"{_DRY_RUN_GRAPH_DOMAIN}.echo_subject"]
diff --git a/tests/unit/pipelex/graph/test_graph_tracer.py b/tests/unit/pipelex/graph/test_graph_tracer.py
index db5a6e8a3..0e0af3954 100644
--- a/tests/unit/pipelex/graph/test_graph_tracer.py
+++ b/tests/unit/pipelex/graph/test_graph_tracer.py
@@ -3,7 +3,7 @@
from datetime import UTC, datetime, timedelta
from pipelex.graph.graph_tracer import GraphTracer
-from pipelex.graph.graphspec import EdgeKind, IOSpec, NodeKind, NodeStatus
+from pipelex.graph.graphspec import EdgeKind, GraphSpecMode, IOSpec, NodeKind, NodeStatus
from tests.unit.pipelex.graph.conftest import make_defaulted_data_inclusion_config
@@ -35,6 +35,21 @@ class TestGraphTracer:
assert graph_spec is not None
assert graph_spec.pipeline_ref.domain == "test.domain"
assert graph_spec.pipeline_ref.main_pipe == "main_pipe"
+ assert graph_spec.meta["mode"] == GraphSpecMode.LIVE
+
+ def test_setup_with_dry_mode_stamps_graphspec_meta(self) -> None:
+ tracer = GraphTracer()
+ tracer.setup(
+ graph_id="test-graph-dry",
+ data_inclusion=make_defaulted_data_inclusion_config(),
+ mode=GraphSpecMode.DRY,
+ )
+
+ graph_spec = tracer.teardown()
+
+ assert graph_spec is not None
+ assert graph_spec.meta["format"] == "mthds"
+ assert graph_spec.meta["mode"] == GraphSpecMode.DRY
def test_teardown_without_setup_returns_none(self) -> None:
"""Test that teardown returns None if not active."""
diff --git a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py b/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
index c6124cbcf..f4434d552 100644
--- a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
+++ b/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
@@ -8,6 +8,7 @@ from pipelex.graph.graphspec import (
EdgeSpec,
ErrorSpec,
GraphSpec,
+ GraphSpecMode,
IOSpec,
NodeIOSpec,
NodeKind,
@@ -131,7 +132,7 @@ class TestGraphSpecRoundtrip:
),
nodes=[node1, node2],
edges=[edge],
- meta={"run_mode": "live"},
+ meta={"mode": GraphSpecMode.LIVE, "extra": "value"},
)
json_str = graph.to_json()
@@ -163,7 +164,7 @@ class TestGraphSpecRoundtrip:
assert restored.edges[0].label == "step 1"
# Verify meta
- assert restored.meta == {"run_mode": "live", "format": "mthds"}
+ assert restored.meta == {"mode": GraphSpecMode.LIVE, "extra": "value", "format": "mthds"}
def test_roundtrip_with_error_spec(self) -> None:
"""Test round-trip for a graph with a failed node containing error info."""
@@ -225,6 +226,15 @@ class TestGraphSpecRoundtrip:
assert restored.graph_id == graph.graph_id
assert restored.nodes[0].node_id == graph.nodes[0].node_id
+ def test_loads_old_fixture_without_mode(self) -> None:
+ """Old GraphSpec JSON without meta.mode remains readable."""
+ fixture_path = Path(__file__).parents[3] / "data" / "graphs" / "cv_batch_old.json"
+
+ restored = GraphSpec.model_validate_json(load_text_from_path(fixture_path))
+
+ assert restored.meta["format"] == "mthds"
+ assert "mode" not in restored.meta
+
def test_json_is_human_readable(self) -> None:
"""Test that generated JSON is indented and human-readable."""
graph = GraphSpec(
diff --git a/tests/unit/pipelex/graph/test_graphspec_validation.py b/tests/unit/pipelex/graph/test_graphspec_validation.py
index 788fa2151..e369f2fda 100644
--- a/tests/unit/pipelex/graph/test_graphspec_validation.py
+++ b/tests/unit/pipelex/graph/test_graphspec_validation.py
@@ -9,6 +9,7 @@ from pipelex.graph.graphspec import (
EdgeSpec,
ErrorSpec,
GraphSpec,
+ GraphSpecMode,
NodeKind,
NodeSpec,
NodeStatus,
@@ -317,6 +318,7 @@ class TestGraphSpecValidation:
edges=[],
)
assert graph.meta["format"] == "mthds"
+ assert "mode" not in graph.meta
def test_meta_format_preserved_when_correct(self) -> None:
graph = GraphSpec(
@@ -330,6 +332,41 @@ class TestGraphSpecValidation:
assert graph.meta["format"] == "mthds"
assert graph.meta["extra"] == "value"
+ @pytest.mark.parametrize("mode", [GraphSpecMode.DRY, GraphSpecMode.LIVE, GraphSpecMode.STATIC])
+ def test_meta_mode_preserved_when_valid(self, mode: GraphSpecMode) -> None:
+ graph = GraphSpec(
+ graph_id="test_graph",
+ created_at=ValidGraphData.CREATED_AT,
+ pipeline_ref=PipelineRef(),
+ nodes=[],
+ edges=[],
+ meta={"format": "mthds", "mode": mode},
+ )
+ assert graph.meta["format"] == "mthds"
+ assert graph.meta["mode"] == mode
+
+ def test_meta_mode_rejected_when_wrong(self) -> None:
+ with pytest.raises(ValidationError):
+ GraphSpec(
+ graph_id="test_graph",
+ created_at=ValidGraphData.CREATED_AT,
+ pipeline_ref=PipelineRef(),
+ nodes=[],
+ edges=[],
+ meta={"format": "mthds", "mode": "wrong"},
+ )
+
+ def test_meta_mode_rejected_when_none(self) -> None:
+ with pytest.raises(ValidationError):
+ GraphSpec(
+ graph_id="test_graph",
+ created_at=ValidGraphData.CREATED_AT,
+ pipeline_ref=PipelineRef(),
+ nodes=[],
+ edges=[],
+ meta={"format": "mthds", "mode": None},
+ )
+
def test_meta_format_rejected_when_wrong(self) -> None:
with pytest.raises(ValidationError):
GraphSpec(
diff --git a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
index 79d07d80d..ac9a9179d 100644
--- a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
+++ b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
@@ -10,6 +10,8 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.graph.graphspec import GraphSpecMode
+from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.tracing_assembly import TracingAssembly, assemble_tracing, assemble_tracing_on_output
from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.system.exceptions import MissingDependencyError
@@ -110,11 +112,13 @@ class TestTracingAssembly:
assemble_usage=False,
domain_code="dom",
main_pipe_code="main",
+ run_mode=PipeRunMode.DRY,
)
assert result.graph_spec is sentinel_graph
assert result.tokens_usages is None
assemble.assert_called_once()
+ assert assemble.call_args.kwargs["mode"] == GraphSpecMode.DRY
def test_graph_and_usage_both_assembled(self, mocker: MockerFixture) -> None:
self._enable_tracing(mocker)
diff --git a/tests/unit/pipelex/tracing/test_graphspec_assembler.py b/tests/unit/pipelex/tracing/test_graphspec_assembler.py
index b0a6d7e37..8d2e2c916 100644
--- a/tests/unit/pipelex/tracing/test_graphspec_assembler.py
+++ b/tests/unit/pipelex/tracing/test_graphspec_assembler.py
@@ -3,7 +3,7 @@
from datetime import UTC, datetime, timedelta
from typing import Any
-from pipelex.graph.graphspec import EdgeKind, ErrorSpec, IOSpec, NodeKind, NodeStatus
+from pipelex.graph.graphspec import EdgeKind, ErrorSpec, GraphSpecMode, IOSpec, NodeKind, NodeStatus
from pipelex.tracing.graphspec_assembler import GraphSpecAssembler
from pipelex.tracing.trace_events import (
BatchAggregateEvent,
@@ -69,6 +69,13 @@ class TestGraphSpecAssembler:
assert result.graph_id == _GRAPH_ID
assert result.nodes == []
assert result.edges == []
+ assert result.meta["mode"] == GraphSpecMode.LIVE
+
+ def test_explicit_mode(self) -> None:
+ """Assembler stamps the requested GraphSpec provenance mode."""
+ result = GraphSpecAssembler.assemble(events=[], graph_id=_GRAPH_ID, mode=GraphSpecMode.DRY)
+ assert result.meta["format"] == "mthds"
+ assert result.meta["mode"] == GraphSpecMode.DRY
def test_registry_source_payloads_survive_assembly(self) -> None:
"""PipeStartEvent and PipeEndSuccessEvent registry payloads are copied unchanged."""