Skip to main content

aip_sdk.traces

Passive agent-trace ingestion and ground truth.

Land passively-collected agent traces into an AIP dataset — either by posting the trace payloads inline, or by triggering a pull from a saved object-store connection. Ingestion runs asynchronously; the returned run object carries the run status and, once complete, the dataset version the traces landed in. Rows that fail to land are recorded as drops you can inspect for diagnostics.

A landed version carries only what your telemetry emitted, so a metric needing a reference answer reports OP_MISSING_COLUMNS against it. Attach that reference answer with attach_ground_truth(), read back what a version carries with get_ground_truth(), and choose which version metrics score with promote_trace_version().

aip_sdk.traces.GROUND_TRUTH_FILE_SUFFIXES​

aip_sdk.traces.GROUND_TRUTH_FILE_SUFFIXES = ('.csv', '.json', '.jsonl')

No docstring is defined in the source.

aip_sdk.traces.INGEST_CONVENTIONS​

aip_sdk.traces.INGEST_CONVENTIONS = ('openinference', 'genai', 'langsmith')

No docstring is defined in the source.

aip_sdk.traces.MAX_DROPS_PER_PAGE​

aip_sdk.traces.MAX_DROPS_PER_PAGE = 2000

No docstring is defined in the source.

aip_sdk.traces.MAX_GROUND_TRUTH_ROWS_PER_PAGE​

aip_sdk.traces.MAX_GROUND_TRUTH_ROWS_PER_PAGE = 2000

No docstring is defined in the source.

aip_sdk.traces.RETENTION_DAYS​

aip_sdk.traces.RETENTION_DAYS = (7, 30, 90)

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion​

aip_sdk.traces.TraceCurrentVersion

The trace dataset version metrics score, after choosing it.

aip_sdk.traces.TraceCurrentVersion.dataset_id​

aip_sdk.traces.TraceCurrentVersion.dataset_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion.dataset_version_id​

aip_sdk.traces.TraceCurrentVersion.dataset_version_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion.is_golden​

aip_sdk.traces.TraceCurrentVersion.is_golden: bool

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion.model_config​

aip_sdk.traces.TraceCurrentVersion.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion.stage​

aip_sdk.traces.TraceCurrentVersion.stage: str

No docstring is defined in the source.

aip_sdk.traces.TraceCurrentVersion.version​

aip_sdk.traces.TraceCurrentVersion.version: int

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason​

aip_sdk.traces.TraceDropReason

Why a record failed to land — a closed set, so every case can be handled.

At TraceDropStage.PULL: DECODE_ERROR (the source bytes were not readable as trace data) and FRAME_UNSUPPORTED (readable, but not a shape spans can be read out of). At TraceDropStage.CONVERT: NO_CONVENTION (the record matched none of the source conventions — the export is what has to change), NO_HANDLER (the named ingest_convention is one this platform release cannot convert, which drops every record in the batch — land without naming one to auto-detect instead), CONVENTION_MISMATCH (the named ingest_convention doesn't match this record's shape — the forced convention is wrong for the payload), and HANDLER_ERROR (the record matched a convention but could not be converted; TraceDropRecord.detail says what failed).

aip_sdk.traces.TraceDropReason.CONVENTION_MISMATCH​

aip_sdk.traces.TraceDropReason.CONVENTION_MISMATCH = 'convention_mismatch'

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason.DECODE_ERROR​

aip_sdk.traces.TraceDropReason.DECODE_ERROR = 'decode_error'

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason.FRAME_UNSUPPORTED​

aip_sdk.traces.TraceDropReason.FRAME_UNSUPPORTED = 'frame_unsupported'

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason.HANDLER_ERROR​

aip_sdk.traces.TraceDropReason.HANDLER_ERROR = 'handler_error'

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason.NO_CONVENTION​

aip_sdk.traces.TraceDropReason.NO_CONVENTION = 'no_convention'

No docstring is defined in the source.

aip_sdk.traces.TraceDropReason.NO_HANDLER​

aip_sdk.traces.TraceDropReason.NO_HANDLER = 'no_handler'

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord​

aip_sdk.traces.TraceDropRecord

A single input record that failed to land, with the stage and reason it was dropped.

