Semantiva Studio Viewer

The Studio Viewer renders pipeline YAML as an interactive diagram and can browse installed components. It is read-only and designed for understanding, review, and sharing.

Quick Start

Visualize a pipeline

semantiva-studio-viewer serve-pipeline my_pipeline.yaml --port 8000
# then open http://127.0.0.1:8000

Export a standalone HTML

semantiva-studio-viewer export-pipeline my_pipeline.yaml --output pipeline_diagram.html
# open pipeline_diagram.html in any browser, no server needed

Browse components (if available)

semantiva-studio-viewer export-components --output semantiva_components.html
semantiva-studio-viewer serve-components semantiva_components.ttl --port 8001
# then open http://127.0.0.1:8001

See also: * Pipelines in Semantiva — how pipelines are defined and executed * Step Evidence Record (SER) v0 — draft — how to enable and read execution traces * Extending Semantiva (Registries & Extensions) — extending Semantiva and generating component sets

Modes & Controls

Viewer supports two modes:

  • Pipeline Visualization — render a single pipeline YAML as an interactive DAG. Click a node to view its details (processor class, parameters, ports, identities).

  • Component Browser — explore installed components (types, processors), organized by categories. Click items to view metadata and docstrings.

Basic controls (typical web-graph UX):

  • Pan: click-drag canvas

  • Zoom: mouse wheel / trackpad pinch

  • Select: click a node

  • Focus: double-click to center on a node (if supported)

Export & Share

Use export-pipeline to create a standalone HTML file that preserves pan/zoom and click-to-inspect interactions. No server required.

semantiva-studio-viewer export-pipeline my_pipeline.yaml --output pipeline_diagram.html

Share the HTML via email, internal portals, or attach it to reports. The export does not contain live data or runtime state—only static metadata from the pipeline definition and component docstrings.

Trace Inspection

The Viewer renders the canonical graph. To inspect execution traces alongside the diagram:

  1. Open your pipeline YAML in the Viewer.

  2. Click a node to see its details (including node_uuid).

  3. Open the corresponding *.ser.jsonl trace file and filter SER records by ids.node_id matching that node_uuid to review timings, checks, or errors for the selected node. Studio overlays are built directly from SER.

The node side panel groups the built-in pre/post checks with PASS/WARN/FAIL badges and exposes the environment pins as a compact key/value table (with copy-to-clipboard support). No YAML editing is required—everything is driven by the SER payloads.

See Step Evidence Record (SER) v0 — draft for the record schema and Trace ↔ Graph Alignment for identity guarantees.

Positional Binding (node_uuid)

Every node shown in the Viewer includes its positional identity, node_uuid, derived from the canonical GraphV1. This identity is:

  • Deterministic for the same canonical spec (formatting changes do not affect it).

  • Comparable across runs (join with trace events).

  • Stable for documentation and audits.

For more on identity, see Canonical Graph Builder.

Limitations

  • Read-only: the Viewer does not edit pipeline content.

  • No live runtime state: values are not streamed into the diagram.

Troubleshooting

Viewer doesn’t start / port in use Try a different port: --port 8002

Command not found Ensure the package is installed in the active environment: pip install semantiva-studio-viewer

Blank diagram Validate the YAML first: semantiva inspect pipeline.yaml --extended. Fix reported errors, then re-open in the Viewer.

Component browser: where does the TTL come from? Export it first: semantiva-studio-viewer export-components --output semantiva_components.ttl. See Extending Semantiva (Registries & Extensions) for extension discovery/registration.

Inspection schema note (GUI)

Each node record now includes:

  • invalid_parameters — list of {name, reason}

  • is_configuration_valid — false if invalid parameters exist

  • checks.why_run.pre / checks.why_ok.post — rendered as grouped check badges

  • checks.why_ok.env — environment pins table for reproducibility context

These allow the viewer to flag and annotate misconfigured nodes precisely.

Large Graphs

For very large pipelines:

  • Prefer generating a filtered/simplified YAML when inspecting specific areas.

  • Use search/filter (if available) to focus on relevant processors.

  • Export to HTML and share a focused subset for reviews.

See also