aip_sdk.embeddings

Embedding projections: tune a config locally, then read a run's coordinates.

Two entry points, one config type. compute() runs the embedding pipelines in this process so a config can be tuned against data you already hold; the same EmbedProjectConfig then goes to aip.run(..., embeddings=config) and the platform persists the coordinates with the run output, where aip_sdk.run.EmbeddingsHandle.coordinates() reads them back.

Every result frame is long/tidy — one row per (row, pipeline) pair with row_id, pipeline_id, x, y, cluster_id — rather than one wide frame per pipeline, so a plot can facet or filter on pipeline_id without reshaping, and adding a pipeline to a config never changes the frame's columns.

SavedAssignedDimension is what save_clusters() returns after cluster labels are written to the platform's dataset-scoped assignment store. Saved dimensions resolve as assigned:<name> and can drive slice delta grouping (group_by=assigned:<name>) on any later run of the same dataset.

Requires the embeddings extra for config types and validation:

pip install 'aip-sdk[embeddings]'

Local compute() also needs the modality encoders your config names — install embeddings-compute for all modalities, or embeddings-text / embeddings-image for one family only:

pip install 'aip-sdk[embeddings,embeddings-compute]'
pip install 'aip-sdk[embeddings,embeddings-text]'   # text-only preview

Reading a completed run's coordinates needs no extra.

aip_sdk.embeddings.CLUSTER_ASSIGN_SOURCE_OP

aip_sdk.embeddings.CLUSTER_ASSIGN_SOURCE_OP = 'transform.embed_project'

No docstring is defined in the source.

aip_sdk.embeddings.COORDINATE_COLUMNS

aip_sdk.embeddings.COORDINATE_COLUMNS = ('row_id', 'pipeline_id', 'x', 'y', 'cluster_id')

No docstring is defined in the source.

aip_sdk.embeddings.EMBED_COLUMN

aip_sdk.embeddings.EMBED_COLUMN = 'embed'

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingComputeResult

aip_sdk.embeddings.EmbeddingComputeResult(coordinates: pd.DataFrame, pipelines: tuple[EmbeddingPipeline, ...])

Coordinates and per-pipeline diagnostics from one compute() call.

Attributes

• coordinates pd.DataFrame: Tidy frame with COORDINATE_COLUMNS, carrying only the pipelines that succeeded.
• pipelines tuple[EmbeddingPipeline, ...]: Every configured pipeline, succeeded and failed alike, so a caller can see what a config actually produced.

aip_sdk.embeddings.EmbeddingComputeResult.coordinates

aip_sdk.embeddings.EmbeddingComputeResult.coordinates: pd.DataFrame

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingComputeResult.failed

aip_sdk.embeddings.EmbeddingComputeResult.failed: tuple[EmbeddingPipeline, ...]

Pipelines that produced no coordinates, each carrying its error.

aip_sdk.embeddings.EmbeddingComputeResult.for_pipeline

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

Return just pipeline_id's coordinates, indexed by position.

Parameters

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

Returns

• pd.DataFrame: The subset of coordinates for that pipeline.

Raises

• EmbeddingsError: If no succeeded pipeline has that id.

aip_sdk.embeddings.EmbeddingComputeResult.pipeline_ids

aip_sdk.embeddings.EmbeddingComputeResult.pipeline_ids: tuple[str, ...]

Ids of the pipelines that produced coordinates.

aip_sdk.embeddings.EmbeddingComputeResult.pipelines

aip_sdk.embeddings.EmbeddingComputeResult.pipelines: tuple[EmbeddingPipeline, ...]

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingComputeResult.succeeded

aip_sdk.embeddings.EmbeddingComputeResult.succeeded: tuple[EmbeddingPipeline, ...]

Pipelines that produced coordinates.

aip_sdk.embeddings.EmbeddingPipeline

aip_sdk.embeddings.EmbeddingPipeline(pipeline_id: str, status: str, supervised: bool, supervision_column: str | None = None, trustworthiness: float | None = None, error: str | None = None)

One pipeline's outcome and diagnostics.

Attributes