stage and reason are closed enumerations — match on a member rather than comparing strings, though both are StrEnum\ s so an existing string comparison keeps working. record_id can be None at TraceDropStage.PULL, where a record may be lost before it is identifiable — source_uri names where it came from and is the only handle on it.

aip_sdk.traces.TraceDropRecord.detail​

aip_sdk.traces.TraceDropRecord.detail: str = ''

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord.model_config​

aip_sdk.traces.TraceDropRecord.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord.reason​

aip_sdk.traces.TraceDropRecord.reason: TraceDropReason

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord.record_id​

aip_sdk.traces.TraceDropRecord.record_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord.source_uri​

aip_sdk.traces.TraceDropRecord.source_uri: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceDropRecord.stage​

aip_sdk.traces.TraceDropRecord.stage: TraceDropStage

No docstring is defined in the source.

aip_sdk.traces.TraceDropStage​

aip_sdk.traces.TraceDropStage

The boundary a record was dropped at.

PULL is reading the source data, before a record is recognised as a span — so a pull drop is attributable to a source object rather than to a record id. CONVERT is mapping a recognised record onto the canonical trace model, one record at a time.

aip_sdk.traces.TraceDropStage.CONVERT​

aip_sdk.traces.TraceDropStage.CONVERT = 'convert'

No docstring is defined in the source.

aip_sdk.traces.TraceDropStage.PULL​

aip_sdk.traces.TraceDropStage.PULL = 'pull'

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruth​

aip_sdk.traces.TraceGroundTruth

The ground truth a dataset version carries.

columns and row_count describe the whole artifact rather than the returned page, so checking which columns a version carries never requires paging.

aip_sdk.traces.TraceGroundTruth.columns​

aip_sdk.traces.TraceGroundTruth.columns: list[str] = Field(default_factory=list[str])

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruth.dataset_version_id​

aip_sdk.traces.TraceGroundTruth.dataset_version_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruth.model_config​

aip_sdk.traces.TraceGroundTruth.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruth.row_count​

aip_sdk.traces.TraceGroundTruth.row_count: int = 0

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruth.rows​

aip_sdk.traces.TraceGroundTruth.rows: list[TraceGroundTruthRow] = Field(default_factory=list[TraceGroundTruthRow])

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthRow​

aip_sdk.traces.TraceGroundTruthRow

One annotated identifier and the ground-truth values attached to it.

Each values entry is the stored cell as the artifact encodes it — a JSON-encoded list, so a column attached as ["search"] reads back as '["search"]'; decode it with json.loads() rather than comparing against the list that was attached.

aip_sdk.traces.TraceGroundTruthRow.model_config​

aip_sdk.traces.TraceGroundTruthRow.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthRow.parent_id​

aip_sdk.traces.TraceGroundTruthRow.parent_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthRow.values​

aip_sdk.traces.TraceGroundTruthRow.values: dict[str, str] = Field(default_factory=dict[str, str])

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion​

aip_sdk.traces.TraceGroundTruthVersion

The version derived by attaching ground truth to a landed trace version.

dataset_version_id is a new version and the base is left untouched, and a migrated evaluation target gets a new ID — so scope everything downstream to dataset_version_id and migrated_partitions[].partition_id.

aip_sdk.traces.TraceGroundTruthVersion.base_dataset_version_id​

aip_sdk.traces.TraceGroundTruthVersion.base_dataset_version_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.created_at​

aip_sdk.traces.TraceGroundTruthVersion.created_at: datetime | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.dataset_id​

aip_sdk.traces.TraceGroundTruthVersion.dataset_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.dataset_version_id​

aip_sdk.traces.TraceGroundTruthVersion.dataset_version_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_columns​

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_columns: list[str] = Field(default_factory=list[str])

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_path​

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_path: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_row_count​

aip_sdk.traces.TraceGroundTruthVersion.ground_truth_row_count: int

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.migrated_id​

aip_sdk.traces.TraceGroundTruthVersion.migrated_id(partition_id: str) -> str

The id partition_id (from the base version) now has on this derived version.

Replaces inverting migrated_partitions into a lookup dict by hand for the common case of resolving one specific partition you already hold a reference to.

Parameters

  • partition_id str: A partition id from the version base_dataset_version_id carried, to resolve onto this derived version.

Returns

Raises

  • NotFoundError: If partition_id did not follow onto this version — either it was never one of the base's partitions, or it hit a name collision (the reason is included in the message).

