semantiva-studio-viewer 0.2.0

A standalone package for interactive visualization of Semantiva pipelines and component hierarchies.

Semantiva Studio Viewer

Web-based viewers and exporters for Semantiva pipelines and component hierarchies.

Install

pip install semantiva-studio-viewer

This provides the semantiva-studio-viewer CLI.

---

CLI overview

semantiva-studio-viewer --help

Main commands:

• Pipeline inspection

  • serve-pipeline <pipeline.yaml> [--trace-jsonl <trace.jsonl>] [--host 127.0.0.1] [--port 8000]
  • export-pipeline <pipeline.yaml> <output.html> [--trace-jsonl <trace.jsonl>]

• Component inspection

  • serve-components <ontology.ttl> [--host 127.0.0.1] [--port 8000]
  • export-components <ontology.ttl> <output.html>

---

Pipeline inspector

Interactive view of a pipeline:

semantiva-studio-viewer serve-pipeline semantiva-imaging-pipeline.yaml --port 8000

Features:

• Dual-channel layout (data + context).
• Node details: parameters, types, provenance.
• Validation hints from Semantiva’s inspection system.

---

Adding execution traces

Overlay execution data from SER (Step Evidence Record) or legacy JSONL traces:

semantiva-studio-viewer serve-pipeline semantiva-imaging-pipeline.yaml \
  --trace-jsonl traces/execution.ser.jsonl

SER v1.1+ support (recommended):

• Full execution evidence: checks, IO deltas, summaries, timing
• Pre/post-execution validation results
• Policy compliance indicators
• Created/updated/read keys tracking
• Rich data type summaries with hashes

Legacy trace support (deprecated):

• Basic before/after/error events
• Timing and hash summaries
• Backward compatibility for older runs

Trace overlay adds:

• Per-node execution summaries (phases, timings, counts).
• SER-specific features: checks badges, IO delta summaries, policy results
• Deterministic node↔UUID binding (via positional identity or SER labels).
• Per-node event APIs: /api/trace/node/<uuid>?offset=&limit=
• Trace metadata at /api/trace/meta and aggregated stats at /api/trace/summary.

You can also export HTML with traces pre-baked:

semantiva-studio-viewer export-pipeline semantiva-imaging-pipeline.yaml \
  pipeline_with_trace.html --trace-jsonl traces/execution.ser.jsonl

Viewing Multiple Executions in One Trace File

Studio now supports JSON/JSONL files that contain multiple SER runs.

• Use --trace-jsonl to point to a combined file containing multiple execution runs.
• A Run dropdown appears in the header (format: run_id[:8] • started_at).
• Selecting a run updates the overlays and URL (?run=<id>).
• Node detail panels now show Run Args (e.g., run-space pins) and an Environment slice (including registry.fingerprint) when present in SER.

Multi-run file formats supported:

• JSONL format: One SER record per line, multiple runs mixed together
• JSON array format: Array of SER records from different runs

Example multi-run trace file (JSONL):

{"type":"ser","ids":{"run_id":"run-1","pipeline_id":"p"},"timing":{"start":"2025-01-01T00:00:01Z"},"status":"completed"}
{"type":"ser","ids":{"run_id":"run-2","pipeline_id":"p"},"timing":{"start":"2025-01-01T00:00:03Z"},"status":"completed"}
{"type":"ser","ids":{"run_id":"run-1","pipeline_id":"p"},"timing":{"start":"2025-01-01T00:00:05Z"},"status":"completed"}

Run-Space Launch Filtering

When traces contain run-space metadata (from parameter sweeps or fanout executions), the viewer provides:

• Run-Space dropdown: Filter runs by (launch_id, attempt) pair
  • All: Show all runs (default)
  • None: Show only runs without run-space decoration (orphan runs)
  • Launch entries: One option per unique (launch_id, attempt) with format:
    <launch_id> · attempt <N> · <combine_mode> · <total_runs>
• Run-Space Configuration Panel: When a specific launch is selected, the Pipeline Metadata panel shows:
  • Identities: Spec ID, Launch ID, Inputs ID (all copyable)
  • Configuration: Combine mode, planned/total runs, max runs limit
  • Input Fingerprints: Scrollable table with URI, digest, and size for each input
  • Planner Metadata: Optional collapsible JSON view of planner details
  • Empty states: Smart hints when "All" or "None" is selected
• Deep-link support: Share specific run-space views via URL
  ?launch=<launch_id>&attempt=<N>&run=<run_id>
• Backward compatible: Traces without run-space metadata work as before

Run-space fields in traces (optional, from pipeline_start events):

• run_space_launch_id: Unique identifier for the sweep/launch
• run_space_attempt: Attempt number for retry/variant tracking
• run_space_index: Position within the launch (for ordering)
• run_space_combine_mode: How parameters were combined (product, zip, etc.)

Run-space configuration (from run_space_start event):

• run_space_spec_id: Run-space specification identifier
• run_space_inputs_id: Input dataset identifier
• run_space_input_fingerprints: List of input file URIs, digests, and sizes
• run_space_planned_run_count: Expected number of runs
• run_space_max_runs_limit: Optional limit on execution
• summary.planner_meta: Optional planner-specific metadata

Run Args panel displays run-space parameters and other execution arguments:

• fanout.index, fanout.values, values_file_sha256, etc.
• Derived from checks.why_ok.args in SER records
• Includes JSON view toggle for detailed inspection

Environment panel shows execution environment details:

• Python version, platform, Semantiva version
• Registry fingerprint for reproducibility tracking
• Derived from checks.why_ok.env in SER records

API support for multi-run traces:

• New endpoint: GET /api/runs lists available runs with metadata
• All trace endpoints accept optional ?run=<run_id> parameter
• Backward compatible: single-run files work without any changes

---

Components browser

Explore Semantiva component ontologies:

semantiva-studio-viewer serve-components semantiva_components.ttl --port 8001

• Classes as nodes
• Subclass edges
• Metadata from docstrings, I/O types, parameters

Export standalone HTML:

semantiva-studio-viewer export-components semantiva_components.ttl components.html

---

Notes

• The inspector tolerates partially invalid configs to aid debugging.
• SER v1 format is used for execution traces.
• When traces are present, node→UUID mapping uses SER identity first, then positional identity (from canonical_spec); FQN fallbacks are used only if necessary.
• SER-only mode: If only SER data is available (no pipeline config), Studio can reconstruct basic graph topology from SER dependencies.upstream relationships.

---

License

Apache License, Version 2.0. See LICENSE.