• pipeline_id str: Derived id, <projection>.<embedding>.<label> — e.g. umap.text_qa.unsupervised. Derived from the pipeline's steps, so two configs naming the same steps produce the same id.
• status str: "succeeded" or "failed".
• supervised bool: Whether the projection was guided by a per-row score.
• supervision_column str | None: Column that guided it, or None when unsupervised.
• trustworthiness float | None: How faithfully the 2D layout preserves the high-dimensional neighbourhoods, in [0, 1]. None when the pipeline failed, and also None on a succeeded pipeline whose frame was too small for the score to be defined — the layout is still usable, only this diagnostic is absent.
• error str | None: Why the pipeline produced no coordinates, or None on success.

aip_sdk.embeddings.EmbeddingPipeline.error

aip_sdk.embeddings.EmbeddingPipeline.error: str | None = None

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingPipeline.pipeline_id

aip_sdk.embeddings.EmbeddingPipeline.pipeline_id: str

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingPipeline.status

aip_sdk.embeddings.EmbeddingPipeline.status: str

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingPipeline.succeeded

aip_sdk.embeddings.EmbeddingPipeline.succeeded: bool

Whether this pipeline produced coordinates.

aip_sdk.embeddings.EmbeddingPipeline.supervised

aip_sdk.embeddings.EmbeddingPipeline.supervised: bool

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingPipeline.supervision_column

aip_sdk.embeddings.EmbeddingPipeline.supervision_column: str | None = None

No docstring is defined in the source.

aip_sdk.embeddings.EmbeddingPipeline.trustworthiness

aip_sdk.embeddings.EmbeddingPipeline.trustworthiness: float | None = None

No docstring is defined in the source.

aip_sdk.embeddings.ID_COLUMNS

aip_sdk.embeddings.ID_COLUMNS = ('row_id', 'input_id', 'image_id')

No docstring is defined in the source.

aip_sdk.embeddings.JsonDict

aip_sdk.embeddings.JsonDict = dict[str, Any]

No docstring is defined in the source.

aip_sdk.embeddings.META_KEY

aip_sdk.embeddings.META_KEY = 'meta'

No docstring is defined in the source.

aip_sdk.embeddings.NOISE_LABEL

aip_sdk.embeddings.NOISE_LABEL = 'noise'

No docstring is defined in the source.

aip_sdk.embeddings.NO_EMBEDDINGS

aip_sdk.embeddings.NO_EMBEDDINGS = '__none__'

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig

aip_sdk.embeddings.RegisteredEmbeddingConfig(id: str, workspace_id: str, name: str, config: JsonDict, created_at: datetime, updated_at: datetime)

A workspace-scoped EmbedProjectConfig registered under a name.

aip_sdk.embeddings.RegisteredEmbeddingConfig.config

aip_sdk.embeddings.RegisteredEmbeddingConfig.config: JsonDict

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig.created_at

aip_sdk.embeddings.RegisteredEmbeddingConfig.created_at: datetime

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig.id

aip_sdk.embeddings.RegisteredEmbeddingConfig.id: str

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig.name

aip_sdk.embeddings.RegisteredEmbeddingConfig.name: str

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig.updated_at

aip_sdk.embeddings.RegisteredEmbeddingConfig.updated_at: datetime

No docstring is defined in the source.

aip_sdk.embeddings.RegisteredEmbeddingConfig.workspace_id

aip_sdk.embeddings.RegisteredEmbeddingConfig.workspace_id: str

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension

aip_sdk.embeddings.SavedAssignedDimension(id: str, name: str, authored_by: str, source_op: str | None, source_run_id: str | None, category_count: int, dataset_version_id: str, assigned_rows: int, total_rows: int, unassigned_rows: int)

A row_id -> category assignment persisted as a dataset-scoped assigned: dimension.

Attributes

• id str: Qualified dimension id, assigned:<name>.
• name str: Dimension name within the assigned namespace.
• authored_by str: How the assignment came about — clustering for a save from save_clusters(), user for one from save_dimension(). Metadata only: both resolve identically when grouping.
• source_op str | None: Op that produced the labels, when one did — transform.embed_project for a cluster save, absent for a user-authored one.
• source_run_id str | None: Run the labels were extracted from, when provided.
• category_count int: Distinct cluster labels saved.
• dataset_version_id str: Version the assignment was validated against.
• assigned_rows int: Rows that received a cluster label.
• total_rows int: Rows in the target version.
• unassigned_rows int: Version rows with no saved label.

aip_sdk.embeddings.SavedAssignedDimension.assigned_rows