aip_sdk.traces.TraceGroundTruthVersion.migrated_partitions​

aip_sdk.traces.TraceGroundTruthVersion.migrated_partitions: list[PartitionMigrationOutcome] = Field(default_factory=list[PartitionMigrationOutcome])

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.model_config​

aip_sdk.traces.TraceGroundTruthVersion.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.object_store_path​

aip_sdk.traces.TraceGroundTruthVersion.object_store_path: str | None = Field(default=None, validation_alias='minio_path')

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.replayed​

aip_sdk.traces.TraceGroundTruthVersion.replayed: bool = False

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.row_count​

aip_sdk.traces.TraceGroundTruthVersion.row_count: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.stage​

aip_sdk.traces.TraceGroundTruthVersion.stage: str

No docstring is defined in the source.

aip_sdk.traces.TraceGroundTruthVersion.unmigrated_partitions​

aip_sdk.traces.TraceGroundTruthVersion.unmigrated_partitions: list[PartitionMigrationOutcome]

The evaluation targets that did not follow the ground truth onto this version.

Empty in the ordinary case; a non-empty list is the only part of migrated_partitions needing action, and each entry's reason says what.

aip_sdk.traces.TraceGroundTruthVersion.version​

aip_sdk.traces.TraceGroundTruthVersion.version: int

No docstring is defined in the source.

aip_sdk.traces.TraceIngestDropPage​

aip_sdk.traces.TraceIngestDropPage

One page of an ingestion run's drop records, and how many of its drops can be read.

total_drops is how many records the run dropped; available is how many of them this endpoint can return. The two differ only for a run that landed nothing, which keeps a capped sample of each drop reason rather than every record — so available below total_drops means the drops you can read are examples, not the full set. items is the page itself, bounded by the limit you asked for.

aip_sdk.traces.TraceIngestDropPage.available​

aip_sdk.traces.TraceIngestDropPage.available: int

No docstring is defined in the source.

aip_sdk.traces.TraceIngestDropPage.items​

aip_sdk.traces.TraceIngestDropPage.items: list[TraceDropRecord]

No docstring is defined in the source.

aip_sdk.traces.TraceIngestDropPage.model_config​

aip_sdk.traces.TraceIngestDropPage.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceIngestDropPage.total_drops​

aip_sdk.traces.TraceIngestDropPage.total_drops: int

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun​

aip_sdk.traces.TraceIngestRun

The status and outcome of a trace-ingestion run.

run_status reports coarse progress and state the stage reached; check is_terminal rather than comparing them by hand. dataset_id and dataset_version_id are populated once the run has landed rows, and the drop counters break down how many input records were dropped and at which stage.

The drop counters say whether every record landed. The content counts describe where canonical content fields were populated among the records that did land, which the drop counters cannot express: a landing can have zero drops and still have no message, tool-call or document values anywhere in a trace. content_diagnostics states those observations in prose:

run = aip.land_traces(payloads, ingest_convention="openinference").wait_until_terminal()
for observation in run.content_diagnostics:
    print(observation)

These are descriptive, not a verdict. spans_without_content is routinely non-zero on a healthy trace, since a parent span often carries topology while its children carry the prompt and response; spans_with_unknown_kind counts spans no agent convention describes, such as HTTP or client instrumentation. To learn whether a specific metric can score a target, call get_partition_metric_availability().

The counts are None on runs that landed before they were measured, which is not the same as zero — an empty content_diagnostics alone does not distinguish "nothing to note" from "never measured", so check a count for None when that difference matters.

aip_sdk.traces.TraceIngestRun.buffer_id​

aip_sdk.traces.TraceIngestRun.buffer_id: str

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.completed_at​

aip_sdk.traces.TraceIngestRun.completed_at: datetime | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.content_diagnostics​

aip_sdk.traces.TraceIngestRun.content_diagnostics: list[str] = Field(default_factory=list[str])

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.content_traces​

aip_sdk.traces.TraceIngestRun.content_traces: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.convert_drops​

aip_sdk.traces.TraceIngestRun.convert_drops: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.created_at​

aip_sdk.traces.TraceIngestRun.created_at: datetime | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.dataset_id​

aip_sdk.traces.TraceIngestRun.dataset_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.dataset_version_id​

