context.viz() – WebUI Visualization API

The visualization service offers a convenient way to log data from agents into persistent storage. It is typically used in conjunction with AG's WebUI to automatically visualize each run. For manual generation of visualization data, it is recommended to use the corresponding Python package.

---

1. Data Visualization

scalar(track_id, *, step, value, ...)

Record a single scalar value for visualization in the Aethergraph UI.

This method standardizes the event format, auto-fills provenance fields, and dispatches the scalar data to the configured storage backend.

Examples:

Basic usage to log a loss metric:

await context.viz().scalar("loss", step=iteration, value=loss)

Logging a scalar with extra metadata and custom tags:

await context.viz().scalar(
    "accuracy",
    step=42,
    value=0.98,
    figure_id="metrics",
    meta={"model": "resnet"},
    tags=["experiment:baseline"]
)

Parameters:

Name	Type	Description	Default
track_id	str	Unique identifier for the scalar track (e.g., "loss").	required
step	int	Integer step or iteration number for the data point.	required
value	float	The scalar value to record (float).	required
figure_id	str | None	Optional figure grouping for UI display.	None
mode	VizMode	Storage mode, typically "append".	'append'
meta	dict[str, Any] | None	Optional dictionary of extra metadata.	None
tags	list[str] | None	Optional list of string labels. The tag "type:scalar" is automatically appended.	None

Returns:

Type	Description
None	None. The event is persisted for later visualization.

vector(track_id, *, step, values, ...)

Record a single vector (1D array) for visualization in the Aethergraph UI.

This method standardizes the event format, auto-fills provenance fields, and dispatches the vector data to the configured storage backend.

Examples:

Basic usage to log a vector:

await context.viz().vector("embedding", step=iteration, values=[0.1, 0.2, 0.3])

Logging a vector with extra metadata and custom tags:

await context.viz().vector(
    "features",
    step=42,
    values=[1.0, 2.5, 3.7],
    figure_id="feature_tracks",
    meta={"source": "encoder"},
    tags=["experiment:baseline"]
)

Parameters:

Name	Type	Description	Default
track_id	str	Unique identifier for the vector track (e.g., "embedding").	required
step	int	Integer step or iteration number for the data point.	required
values	Sequence[float]	Sequence of float values representing the vector.	required
figure_id	str | None	Optional figure grouping for UI display.	None
mode	VizMode	Storage mode, typically "append".	'append'
meta	dict[str, Any] | None	Optional dictionary of extra metadata.	None
tags	list[str] | None	Optional list of string labels. The tag "type:vector" is automatically appended.	None

Returns:

Type	Description
None	None. The event is persisted for later visualization.

matrix(track_id, *, step, matrix, ...)

Record a single matrix (2D array) for visualization in the Aethergraph UI.

This method standardizes the event format, auto-fills provenance fields, and dispatches the matrix data to the configured storage backend.

Examples:

Basic usage to log a matrix:

await context.viz().matrix("confusion", step=iteration, matrix=[[1, 2], [3, 4]])

Logging a matrix with extra metadata and custom tags:

await context.viz().matrix(
    "heatmap",
    step=42,
    matrix=[[0.1, 0.2], [0.3, 0.4]],
    figure_id="metrics",
    meta={"source": "model"},
    tags=["experiment:baseline"]
)

Parameters:

Name	Type	Description	Default
track_id	str	Unique identifier for the matrix track (e.g., "confusion").	required
step	int	Integer step or iteration number for the data point.	required
matrix	Sequence[Sequence[float]]	Sequence of sequences of float values representing the 2D matrix.	required
figure_id	str | None	Optional figure grouping for UI display.	None
mode	VizMode	Storage mode, typically "append".	'append'
meta	dict[str, Any] | None	Optional dictionary of extra metadata.	None
tags	list[str] | None	Optional list of string labels. The tag "matrix" is automatically appended.	None

Returns:

Type	Description
None	None. The event is persisted for later visualization.

2. Artifact Visualization (image etc.)

image_from_artifact(track_id, *, step, artifact, ...)

Record a reference to an existing image Artifact for visualization in the Aethergraph UI.

This method standardizes the event format, auto-fills provenance fields, and dispatches the image reference to the configured storage backend.

Examples:

Basic usage to log an image artifact:

await context.viz().image_from_artifact(
    "design_shape",
    step=17,
    artifact=artifact,
    figure_id="design"
)

Logging an image with extra metadata and custom tags:

await context.viz().image_from_artifact(
    "output_frame",
    step=42,
    artifact=artifact,
    figure_id="frames",
    meta={"source": "simulation"},
    tags=["experiment:baseline"]
)

Parameters:

Name	Type	Description	Default
track_id	str	Unique identifier for the image track (e.g., "design_shape").	required
step	int	Integer step or iteration number for the data point.	required
artifact	Artifact	The Artifact object referencing the stored image.	required
figure_id	str | None	Optional figure grouping for UI display.	None
mode	VizMode	Storage mode, typically "append".	'append'
meta	dict[str, Any] | None	Optional dictionary of extra metadata.	None
tags	list[str] | None	Optional list of string labels. The tag "image" is automatically appended.	None

Returns:

Type	Description
None	None. The event is persisted for later visualization.

image_from_bytes(track_id, *, step, data, ...)

Save image bytes as an Artifact and log a visualization event.

This convenience method is accessed via context.viz().image_from_bytes(...) and is used by the Aethergraph UI to persist image data to storage. It stores the image as an Artifact using the configured ArtifactFacade, then logs a visualization event referencing the saved artifact.

Examples:

Saving a PNG image to the current visualization track:

await context.viz().image_from_bytes(
    track_id="experiment-123",
    step=42,
    data=image_bytes,
    mime="image/png",
    labels={"type": "output", "stage": "inference"},
    tags=["result", "png"]
)

Saving an image with custom metadata and figure association:

await context.viz().image_from_bytes(
    track_id="demo-track",
    step=7,
    data=img_bytes,
    figure_id="fig-1",
    meta={"caption": "Sample output"},
    mode="replace"
)

Parameters:

Name	Type	Description	Default
track_id	str	The identifier for the visualization track to associate with the image.	required
step	int	The step or index within the track for this image.	required
data	bytes	Raw image bytes to be saved.	required
mime	str	The MIME type of the image (default: "image/png").	'image/png'
kind	str	The artifact kind (default: "image").	'image'
figure_id	str | None	Optional identifier for the figure this image belongs to.	None
mode	VizMode	Visualization mode, e.g., "append" or "replace".	'append'
labels	dict[str, Any] | None	Optional dictionary of labels to attach to the artifact.	None
meta	dict[str, Any] | None	Optional dictionary of metadata for the visualization event.	None
tags	list[str] | None	Optional list of string tags for categorization.	None

Returns:

Name	Type	Description
Artifact	Artifact	The persisted Artifact object representing the saved image.

Notes

• This method requires that self.artifacts is set to an ArtifactFacade instance.
• The saved artifact is automatically linked to the visualization event.
• To change the name of the saved artifact in UI, use labels to set a "filename" label.