aip_sdk.embeddings.SavedAssignedDimension.assigned_rows: int

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.authored_by

aip_sdk.embeddings.SavedAssignedDimension.authored_by: str

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.category_count

aip_sdk.embeddings.SavedAssignedDimension.category_count: int

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.dataset_version_id

aip_sdk.embeddings.SavedAssignedDimension.dataset_version_id: str

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.id

aip_sdk.embeddings.SavedAssignedDimension.id: str

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.name

aip_sdk.embeddings.SavedAssignedDimension.name: str

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.source_op

aip_sdk.embeddings.SavedAssignedDimension.source_op: str | None

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.source_run_id

aip_sdk.embeddings.SavedAssignedDimension.source_run_id: str | None

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.total_rows

aip_sdk.embeddings.SavedAssignedDimension.total_rows: int

No docstring is defined in the source.

aip_sdk.embeddings.SavedAssignedDimension.unassigned_rows

aip_sdk.embeddings.SavedAssignedDimension.unassigned_rows: int

No docstring is defined in the source.

aip_sdk.embeddings.attach_clusters

aip_sdk.embeddings.attach_clusters(df: pd.DataFrame, pipeline_id: str, id_column: str | None = None) -> pd.DataFrame

Return df with one pipeline's x, y, and cluster_id alongside.

The wide counterpart to flatten_embed_column(): for plotting a single layout coloured by a column the run already carries, one frame is easier to work with than a join.

Parameters

• df pd.DataFrame: A run-output frame carrying an embed column.
• pipeline_id str: Which pipeline's coordinates to attach.
• id_column str | None: Row-identity column. Defaults to the first of ID_COLUMNS present in df.

Returns

• pd.DataFrame: A copy of df with x, y, and cluster_id columns added. Row
• pd.DataFrame: count and row order are unchanged.

Raises

• EmbeddingsError: If df has no embed column, no row-identity column, or no coordinates for pipeline_id.

Examples:

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

aip_sdk.embeddings.compute

aip_sdk.embeddings.compute(df: pd.DataFrame, config: EmbedProjectConfig, available_metrics: list[str] | None = None, cache_dir: str | None = None) -> EmbeddingComputeResult

Run every configured embedding pipeline over df, in this process.

No platform run, no SUT inference, no scoring — this is the authoring loop for an embedding config: change a projection parameter, recompute, look at the layout. The config that produces a layout you want is then passed verbatim to aip.run(..., embeddings=config), which applies the same pipelines to a run's scored output.

Row order is preserved and row count is invariant: the coordinate for row i of df is the coordinate reported against that row's identity.

Parameters

• df pd.DataFrame: Rows to embed. Needs a row-identity column (see row_id_column()) plus whatever columns the configured embeddings read — prompt for text, image_path and label for image.
• config EmbedProjectConfig: The pipelines to run, and the embedding, projection, and clustering libraries they draw on.
• available_metrics list[str] | None: Per-row score columns a supervised pipeline may use. Supplies the columns for a expand_supervision_over_metrics whose own metrics is unset; without it, such an expansion contributes no pipelines.
• cache_dir str | None: Where to keep the embedding chunk cache. Defaults to a temporary directory removed when the call returns, on both the success and the failure path.

Returns

• An EmbeddingComputeResult: class:EmbeddingComputeResult whose coordinates carries the
• EmbeddingComputeResult: succeeded pipelines and whose pipelines describes all of them.

Raises

• EmbeddingsNotInstalledError: If the embeddings extra is not installed.
• EmbeddingsError: If df has no row-identity column, exceeds the config's row ceiling, or no pipeline produced coordinates.

Examples:

import aip_sdk as aip
from aip_embeddings_core import (
    ClusteringConfig,
    EmbeddingConfig,
    EmbeddingPipelineConfig,
    EmbedProjectConfig,
    ProjectionConfig,
)

config = EmbedProjectConfig(
    embeddings={"qa": EmbeddingConfig(modality="text", task_type="single_turn_llm")},
    projections={"unsup": ProjectionConfig(n_neighbors=8)},
    clusterings={"default": ClusteringConfig(min_cluster_size=5)},
    pipelines=[EmbeddingPipelineConfig(embedding="qa", projection="unsup", clustering="default")],
)
result = aip.embeddings.compute(df, config)
print(result.pipeline_ids)
result.coordinates.head()