aip_sdk.traces.TraceIngestRun.dataset_version_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.drop_path​

aip_sdk.traces.TraceIngestRun.drop_path: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.error​

aip_sdk.traces.TraceIngestRun.error: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.failed​

aip_sdk.traces.TraceIngestRun.failed: bool

Whether the run finished unsuccessfully. error carries the reason.

aip_sdk.traces.TraceIngestRun.id​

aip_sdk.traces.TraceIngestRun.id: str

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.is_terminal​

aip_sdk.traces.TraceIngestRun.is_terminal: bool

Whether the run has finished, successfully or not, and will not change again.

aip_sdk.traces.TraceIngestRun.iter_drops​

aip_sdk.traces.TraceIngestRun.iter_drops(*, page_size: int = 500, client: APIClient | None = None) -> Iterator[TraceDropRecord]

Iterate every record this run failed to land, reading each drop's detail.

Pages are fetched lazily as the iterator is consumed, so a run that dropped as many records as it read is never materialised in full. A run that landed nothing yields a capped sample per drop reason rather than every record — compare what you consumed against total_drops, or call list_drops() for the two counts directly.

Parameters

  • page_size int: Records to fetch per request (1 to MAX_DROPS_PER_PAGE). Affects only request granularity, not the records yielded.
  • client APIClient | None: Optional API client. Defaults to whichever client fetched or created this run, not the session default.

Yields

Raises

aip_sdk.traces.TraceIngestRun.landed_rows​

aip_sdk.traces.TraceIngestRun.landed_rows: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.last_successful_state​

aip_sdk.traces.TraceIngestRun.last_successful_state: TraceIngestState

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.list_drops​

aip_sdk.traces.TraceIngestRun.list_drops(*, limit: int = 200, offset: int = 0, client: APIClient | None = None) -> TraceIngestDropPage

Read one page of the records this run failed to land.

Works whether or not the run landed a version, so it is what to reach for when failed is true and there is no dataset_version_id to read drops by. Prefer iter_drops() to walk every drop without paging by hand.

Parameters

  • limit int: Maximum records to return (1 to MAX_DROPS_PER_PAGE).
  • offset int: Number of records to skip, for pagination.
  • client APIClient | None: Optional API client. Defaults to whichever client fetched or created this run, not the session default.

Returns

  • TraceIngestDropPage: The page, alongside how many drops the run has and how many can be read.

Raises

aip_sdk.traces.TraceIngestRun.model_config​

aip_sdk.traces.TraceIngestRun.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.object_store_path​

aip_sdk.traces.TraceIngestRun.object_store_path: str | None = Field(default=None, validation_alias='minio_path')

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.project_id​

aip_sdk.traces.TraceIngestRun.project_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.pull_drops​

aip_sdk.traces.TraceIngestRun.pull_drops: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.run_status​

aip_sdk.traces.TraceIngestRun.run_status: TraceIngestStatus

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.spans_with_unknown_kind​

aip_sdk.traces.TraceIngestRun.spans_with_unknown_kind: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.spans_without_content​

aip_sdk.traces.TraceIngestRun.spans_without_content: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.state​

aip_sdk.traces.TraceIngestRun.state: TraceIngestState

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.sut_id​

aip_sdk.traces.TraceIngestRun.sut_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.total_drops​

aip_sdk.traces.TraceIngestRun.total_drops: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.total_in​

aip_sdk.traces.TraceIngestRun.total_in: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.traces_without_content​

aip_sdk.traces.TraceIngestRun.traces_without_content: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestRun.wait_until_terminal​

aip_sdk.traces.TraceIngestRun.wait_until_terminal(*, interval: float = 1.0, timeout: float = 60.0, client: APIClient | None = None) -> TraceIngestRun

Poll this run until it reaches a terminal state.

Parameters

  • interval float: Seconds between polls.
  • timeout float: Maximum seconds to wait.
  • client APIClient | None: Optional API client. Defaults to whichever client fetched or created this run (e.g. the one passed to land_traces()), not the session default — pass one explicitly only to poll with a different client.

Returns

Raises

  • TimeoutError: If the run has not reached a terminal state within timeout.
  • AuthError: If credentials are missing or invalid.
  • NotFoundError: If the run does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.TraceIngestRun.workspace_id​

aip_sdk.traces.TraceIngestRun.workspace_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceIngestState​

