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.mdindex 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.pyindex 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@propertydef 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 returnedTraceContext so it is born with the correct flag.+ mode: Provenance mode to stamp onto generated GraphSpecs."""self._is_active = Trueself._emit_graph_events = emit_graph_events@@ -267,6 +272,7 @@ class GraphTracer(GraphTracerProtocol):self._event_sequence = 0self._pipe_registry = {}self._concept_registry = {}+ self._mode = modereturn 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 = 0self._pipe_registry = {}self._concept_registry = {}+ self._mode = GraphSpecMode.LIVEreturn graphdiff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.pyindex 4431370b8..a4a6c3bfc 100644--- a/pipelex/graph/graph_tracer_manager.py+++ b/pipelex/graph/graph_tracer_manager.py@@ -7,7 +7,7 @@ from pipelex import logfrom pipelex.graph.graph_config import DataInclusionConfigfrom pipelex.graph.graph_tracer import GraphTracerfrom pipelex.graph.graph_tracer_protocol import GraphTracerProtocol-from pipelex.graph.graphspec import GraphSpec, IOSpec, NodeKind+from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, IOSpec, NodeKindfrom pipelex.graph.trace_context import TraceContextfrom pipelex.system.registries.singleton import ABCSingletonMeta, MetaSingletonfrom 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 setupso 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 keyif tracer_key is not None:diff --git a/pipelex/graph/graph_tracer_protocol.py b/pipelex/graph/graph_tracer_protocol.pyindex 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, Protocolfrom typing_extensions import overridefrom pipelex.graph.graph_config import DataInclusionConfig-from pipelex.graph.graphspec import EdgeKind, GraphSpec, IOSpec, NodeKind+from pipelex.graph.graphspec import EdgeKind, GraphSpec, GraphSpecMode, IOSpec, NodeKindfrom pipelex.graph.trace_context import TraceContextfrom 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.pyindex eedaea58d..59303b572 100644--- a/pipelex/graph/graphspec.py+++ b/pipelex/graph/graphspec.py@@ -22,6 +22,22 @@ MAX_STACK_LENGTH = 2000GRAPHSPEC_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_FORMATelif 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 excreturn selfdef to_json(self) -> str:diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.pyindex 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 ContentGeneratorfrom pipelex.config import get_configfrom pipelex.core.pipes.pipe_abstract import PipeAbstractfrom pipelex.graph.graph_tracer_manager import GraphTracerManager-from pipelex.graph.graphspec import GraphSpec+from pipelex.graph.graphspec import GraphSpec, GraphSpecModefrom pipelex.hub import get_library_manager, scoped_content_generator, scoped_event_log, scoped_pipe_routerfrom pipelex.observer.observer_protocol import ObserverNoOpfrom pipelex.pipe_run.exceptions import DryRunGraphNotProducedError@@ -128,6 +128,7 @@ async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> Grapipeline_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.pyindex 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.pyindex 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 annotationsfrom enum import StrEnum+from pipelex.graph.graphspec import GraphSpecMode+class PipeRunMode(StrEnum):LIVE = "live"@@ -22,3 +24,11 @@ class PipeRunMode(StrEnum):return Truecase PipeRunMode.DRY:return False++ @property+ def graphspec_mode(self) -> GraphSpecMode:+ match self:+ case PipeRunMode.DRY:+ return GraphSpecMode.DRY+ case PipeRunMode.LIVE:+ return GraphSpecMode.LIVEdiff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.pyindex 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_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.graph.graphspec import GraphSpec, PipelineReffrom pipelex.hub import get_event_log_override+from pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.reporting.reporting_types import AnyTokensUsagefrom pipelex.system.exceptions import MissingDependencyErrorfrom 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_specdiff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex 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 alsodiff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.pyindex 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_idself._pipeline_ref = pipeline_ref+ self._mode = modeself._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.jsonindex 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.jsonindex 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.pyindex 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 pytestfrom pipelex.config import get_configfrom pipelex.core.memory.absence import AbsenceRecordfrom pipelex.core.memory.working_memory import MAIN_STUFF_NAME-from pipelex.graph.graphspec import GraphSpec, NodeStatus+from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, NodeStatusfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.pipeline_response import RunStatefrom pipelex.pipeline.runner import PipelexMTHDSProtocol@@ -60,6 +60,8 @@ class TestLiftedChainDryLiveParity:dry_graph = dry_response.pipe_output.graph_specassert live_graph is not Noneassert dry_graph is not None+ assert live_graph.meta["mode"] == GraphSpecMode.LIVE+ assert dry_graph.meta["mode"] == GraphSpecMode.DRYlive_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.pyindex 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 MockerFixturefrom pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.graph.graphspec import GraphSpecModefrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend@@ -73,6 +74,7 @@ class TestDirectTracingAssembly:assert pipe_output.tokens_usages is not Noneassert len(pipe_output.tokens_usages) >= 1assert pipe_output.graph_spec is not None+ assert pipe_output.graph_spec.meta["mode"] == GraphSpecMode.DRYassert pipe_output.usage_assembly_error is Noneasync 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.pyindex 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 MockerFixturefrom pipelex.config import get_configfrom pipelex.core.interpreter.exceptions import PipelexInterpreterError+from pipelex.graph.graphspec import GraphSpecModefrom pipelex.pipeline.dry_run_pipeline import dry_run_pipelinefrom 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.DRYtraced_pipe_codes = {node.pipe_code for node in graph_spec.nodes if node.pipe_code}assert "echo_subject" in traced_pipe_codesassert "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.pyindex 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, timedeltafrom pipelex.graph.graph_tracer import GraphTracer-from pipelex.graph.graphspec import EdgeKind, IOSpec, NodeKind, NodeStatus+from pipelex.graph.graphspec import EdgeKind, GraphSpecMode, IOSpec, NodeKind, NodeStatusfrom tests.unit.pipelex.graph.conftest import make_defaulted_data_inclusion_config@@ -35,6 +35,21 @@ class TestGraphTracer:assert graph_spec is not Noneassert 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.DRYdef 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.pyindex 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_idassert 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.pyindex 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.metadef 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.pyindex 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 LLMTokensUsagefrom pipelex.cogt.usage.cost_category import CostCategoryfrom pipelex.cogt.usage.token_category import TokenCategoryfrom pipelex.core.pipes.pipe_output import PipeOutput+from pipelex.graph.graphspec import GraphSpecMode+from pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipe_run.tracing_assembly import TracingAssembly, assemble_tracing, assemble_tracing_on_outputfrom pipelex.pipeline.job_metadata import JobMetadatafrom 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_graphassert result.tokens_usages is Noneassemble.assert_called_once()+ assert assemble.call_args.kwargs["mode"] == GraphSpecMode.DRYdef 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.pyindex 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, timedeltafrom typing import Any-from pipelex.graph.graphspec import EdgeKind, ErrorSpec, IOSpec, NodeKind, NodeStatus+from pipelex.graph.graphspec import EdgeKind, ErrorSpec, GraphSpecMode, IOSpec, NodeKind, NodeStatusfrom pipelex.tracing.graphspec_assembler import GraphSpecAssemblerfrom pipelex.tracing.trace_events import (BatchAggregateEvent,@@ -69,6 +69,13 @@ class TestGraphSpecAssembler:assert result.graph_id == _GRAPH_IDassert 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.DRYdef test_registry_source_payloads_survive_assembly(self) -> None:"""PipeStartEvent and PipeEndSuccessEvent registry payloads are copied unchanged."""