aip_sdk.embeddings.flatten_embed_column

aip_sdk.embeddings.flatten_embed_column(df: pd.DataFrame, id_column: str | None = None) -> pd.DataFrame

Explode a run output's nested embed column into a tidy frame.

The persisted embed struct holds one entry per row, keyed by pipeline id, so reading it means walking rows and pipelines together. This does that walk and attaches each coordinate to its row's identity.

Parameters

• df pd.DataFrame: A run-output frame carrying an embed column, as returned by aip_sdk.run.Run.output().
• id_column str | None: Row-identity column to key coordinates by. Defaults to the first of ID_COLUMNS present in df.

Returns

• pd.DataFrame: Tidy frame with COORDINATE_COLUMNS. Empty (with those columns)
• pd.DataFrame: when the frame carries no coordinates.

Raises

• EmbeddingsError: If df has no embed column or no row-identity column.

Examples:

df = run.output()
coords = aip.embeddings.flatten_embed_column(df)
coords[coords.pipeline_id == "umap.text_qa.unsupervised"].head()

aip_sdk.embeddings.get

aip_sdk.embeddings.get(config_ref: str, *, workspace_id: str | None = None, client: APIClient | None = None) -> RegisteredEmbeddingConfig

Fetch a registered embedding config by id, or by name within one workspace.

The result can be passed straight to aip.run(..., embeddings=…) as a one-run override — no need to reach into .config.

Parameters

• config_ref str: The config's id, or its workspace-scoped name.
• workspace_id str | None: Which workspace to resolve a name in. Names are unique only within a workspace, so pass this whenever the same name may exist in several — including NO_EMBEDDINGS, which every workspace has. Not needed when config_ref is an id, or when you can see exactly one workspace.
• client APIClient | None: Optional pre-configured API client.

Returns

• RegisteredEmbeddingConfig: The registered config, carrying its id, name and timestamps.

Raises

• EmbeddingConfigNotFoundError: If no live config matches in a workspace the caller can see.
• ValidationError: If the name is ambiguous across workspaces the caller can see and no workspace_id was given. The message names the candidates.

aip_sdk.embeddings.list_embedding_configs

aip_sdk.embeddings.list_embedding_configs(page: int = 1, per_page: int = 100, *, workspace_id: str | None = None, client: APIClient | None = None, all_workspaces: bool = False) -> list[RegisteredEmbeddingConfig]

List registered embedding configs, newest first.

Reads your session's workspace unless you name one, and raises if none is set. Pass all_workspaces=True to read across every workspace you can access.

Parameters

• page int: 1-based page number.
• per_page int: Page size.
• workspace_id str | None: Restrict to one workspace.
• client APIClient | None: Optional pre-configured API client.
• all_workspaces bool: Read across every workspace you can access.

Returns

• list[RegisteredEmbeddingConfig]: The registered configs on the requested page.

Raises

• ForbiddenError: If workspace_id names a workspace the caller cannot access.
• InvalidArgumentError: If both workspace_id and all_workspaces are given.
• NoWorkspaceSelectedError: No workspace was passed, none is configured for the session, and all_workspaces was not set.

aip_sdk.embeddings.pipelines_from_embed_column

aip_sdk.embeddings.pipelines_from_embed_column(df: pd.DataFrame) -> tuple[EmbeddingPipeline, ...]

Read per-pipeline metadata out of a run output's embed column.

Provenance travels with the coordinates, so this needs no second request. meta.pipelines lists every configured pipeline — succeeded and failed. Coordinate struct keys list only the pipelines that produced coordinates, so the full set is the union of both when meta is present.

Parameters

• df pd.DataFrame: A run-output frame carrying an embed column.

Returns

• One EmbeddingPipeline: class:EmbeddingPipeline per configured pipeline, ordered by id.
• ...: Failed pipelines carry status='failed' and error; they have no
• tuple[EmbeddingPipeline, ...]: coordinates. Empty when the frame carries none.

Raises

• EmbeddingsError: If df has no embed column.

aip_sdk.embeddings.register

aip_sdk.embeddings.register(name: str, config: EmbedProjectConfig | dict[str, Any], *, workspace_id: str | None = None, client: APIClient | None = None) -> RegisteredEmbeddingConfig

Register an EmbedProjectConfig under a workspace-scoped name.