aip_sdk.traces.TraceIngestState

The stage a trace-ingestion run has durably reached.

A run advances PENDING → BUFFERED → CONVERTED → COMPLETED; a retry resumes from the last stage it completed rather than repeating finished work.

aip_sdk.traces.TraceIngestState.BUFFERED​

aip_sdk.traces.TraceIngestState.BUFFERED = 'BUFFERED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestState.COMPLETED​

aip_sdk.traces.TraceIngestState.COMPLETED = 'COMPLETED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestState.CONVERTED​

aip_sdk.traces.TraceIngestState.CONVERTED = 'CONVERTED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestState.FAILED​

aip_sdk.traces.TraceIngestState.FAILED = 'FAILED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestState.PENDING​

aip_sdk.traces.TraceIngestState.PENDING = 'PENDING'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestStatus​

aip_sdk.traces.TraceIngestStatus

Coarse progress of a trace-ingestion run.

aip_sdk.traces.TraceIngestStatus.COMPLETED​

aip_sdk.traces.TraceIngestStatus.COMPLETED = 'COMPLETED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestStatus.FAILED​

aip_sdk.traces.TraceIngestStatus.FAILED = 'FAILED'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestStatus.PENDING​

aip_sdk.traces.TraceIngestStatus.PENDING = 'PENDING'

No docstring is defined in the source.

aip_sdk.traces.TraceIngestStatus.RUNNING​

aip_sdk.traces.TraceIngestStatus.RUNNING = 'RUNNING'

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection​

aip_sdk.traces.TraceSourceConnection

A saved object-store connection traces can be pulled from.

Credential fields (access_key, secret_key, auth_header_value) are write-only: the platform masks them in responses, and they are additionally kept out of this object's repr so a credential can never surface in a log or traceback even if a response echoed one.

unusable_reason states why the connection's source is not one the platform may pull from — most often a bucket or prefix that was never allowed, on a connection saved before the platform validated the source at creation. It is None for a usable connection, and against a platform that validates at creation it is None on everything create_source_connection() returns. The remedy is to create a replacement naming an allowed source; the string is human-facing diagnostic text and its wording is not a contract to parse.

aip_sdk.traces.TraceSourceConnection.access_key​

aip_sdk.traces.TraceSourceConnection.access_key: str | None = Field(default=None, repr=False)

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.auth_header_name​

aip_sdk.traces.TraceSourceConnection.auth_header_name: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.auth_header_value​

aip_sdk.traces.TraceSourceConnection.auth_header_value: str | None = Field(default=None, repr=False)

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.auth_type​

aip_sdk.traces.TraceSourceConnection.auth_type: str

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.bucket​

aip_sdk.traces.TraceSourceConnection.bucket: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.config​

aip_sdk.traces.TraceSourceConnection.config: dict[str, Any] = Field(default_factory=dict)

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.created_at​

aip_sdk.traces.TraceSourceConnection.created_at: datetime | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.endpoint​

aip_sdk.traces.TraceSourceConnection.endpoint: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.id​

aip_sdk.traces.TraceSourceConnection.id: str

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.label​

aip_sdk.traces.TraceSourceConnection.label: str

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.model_config​

aip_sdk.traces.TraceSourceConnection.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.prefix​

aip_sdk.traces.TraceSourceConnection.prefix: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.project_id​

aip_sdk.traces.TraceSourceConnection.project_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.region​

aip_sdk.traces.TraceSourceConnection.region: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.retention_days​

aip_sdk.traces.TraceSourceConnection.retention_days: int | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.secret_key​

aip_sdk.traces.TraceSourceConnection.secret_key: str | None = Field(default=None, repr=False)

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.secure​

aip_sdk.traces.TraceSourceConnection.secure: bool = True

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.source_type​

aip_sdk.traces.TraceSourceConnection.source_type: str

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.sut_id​

aip_sdk.traces.TraceSourceConnection.sut_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.unusable_reason​

aip_sdk.traces.TraceSourceConnection.unusable_reason: str | None = None

No docstring is defined in the source.

aip_sdk.traces.TraceSourceConnection.workspace_id​

aip_sdk.traces.TraceSourceConnection.workspace_id: str | None = None

No docstring is defined in the source.

aip_sdk.traces.attach_ground_truth​

