aip_sdk.EmbeddingsHandle

aip_sdk.EmbeddingsHandle(run: Run)

Read access to one run's embedding coordinates.

Reached as Run.embeddings, never constructed directly. Coordinates live in the run's own output Parquet, so reading them needs no separate request and no high-dimensional vector download — the platform persists the 2D layout, which is what a plot consumes.

Shares Run.output()'s download cache, so run.output() followed by run.embeddings.coordinates costs one download rather than two.

The cache does not follow the run's state. A read only succeeds once the run has output at all — an unfinished run raises RunNotCompleteError rather than caching anything — but a run whose output is rewritten afterwards (a re-scored run, say) still serves the frame from the first read. Call refresh() to discard it.

aip_sdk.EmbeddingsHandle.attach_to

aip_sdk.EmbeddingsHandle.attach_to(pipeline_id: str) -> pd.DataFrame

Return the full run output with one pipeline's coordinates alongside.

The wide frame for plotting: every scored column the run produced, plus x, y, and cluster_id for pipeline_id.

Parameters

• pipeline_id str: Which pipeline's coordinates to attach.

Returns

• pd.DataFrame: The run output with three columns added. Row count and order are
• pd.DataFrame: unchanged.

Raises

• EmbeddingsError: If this run has no coordinates for that pipeline. A pipeline that failed is reported as failed, with its error.
• RunNotCompleteError: If the run has not finished.
• DownloadError: If the output download fails.

Examples:

plot_df = run.embeddings.attach_to("umap.text_qa.unsupervised")
plot_df.plot.scatter(x="x", y="y", c="llm.bleu", colormap="viridis")

aip_sdk.EmbeddingsHandle.coordinates

aip_sdk.EmbeddingsHandle.coordinates: pd.DataFrame

Tidy coordinate frame: row_id, pipeline_id, x, y, cluster_id.

One row per (row, pipeline) pair, carrying only the pipelines that produced coordinates. Filter on pipeline_id to plot one layout.

Returns

• pd.DataFrame: DataFrame with those five columns, empty when this run computed no
• pd.DataFrame: embeddings.

Raises

• EmbeddingsError: If the run output carries no embed column — the run was created without embeddings=.
• RunNotCompleteError: If the run has not finished.
• DownloadError: If the output download fails.

Examples:

coords = run.embeddings.coordinates
one = coords[coords.pipeline_id == "umap.text_qa.unsupervised"]

aip_sdk.EmbeddingsHandle.explorer

aip_sdk.EmbeddingsHandle.explorer(*, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> EmbeddingExplorer

Build an interactive EmbeddingExplorer.

Parameters

• row_preview RowPreviewFn | None: Optional callback mapping one selected row to an HTML tile. When omitted, lasso selection shows a compact table of row ids.
• gallery_preamble_html str | None: Optional HTML shown above the lasso gallery.

Returns

• EmbeddingExplorer: An explorer with panel(), show(), and write_html().

Raises

• EmbeddingsError: If this run carries no embedding coordinates.
• RunNotCompleteError: If the run has not finished.

aip_sdk.EmbeddingsHandle.for_pipeline

aip_sdk.EmbeddingsHandle.for_pipeline(pipeline_id: str) -> pd.DataFrame

Return just pipeline_id's coordinates.

Parameters

• pipeline_id str: A derived pipeline id, as listed by pipeline_ids.

Returns

• pd.DataFrame: The tidy coordinate rows for that pipeline.

Raises

• EmbeddingsError: If this run has no coordinates for that pipeline. A pipeline that failed is reported as failed, with its error.
• RunNotCompleteError: If the run has not finished.
• DownloadError: If the output download fails.

aip_sdk.EmbeddingsHandle.pipeline_ids

aip_sdk.EmbeddingsHandle.pipeline_ids: tuple[str, ...]

Ids of the pipelines that produced coordinates, ordered by id.

aip_sdk.EmbeddingsHandle.pipelines

aip_sdk.EmbeddingsHandle.pipelines: tuple[EmbeddingPipeline, ...]

Per-pipeline metadata for every configured embedding pipeline.

Returns

• One EmbeddingPipeline: class:~aip_sdk.embeddings.EmbeddingPipeline per pipeline in
• ...: embed.meta.pipelines, succeeded and failed alike, ordered by id.
• tuple[EmbeddingPipeline, ...]: Failed pipelines carry status='failed' and error; they have
• tuple[EmbeddingPipeline, ...]: no coordinates. Use pipeline_ids for the subset with
• tuple[EmbeddingPipeline, ...]: coordinates.

Raises

• EmbeddingsError: If the run output carries no embed column.
• RunNotCompleteError: If the run has not finished.
• DownloadError: If the output download fails.

aip_sdk.EmbeddingsHandle.refresh

aip_sdk.EmbeddingsHandle.refresh() -> None

Discard the cached run output so the next read downloads it again.

aip_sdk.EmbeddingsHandle.save_clusters

aip_sdk.EmbeddingsHandle.save_clusters(name: str, pipeline_id: str, *, version_id: str | None = None) -> SavedAssignedDimension

Save this run's cluster labels as a dataset-scoped assigned dimension.

Uses the run's dataset and id as provenance. Equivalent to save_clusters() with df=run.output() and source_run_id=run.id.

Parameters

• name str: Assigned dimension name — lowercase, underscores, no dots.
• pipeline_id str: Which pipeline's cluster labels to save.
• version_id str | None: Dataset version whose row ids are validated. Defaults to this run's dataset version.

Returns

• SavedAssignedDimension: The saved dimension, including coverage counts from the platform.

Raises

• EmbeddingsError: If this run has no coordinates for pipeline_id, or every row is unclustered noise.
• InvalidStateError: If the run is not associated with a dataset version.
• RunNotCompleteError: If the run has not finished.
• DownloadError: If the run output cannot be downloaded.
• UnprocessableEntityError: If the name or assignments fail platform validation.

Examples:

saved = run.embeddings.save_clusters(
    "clusters_semantic",
    "umap.text_qa.unsupervised",
)