Inspection Payload & CLI

Who this is for

This page is for pipeline users who want to inspect executions and for architects/system designers who care about provenance and trace flows.

It assumes you are comfortable with pipelines (Pipeline users) and have run at least a few real workflows.

Inspection computes a configuration-only view of a pipeline. The builder exposes a canonical payload that both the CLI and GUI consume.

Note

The inspection payload is the single source of truth for GUI/CLI in config-only mode. It never contains runtime or run-space live identifiers.

See also Identity Cheatsheet for a quick reference to the identities.

Payload shape

The payload returned by semantiva.inspection.build_inspection_payload() is JSON-safe and deterministic. All ordering is canonical:

  • Nodes appear in pipeline execution order.

  • required_context_keys are sorted alphabetically.

  • All dictionaries contributing to identity computation are key-sorted.

{
  "identity": {
    "semantic_id": "plsemid-…",
    "config_id": "plcid-…",
    "run_space": {"spec_id": "…"}
  },
  "pipeline_spec_canonical": {
    "nodes": [
      {
        "uuid": "…",
        "role": "DataOperation",
        "fqcn": "package.Class",
        "node_semantic_id": "…",
        "preprocessor_metadata": {
          "derive": {
            "parameter_sweep": {
              "parameters_sig": {"factor": {"format": "ExpressionSigV1", "ast": "…"}},
              "variables_sig": {"t": {"kind": "range", "lo": 0.0, "hi": 1.0, "steps": 3, "scale": "linear", "endpoint": true}},
              "mode": "combinatorial",
              "broadcast": false,
              "collection": "semantiva.examples.test_utils.FloatDataCollection"
            }
          }
        }
      }
    ]
  },
  "required_context_keys": ["batch_size", "seed"]
}

Note

The run_space object contains only spec_id at inspection time. The inputs_id field is never computed during inspection—it appears only in runtime traces after input sources are fingerprinted.

API entry points

The inspection layer exposes three primary entry points:

  • semantiva.inspection.build_pipeline_inspection — error-resilient builder returning PipelineInspection.

  • semantiva.inspection.build_inspection_payload — canonical, JSON-safe payload used by GUI/CLI (preferred over the legacy name).

  • semantiva.inspection.build_canonical_graph — canonical graph representation for visualization.

Deprecated since version 0.5.1: semantiva.inspection.build is deprecated in favour of semantiva.inspection.build_inspection_payload and will be removed in a future minor release (not before 0.6.0). The helper semantiva.inspection.collect_required_context_keys is also deprecated; access PipelineInspection.required_context_keys directly instead.

Excluded fields

The payload never exposes runtime identifiers or UI-only metadata:

  • pipeline_id (plid-*) — runtime-only

  • run_id (run-*) — runtime-only

  • run_space_launch_id — runtime-only

  • run_space_attempt — runtime-only

  • run_space_index — runtime-only

  • run_space_context — runtime-only

  • run_space_inputs_id — computed at runtime, never at inspection

  • preprocessor_view — UI-only (raw expressions for display)

These exclusions ensure the payload remains a pure configuration-time artifact suitable for caching, comparison, and use as a single source of truth (SSOT) for configuration identity.

CLI contract

semantiva inspect <pipeline.yaml> renders the payload in two modes:

Concise mode (default)

Prints exactly four lines of identity information:

Configuration Identity
- Semantic ID: plsemid-…
- Config ID:   plcid-…
- Run-Space Config ID: <spec_id or "none">
Required Context Keys: a, b, c

  • semantic_id and config_id are always present.

  • Run-Space Config ID shows the run-space plan fingerprint if a run_space section exists in the YAML, otherwise displays none.

  • Required Context Keys lists all keys that must be provided in the initial payload context, sorted alphabetically.

Extended mode (--extended)

Appends a per-node table after the concise output:

Nodes:
- UUID: <node_uuid>
  Role: DataOperation
  FQCN: package.module.ClassName
  Node Semantic ID: <semantic_id or "none">
  Sweep:
    parameters_sig: arg1, arg2
    variables_sig: var1, var2
    mode: combinatorial
    broadcast: false
    collection: package.CollectionClass

For nodes with derive.parameter_sweep metadata, the sweep summary includes:

  • parameters_sig — keys of swept parameters (not the full expressions or signatures)

  • variables_sig — keys of sweep variables

  • mode — sweep mode (e.g., combinatorial, zip)

  • broadcast — whether broadcast is enabled

  • collection — fully-qualified collection class name

Guarantees

  • The CLI never prints runtime IDs (plid-*, run-*, run_space_launch_id, etc.).

  • Raw sweep expressions (expr fields) are never shown—only sanitized signatures.

  • The output is deterministic and suitable for snapshot testing.

Invalid configuration parameters

Invalid configuration parameters are still reported after the identity block, and --strict continues to exit non-zero when invalid parameters are present.