aip_sdk.traces.attach_ground_truth(version_id: str, file: str | Path | None = None, *, rows: Mapping[str, Mapping[str, Sequence[str]]] | None = None, data: bytes | None = None, filename: str | None = None, client: APIClient | None = None) -> TraceGroundTruthVersion

Attach ground truth to a landed trace version, deriving a new version from it.

Supply the ground truth exactly one way: file (a path to a .csv/.json/ .jsonl file), rows (an in-memory mapping), or data (raw bytes, which needs filename so the platform can read the format from its extension).

The base version is never mutated — the returned dataset_version_id is a new version carrying the ground truth, and it takes over as the version metrics score when the base was that version. Evaluation targets defined on the base are carried across with new IDs, reported per target in migrated_partitions.

Retries must re-submit against the same version_id as the first attempt: replay is keyed on the base, so re-uploading the same file against the version it just derived is a different request that merges to a no-op and still derives a version. Record the returned dataset_version_id as the result rather than using it as the next upload target.

Parameters

  • version_id str: Dataset version to attach the ground truth to.
  • file str | Path | None: Path to the ground-truth file, keyed by session_id (or trace_id).
  • rows Mapping[str, Mapping[str, Sequence[str]]] | None: Ground truth as identifier -> column -> values, serialised for you.
  • data bytes | None: Ground-truth file content, for a file you have already read or built.
  • filename str | None: Name for data, whose extension selects the format. Required with data and rejected with file/rows.
  • client APIClient | None: Optional API client.

Returns

Raises

  • InvalidArgumentError: If the ground truth is supplied more than one way or not at all, filename is missing or misplaced, a rows value is not a list of strings, the file cannot be read, or the format is not one of GROUND_TRUTH_FILE_SUFFIXES.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If the caller lacks editor rights on the version's workspace.
  • NotFoundError: If the dataset version does not exist.
  • UnprocessableEntityError: If the platform rejects the file — over the size limit, malformed, or keyed against identifiers this version does not have.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.create_source_connection​

aip_sdk.traces.create_source_connection(*, bucket: str, label: str = 'default', workspace_id: str | None = None, project_id: str | None = None, sut_id: str | None = None, prefix: str | None = None, endpoint: str | None = None, access_key: str | None = None, secret_key: str | None = None, secure: bool = True, region: str | None = None, retention_days: int | None = None, client: APIClient | None = None) -> TraceSourceConnection

Create a saved object-store connection traces can be pulled from.

An object store authenticates with an access_key/secret_key pair, which must be supplied together and only alongside an endpoint. Omit endpoint to pull from a bucket the platform is already configured for, in which case no per-connection credential or region applies. Credentials are stored write-only and are never returned in plaintext.

Parameters

  • bucket str: Object-store bucket to pull from.
  • label str: Human-readable label for the connection, unique within the workspace or project it is scoped to.
  • workspace_id str | None: Workspace the connection belongs to. If omitted and project_id is also omitted, falls back to the client's configured default workspace (aip.init(workspace_id=...) / AIP_WORKSPACE_ID). Pass this or project_id, not both: a project already determines its workspace.
  • project_id str | None: System-under-test's workspace project the connection is associated with.
  • sut_id str | None: System-under-test the pulled traces are attributed to.
  • prefix str | None: Key prefix within the bucket to scope the pull.
  • endpoint str | None: External object-store host, as host or host:port — without a scheme, path, or credentials. Omit it to pull from a platform-configured bucket.
  • access_key str | None: Object-store access key (write-only). Requires endpoint and secret_key.
  • secret_key str | None: Object-store secret key (write-only). Requires endpoint and access_key.
  • secure bool: Whether to connect to endpoint over HTTPS.
  • region str | None: Object-store region. Requires endpoint.
  • retention_days int | None: Retention window for pulled data — one of RETENTION_DAYS. When None, the platform default applies.
  • client APIClient | None: Optional API client.

Returns

Raises

  • NoWorkspaceSelectedError: If no workspace is passed and none is configured for the session.
  • InvalidArgumentError: If bucket is empty, retention_days is not a supported window, only one of access_key/secret_key is given, a credential or region is given without an endpoint, or both project_id and workspace_id are given — a project already determines its workspace.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If bucket, prefix, or endpoint names a source the platform may not pull from; the message names the constraint and the values that would satisfy it, so no connection is saved that cannot be landed from. Also raised, with an access message instead, if the caller lacks rights to create a connection in the workspace.
  • ConflictError: If a connection with this label already exists in the same scope.
  • UnprocessableEntityError: If the connection configuration is rejected by the platform.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.get_ground_truth​