Parameters

• name str: Catalogue name — unique among live configs in the workspace.
• config EmbedProjectConfig | dict[str, Any]: The same EmbedProjectConfig used with aip.run(..., embeddings=config).
• workspace_id str | None: Workspace to register in. Falls back to the client's configured workspace (AIP_WORKSPACE_ID); a membership is never picked arbitrarily, so a caller with no configured workspace must pass one.
• client APIClient | None: Optional pre-configured API client.

Returns

• RegisteredEmbeddingConfig: The registered config, carrying the server-assigned id and timestamps.

Raises

• DuplicateEmbeddingConfigError: If the name is already taken in the workspace.
• NoWorkspaceSelectedError: If no workspace is given and none is configured for the session.
• InvalidArgumentError: If config is not a valid EmbedProjectConfig.

aip_sdk.embeddings.require_extra

aip_sdk.embeddings.require_extra() -> None

Raise unless local compute dependencies are installed.

Checks aip-embeddings-core ([embeddings]) and at least one modality package ([embeddings-compute], [embeddings-text], or [embeddings-image]). Core alone is enough for typed config authoring and read-back — call this only before compute().

Raises

• EmbeddingsNotInstalledError: If core or any modality package is missing.

Examples:

aip.embeddings.require_extra()  # fail now, not after loading 10GB of frames

aip_sdk.embeddings.row_id_column

aip_sdk.embeddings.row_id_column(df: pd.DataFrame) -> str

Return the name of df's row-identity column.

Looks for ID_COLUMNS in order — row_id, then the schema-specific input_id (text) and image_id (image).

Parameters

• df pd.DataFrame: Frame to inspect.

Returns

• str: The column name found.

Raises

• EmbeddingsError: If the frame carries none of them.

aip_sdk.embeddings.save_clusters

aip_sdk.embeddings.save_clusters(dataset: str, name: str, pipeline_id: str, *, df: pd.DataFrame | None = None, coordinates: pd.DataFrame | None = None, compute_result: EmbeddingComputeResult | None = None, source_run_id: str | None = None, version_id: str | None = None, client: APIClient | None = None) -> SavedAssignedDimension

Save one pipeline's cluster labels as a dataset-scoped assigned dimension.

Extracts row_id → cluster_id from embedding coordinates and calls POST /datasets/{id}/dimensions:assign with authored_by="clustering". The saved dimension resolves as assigned:<name> on every later run of the same dataset, so slice delta grouping can use group_by=assigned:<name>.

Unclustered rows are omitted from the assignment: HDBSCAN reports them as the label "noise", and a pipeline with clustering disabled as null. Both are dropped rather than saved, so they appear under missing: in join coverage rather than as a noise category.

Parameters

• dataset str: Dataset id, or "name@vN" to pin the validation version.
• name str: Assigned dimension name — lowercase, underscores, no dots.
• pipeline_id str: Which pipeline's cluster labels to save.
• df pd.DataFrame | None: Run output carrying a nested embed column. Mutually exclusive with coordinates= and compute_result=.
• coordinates pd.DataFrame | None: Tidy coordinate frame with COORDINATE_COLUMNS.
• compute_result EmbeddingComputeResult | None: Result of compute(); its coordinates are used.
• source_run_id str | None: Run the labels were extracted from — stored as metadata.
• version_id str | None: Dataset version whose row ids are validated. Defaults to the latest version. Mutually exclusive with a name@vN pin on dataset — passing both raises rather than silently choosing one.
• client APIClient | None: Optional pre-configured API client.

Returns

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

Raises

• EmbeddingsError: If no coordinate source is given, more than one is given, df carries no embed column, the coordinates frame is missing a required column, dataset is malformed, dataset and version_id= pin different versions, the pinned version does not exist, the pipeline has no cluster labels, a row carries conflicting labels, or every row is unclustered noise.
• AipError: If no client is given and none is configured.
• UnprocessableEntityError: If the name or assignments fail platform validation.
• NotFoundError: If the dataset does not exist.
• ConflictError: If concurrent saves of the same dimension cannot be serialised.

Examples:

df = run.output()
saved = aip.embeddings.save_clusters(
    dataset.id,
    "clusters_semantic",
    "umap.text_qa.unsupervised",
    df=df,
    source_run_id=run.id,
)
# Slice delta: group_by=saved.id