API: Visualization Package
Visualization contracts represent UI-agnostic output artifacts and metadata. Adapters can render them in Streamlit, notebooks, CLIs, services, or files.
ArtifactRole
Bases: StrEnum
Semantic role used by UIs and exporters to place artifacts correctly.
Roles are presentation hints. They do not change artifact data semantics.
VisualArtifact
dataclass
Bases: ABC
Base contract for UI-agnostic presentation artifacts.
Visual artifacts are immutable values returned by visualizers and exporters. They describe what should be rendered or persisted without assuming a specific UI framework.
Attributes:
| Name | Type | Description |
|---|---|---|
artifact_id |
str
|
Stable id for UI diffing, downloads, and materialization caching. |
kind |
str
|
Artifact kind string such as |
role |
ArtifactRole | str
|
Semantic placement hint for adapters. |
title |
str | None
|
Optional display title. |
description |
str | None
|
Optional explanatory text. |
metadata |
Mapping[str, Any]
|
JSON-like metadata for adapters and diagnostics. |
ImageArtifact
dataclass
Bases: VisualArtifact
In-memory image artifact ready for rendering or persistence.
Use this for small images. Large images should generally be written through a file-backed or deferred artifact strategy.
VideoArtifact
dataclass
Bases: VisualArtifact
In-memory video artifact ready for UI playback or persistence.
This value enforces a hard byte limit to protect UI and API adapters from accidentally carrying large encoded videos in memory.
VideoFileArtifact
dataclass
Bases: VisualArtifact
File-backed video artifact that avoids keeping encoded bytes in memory.
The path must exist at construction time and point to a non-empty file.
DeferredVideoArtifact
dataclass
Bases: VisualArtifact
Lazy video artifact that renders to disk only when a consumer materializes it.
The render callback receives the target output path and must write a complete video file there. This keeps expensive annotated-video generation outside the main pipeline execution path and avoids in-memory MP4 buffering.
materialize
materialize(output_dir: Path | str | None = None) -> Path
Render the video if needed and return the resulting file path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_dir
|
Path | str | None
|
Optional directory where the rendered video should be created. |
None
|
Returns:
| Type | Description |
|---|---|
Path
|
Path to the rendered video file. |
Notes
Repeated calls reuse the same file when it is still present. The lock prevents two UI refreshes from rendering the same expensive video at the same time.
TableArtifact
dataclass
Bases: VisualArtifact
Tabular artifact represented as column names and row mappings.
Rows are copied to dictionaries during construction so adapters can render a stable snapshot.
JsonArtifact
dataclass
TextArtifact
dataclass
Bases: VisualArtifact
Textual artifact with an explicit content type.
Markdown is the default content type because it renders well in docs, notebooks, and Streamlit-like adapters.
VisualizationContext
dataclass
Execution context passed to visualizers during artifact generation.
The context carries run metadata and render hints without coupling visualizers to a specific UI framework. Values are copied to dictionaries at construction time so visualizers receive a stable snapshot.
PipelineRunMetadata
dataclass
Execution metadata attached to completed pipeline outputs.
Metadata is intended for reproducibility, UI summaries, and integration diagnostics. Mappings are copied to dictionaries so consumers can inspect a stable snapshot of the completed run.
PipelineOutputs
dataclass
Immutable aggregate returned by completed pipeline runs.
PipelineOutputs is the handoff value for UI, API, notebook, and exporter
adapters. It keeps analytical results separate from final artifacts and
debug artifacts so presentation layers can decide what to show by default.
Attributes:
| Name | Type | Description |
|---|---|---|
results |
tuple[IData, ...]
|
Final analyzer results in analyzer order. |
final_artifacts |
tuple[VisualArtifact, ...]
|
Primary artifacts intended for normal users. |
debug_artifacts |
tuple[VisualArtifact, ...]
|
Diagnostic artifacts intended for inspection or troubleshooting. |
metadata |
PipelineRunMetadata
|
Execution metadata, plan, and reproducibility details. |
intermediate_frames |
IntermediateFrameArtifactCollection
|
Optional bounded intermediate-frame debug collection. |
artifact_count
property
artifact_count: int
Return final plus debug artifact count for monitoring summaries.