aip_sdk.traces.get_ground_truth(version_id: str, *, limit: int = 200, offset: int = 0, client: APIClient | None = None) -> TraceGroundTruth

Read the ground truth a dataset version carries.

columns and row_count always describe the whole artifact, so read TraceGroundTruthVersion.ground_truth_columns or these fields to learn which columns exist rather than paging; prefer iter_ground_truth() to walk every row.

Parameters

  • version_id str: Dataset version to read.
  • limit int: Maximum annotated identifiers to return (1 to MAX_GROUND_TRUTH_ROWS_PER_PAGE).
  • offset int: Number of identifiers to skip, for pagination.
  • client APIClient | None: Optional API client.

Returns

  • TraceGroundTruth: The version's ground truth, with one page of rows ordered by identifier. A version
  • TraceGroundTruth: with none attached returns empty columns and rows rather than raising.

Raises

  • InvalidArgumentError: If limit or offset is out of range.
  • AuthError: If credentials are missing or invalid.
  • NotFoundError: If the dataset version does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.get_ingest_run​

aip_sdk.traces.get_ingest_run(run_id: str, *, client: APIClient | None = None) -> TraceIngestRun

Fetch the current status of a trace-ingestion run.

Parameters

  • run_id str: The ingestion run ID returned by land_traces().
  • client APIClient | None: Optional API client.

Returns

  • TraceIngestRun: The ingestion run, including its latest run_status and landed dataset version.

Raises

  • AuthError: If credentials are missing or invalid.
  • NotFoundError: If the run does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.iter_ground_truth​

aip_sdk.traces.iter_ground_truth(version_id: str, *, page_size: int = 500, client: APIClient | None = None) -> Iterator[TraceGroundTruthRow]

Iterate every annotated identifier on a dataset version.

Pages are fetched lazily as the iterator is consumed, so no page is held beyond the rows yielded from it. This bounds each response, not the platform's own read — the artifact is decoded whole to serve any page, and the upload size limit is what keeps that bounded.

Parameters

  • version_id str: Dataset version to read.
  • page_size int: Identifiers to fetch per request (1 to MAX_GROUND_TRUTH_ROWS_PER_PAGE). Affects only request granularity.
  • client APIClient | None: Optional API client.

Yields

Raises

aip_sdk.traces.iter_ingest_drops​

aip_sdk.traces.iter_ingest_drops(version_id: str, *, page_size: int = 500, client: APIClient | None = None) -> Iterator[TraceDropRecord]

Iterate every record dropped while landing traces into a dataset version.

Pages are fetched lazily as the iterator is consumed, so a version with many drops is never materialised in full. A failed ingestion can drop as many records as it read, which is why this is the default way to read them.

Parameters

  • version_id str: Dataset version ID the ingestion run landed into.
  • page_size int: Records to fetch per request (1 to MAX_DROPS_PER_PAGE). Affects only request granularity, not the records yielded.
  • client APIClient | None: Optional API client.

Yields

Raises

aip_sdk.traces.land_traces​

aip_sdk.traces.land_traces(payloads: list[dict[str, Any]], *, workspace_id: str | None = None, project_id: str | None = None, sut_id: str | None = None, ingest_convention: str | None = None, dataset_name: str | None = None, dataset_id: str | None = None, buffer_id: str | None = None, retention_days: int | None = None, trace_tags: Iterable[TagInput] | None = None, client: APIClient | None = None) -> TraceIngestRun

Trigger ingestion of inline trace payloads into a dataset.

Landing is asynchronous: this returns as soon as the run is accepted. Call TraceIngestRun.wait_until_terminal() on the result (or poll get_ingest_run() by hand) until run_status is terminal to learn the dataset version the traces landed in.

Parameters

  • payloads list[dict[str, Any]]: The raw trace payloads to ingest (e.g. OpenInference/gen_ai/LangSmith spans). Must be non-empty.
  • workspace_id str | None: Workspace to land the traces in. If omitted and project_id is also omitted, falls back to the client's configured default workspace (aip.init(workspace_id=...) / AIP_WORKSPACE_ID). Pass this or project_id, not both: a project already determines its workspace.
  • project_id str | None: Project to associate the landed dataset with.
  • sut_id str | None: System-under-test the traces were produced by.
  • ingest_convention str | None: Source convention to convert the payloads as — one of INGEST_CONVENTIONS, the set this SDK version knows. Naming it overrides detection, so a payload that is not in that convention is dropped rather than re-sniffed. Leave it None to auto-detect per record, which also handles a convention newer than this SDK version.
  • dataset_name str | None: Name for a new dataset to create for these traces.
  • dataset_id str | None: Existing dataset to append the traces to, instead of creating one.
  • buffer_id str | None: Idempotency key, scoped to the resolved workspace_id. Re-landing with the key of a completed run in the same workspace replays that run's outcome instead of duplicating rows; re-landing while the first run is still in flight raises ConflictError. Reusing a buffer_id across a change in which workspace it resolves to (e.g. setting AIP_WORKSPACE_ID for the first time) does not replay the earlier run, since the pair no longer matches.
  • retention_days int | None: Retention window for the raw landed data — one of RETENTION_DAYS. When None, the platform default applies.
  • trace_tags Iterable[TagInput] | None: Optional trace tags to attach to the landed traces, as TraceTagUpsert instances or equivalent dicts.
  • client APIClient | None: Optional API client.

Returns

Raises

  • NoWorkspaceSelectedError: If no workspace is passed and none is configured for the session.
  • InvalidArgumentError: If payloads is empty, ingest_convention is not a recognised convention, retention_days is not a supported window, an trace_tags entry is malformed or the per-request limit is exceeded, or both project_id and workspace_id are given — a project already determines its workspace.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If workspace_id (or the configured default) names a workspace the caller is not a member of.
  • NotFoundError: If dataset_id names no dataset in the landing workspace or project.
  • APIError: If project_id names no project in a workspace the caller belongs to.
  • ConflictError: If a run for buffer_id is already in flight.
  • UnprocessableEntityError: If the payloads or arguments are rejected by the platform.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.land_traces_from_connection​

aip_sdk.traces.land_traces_from_connection(connection_id: str, *, client: APIClient | None = None) -> TraceIngestRun

Trigger ingestion by pulling traces from a saved object-store connection.

Parameters

  • connection_id str: ID of the source connection to pull from.
  • client APIClient | None: Optional API client.

Returns

Raises

aip_sdk.traces.list_ingest_drops​

aip_sdk.traces.list_ingest_drops(version_id: str, *, limit: int = 200, offset: int = 0, client: APIClient | None = None) -> list[TraceDropRecord]

List the records dropped while landing traces into a dataset version.

Prefer iter_ingest_drops() to walk every drop without paging by hand.

Parameters

  • version_id str: Dataset version ID the ingestion run landed into.
  • limit int: Maximum records to return (1 to MAX_DROPS_PER_PAGE).
  • offset int: Number of records to skip, for pagination.
  • client APIClient | None: Optional API client.

Returns

  • list[TraceDropRecord]: One page of drop records for the version, oldest first. A page shorter than
  • list[TraceDropRecord]: limit means there are no further records.

Raises

  • InvalidArgumentError: If limit or offset is out of range.
  • AuthError: If credentials are missing or invalid.
  • NotFoundError: If the dataset version does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.traces.list_source_connections​

aip_sdk.traces.list_source_connections(*, client: APIClient | None = None, workspace_id: str | None = None, all_workspaces: bool = False) -> list[TraceSourceConnection]

List saved object-store connections traces can be pulled from.

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

  • client APIClient | None: Optional API client.
  • workspace_id str | None: Return only connections saved in this workspace.
  • all_workspaces bool: Read across every workspace you can access.

Returns

  • list[TraceSourceConnection]: The available source connections, with credential fields masked.

Raises

aip_sdk.traces.promote_trace_version​

aip_sdk.traces.promote_trace_version(version_id: str, *, client: APIClient | None = None) -> TraceCurrentVersion

Choose which version of a trace dataset its metrics score, stepping back whichever was.

Attaching ground truth already hands currency to the version it derives, so this is for the cases that are not that — going back to the un-annotated version, or selecting a derivation built from a version that was not current at the time.

Parameters

  • version_id str: Dataset version to make current.
  • client APIClient | None: Optional API client.

Returns

Raises