Skip to main content

aip_sdk.trace_models

Canonical agent-trace value objects shared across the trace-evaluation surface.

These types mirror the canonical trace vocabulary the platform resolves partitions, topology graphs, and trace tags against. They are the stable shapes returned by aip_sdk.partitions and aip_sdk.topology, and the selector shapes those modules accept.

kind/role/status are closed enumerations of the platform's canonical vocabulary: a value outside the enumeration is rejected, so a span carrying a kind added by a newer platform release needs an SDK upgrade to read. Unrecognised fields are kept.

aip_sdk.trace_models.CanonicalSession​

aip_sdk.trace_models.CanonicalSession

A session: the traces belonging to one conversation/thread.

aip_sdk.trace_models.CanonicalSession.model_config​

aip_sdk.trace_models.CanonicalSession.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSession.session_id​

aip_sdk.trace_models.CanonicalSession.session_id: str

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSession.traces​

aip_sdk.trace_models.CanonicalSession.traces: list[CanonicalTrace] = Field(default_factory=list[CanonicalTrace])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan​

aip_sdk.trace_models.CanonicalSpan

One span in the platform's canonical vocabulary.

aip carries skill-written fields already in canonical vocabulary, as a free-form map whose contents depend on the source trace. provenance maps a canonical field name to how that field was produced, so a caller can tell a losslessly-mapped value from one recovered out of an unstructured payload.

aip_sdk.trace_models.CanonicalSpan.aip​

aip_sdk.trace_models.CanonicalSpan.aip: dict[str, Any] = Field(default_factory=dict)

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.documents​

aip_sdk.trace_models.CanonicalSpan.documents: list[Document] = Field(default_factory=list[Document])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.end_ns​

aip_sdk.trace_models.CanonicalSpan.end_ns: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.error​

aip_sdk.trace_models.CanonicalSpan.error: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.input_messages​

aip_sdk.trace_models.CanonicalSpan.input_messages: list[Message] = Field(default_factory=list[Message])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.input_tokens​

aip_sdk.trace_models.CanonicalSpan.input_tokens: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.kind​

aip_sdk.trace_models.CanonicalSpan.kind: SpanKind

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.model​

aip_sdk.trace_models.CanonicalSpan.model: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.model_config​

aip_sdk.trace_models.CanonicalSpan.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.name​

aip_sdk.trace_models.CanonicalSpan.name: str

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.output_messages​

aip_sdk.trace_models.CanonicalSpan.output_messages: list[Message] = Field(default_factory=list[Message])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.output_tokens​

aip_sdk.trace_models.CanonicalSpan.output_tokens: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.parent_id​

aip_sdk.trace_models.CanonicalSpan.parent_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.provenance​

aip_sdk.trace_models.CanonicalSpan.provenance: dict[str, Provenance] = Field(default_factory=dict[str, Provenance])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.session_id​

aip_sdk.trace_models.CanonicalSpan.session_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.span_id​

aip_sdk.trace_models.CanonicalSpan.span_id: str

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.start_ns​

aip_sdk.trace_models.CanonicalSpan.start_ns: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.status​

aip_sdk.trace_models.CanonicalSpan.status: SpanStatus = SpanStatus.UNSET

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.step_index​

aip_sdk.trace_models.CanonicalSpan.step_index: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.tool_calls​

aip_sdk.trace_models.CanonicalSpan.tool_calls: list[ToolCall] = Field(default_factory=list[ToolCall])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalSpan.trace_id​

aip_sdk.trace_models.CanonicalSpan.trace_id: str

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalTrace​

aip_sdk.trace_models.CanonicalTrace

A trace: the tree of spans sharing one trace_id.

tags holds per-trace tags overlaid at read time (see aip_sdk.trace_tags).

aip_sdk.trace_models.CanonicalTrace.by_kind​

aip_sdk.trace_models.CanonicalTrace.by_kind(kind: SpanKind) -> list[CanonicalSpan]

Return this trace's spans of a given kind.

Parameters

  • kind SpanKind: The span kind to filter by.

Returns

  • list[CanonicalSpan]: The spans whose kind equals kind, in trace order.

aip_sdk.trace_models.CanonicalTrace.model_config​

aip_sdk.trace_models.CanonicalTrace.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalTrace.roots​

aip_sdk.trace_models.CanonicalTrace.roots() -> list[CanonicalSpan]

Return the trace's root spans (those with no parent).

Returns

  • list[CanonicalSpan]: The spans whose parent_id is None.

aip_sdk.trace_models.CanonicalTrace.spans​

aip_sdk.trace_models.CanonicalTrace.spans: list[CanonicalSpan] = Field(default_factory=list[CanonicalSpan])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalTrace.tags​

aip_sdk.trace_models.CanonicalTrace.tags: dict[str, str | None] = Field(default_factory=dict[str, 'str | None'])

No docstring is defined in the source.

aip_sdk.trace_models.CanonicalTrace.trace_id​

aip_sdk.trace_models.CanonicalTrace.trace_id: str

No docstring is defined in the source.

aip_sdk.trace_models.Document​

aip_sdk.trace_models.Document

A retrieved or reranked document attached to a span.

aip_sdk.trace_models.Document.content​

aip_sdk.trace_models.Document.content: str

No docstring is defined in the source.

aip_sdk.trace_models.Document.id​

aip_sdk.trace_models.Document.id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.Document.model_config​

aip_sdk.trace_models.Document.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.Document.score​

aip_sdk.trace_models.Document.score: float | None = None

No docstring is defined in the source.

aip_sdk.trace_models.Entity​

aip_sdk.trace_models.Entity

The concrete semantic identity of a topology node: (kind, name, role).

Identity is exactly those three fields, so two entities naming the same component compare equal and an Entity you construct yourself can be matched against one the platform returned. Unmodelled response fields are dropped rather than kept, which is what keeps that equality stable across platform releases.

aip_sdk.trace_models.Entity.kind​

aip_sdk.trace_models.Entity.kind: SpanKind

No docstring is defined in the source.

aip_sdk.trace_models.Entity.model_config​

aip_sdk.trace_models.Entity.model_config = ConfigDict(frozen=True, extra='ignore')

No docstring is defined in the source.

aip_sdk.trace_models.Entity.name​

aip_sdk.trace_models.Entity.name: str

No docstring is defined in the source.

aip_sdk.trace_models.Entity.role​

aip_sdk.trace_models.Entity.role: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.EntitySelector​

aip_sdk.trace_models.EntitySelector

A wildcard-capable match predicate over span identity.

kind is required; name and role match any value when left as None. EntitySelector(kind=SpanKind.LLM) matches every LLM span, while adding name="researcher" narrows to one semantic component.

aip_sdk.trace_models.EntitySelector.kind​

aip_sdk.trace_models.EntitySelector.kind: SpanKind

No docstring is defined in the source.

aip_sdk.trace_models.EntitySelector.model_config​

aip_sdk.trace_models.EntitySelector.model_config = ConfigDict(frozen=True)

No docstring is defined in the source.

aip_sdk.trace_models.EntitySelector.name​

aip_sdk.trace_models.EntitySelector.name: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.EntitySelector.role​

aip_sdk.trace_models.EntitySelector.role: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.Message​

aip_sdk.trace_models.Message

A role-tagged message composed of typed parts.

aip_sdk.trace_models.Message.model_config​

aip_sdk.trace_models.Message.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.Message.parts​

aip_sdk.trace_models.Message.parts: list[MessagePart] = Field(default_factory=list[MessagePart])

No docstring is defined in the source.

aip_sdk.trace_models.Message.role​

aip_sdk.trace_models.Message.role: str

No docstring is defined in the source.

aip_sdk.trace_models.Message.text​

aip_sdk.trace_models.Message.text: str

Concatenate the text content of this message's parts.

Returns

  • str: The joined text-part content, or an empty string if the message
  • str: carries no text parts. Non-string content on a text part is skipped.

aip_sdk.trace_models.MessagePart​

aip_sdk.trace_models.MessagePart

One typed part of a message (text, tool call, reasoning, blob, ...).

aip_sdk.trace_models.MessagePart.content​

aip_sdk.trace_models.MessagePart.content: Any | None = None

No docstring is defined in the source.

aip_sdk.trace_models.MessagePart.model_config​

aip_sdk.trace_models.MessagePart.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.MessagePart.tool_call​

aip_sdk.trace_models.MessagePart.tool_call: ToolCall | None = None

No docstring is defined in the source.

aip_sdk.trace_models.MessagePart.type​

aip_sdk.trace_models.MessagePart.type: str

No docstring is defined in the source.

aip_sdk.trace_models.PartitionSelector​

aip_sdk.trace_models.PartitionSelector

A re-resolvable selector naming a typed evaluation target.

target optionally narrows a SPAN partition to one component — omitted, every span is its own occurrence — and must be omitted for TRACE/SESSION partitions. ancestry_path further disambiguates a span match by its nearest ancestors. The consistency of these fields with partition_type is checked when the selector is used to create a partition.

aip_sdk.trace_models.PartitionSelector.ancestry_path​

aip_sdk.trace_models.PartitionSelector.ancestry_path: tuple[EntitySelector, ...] = ()

No docstring is defined in the source.

aip_sdk.trace_models.PartitionSelector.model_config​

aip_sdk.trace_models.PartitionSelector.model_config = ConfigDict(frozen=True)

No docstring is defined in the source.

aip_sdk.trace_models.PartitionSelector.partition_type​

aip_sdk.trace_models.PartitionSelector.partition_type: PartitionType

No docstring is defined in the source.

aip_sdk.trace_models.PartitionSelector.target​

aip_sdk.trace_models.PartitionSelector.target: EntitySelector | None = None

No docstring is defined in the source.

aip_sdk.trace_models.Provenance​

aip_sdk.trace_models.Provenance

How a canonical field was produced, most to least trusted.

Use it to judge how much to rely on a field: CONVENTION_DERIVED was mapped losslessly from a recognised tracing convention, SKILL_EMITTED was written at the source in the platform's own vocabulary, and BLOB_EXTRACTED was recovered from an unstructured payload and is the least reliable.

aip_sdk.trace_models.Provenance.BLOB_EXTRACTED​

aip_sdk.trace_models.Provenance.BLOB_EXTRACTED = 'blob-extracted'

No docstring is defined in the source.

aip_sdk.trace_models.Provenance.CONVENTION_DERIVED​

aip_sdk.trace_models.Provenance.CONVENTION_DERIVED = 'convention-derived'

No docstring is defined in the source.

aip_sdk.trace_models.Provenance.SKILL_EMITTED​

aip_sdk.trace_models.Provenance.SKILL_EMITTED = 'skill-emitted'

No docstring is defined in the source.

aip_sdk.trace_models.ResolvedPartition​

aip_sdk.trace_models.ResolvedPartition = Annotated[SpanPartition | TracePartition | SessionPartition, Field(discriminator='partition_type')]

One resolved partition: a span, trace, or session target, tagged by partition_type.

aip_sdk.trace_models.RunSession​

aip_sdk.trace_models.RunSession

One session's span structure with a run's evaluation results joined onto it.

Returned by Run.session(). A session may span several traces, so components are keyed on (trace_id, span_id).

Attributes

  • run_id str: The run these results were read from.
  • parent_id str: The session key this data was rolled up under — the same value passed to Run.session().
  • dataset_version_id str: The dataset version the run scored.
  • end_to_end list[SessionEndToEndResult]: Session/trace-granularity verdicts — the ones no single component owns.
  • components list[SessionComponent]: Every span in the session, including ones no partition covered.
  • evaluated_count int: Number of components that at least one metric scored.
  • total_count int: Total number of components in the session.

aip_sdk.trace_models.RunSession.components​

aip_sdk.trace_models.RunSession.components: list[SessionComponent] = Field(default_factory=list['SessionComponent'])

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.dataset_version_id​

aip_sdk.trace_models.RunSession.dataset_version_id: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.end_to_end​

aip_sdk.trace_models.RunSession.end_to_end: list[SessionEndToEndResult] = Field(default_factory=list['SessionEndToEndResult'])

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.evaluated_count​

aip_sdk.trace_models.RunSession.evaluated_count: int = Field(ge=0)

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.model_config​

aip_sdk.trace_models.RunSession.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.parent_id​

aip_sdk.trace_models.RunSession.parent_id: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.run_id​

aip_sdk.trace_models.RunSession.run_id: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.RunSession.total_count​

aip_sdk.trace_models.RunSession.total_count: int = Field(ge=0)

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget​

aip_sdk.trace_models.RunTarget

One partition target a trace_metric_invoke run scores at.

Pass a list of these to aip.run(targets=[...])/aip.arun(targets=[...]) to score several granularities in one run. span_kind cannot be set — scope which spans are scored with partition_id instead (see aip.create_partition()).

aip.run(**config.to_run_kwargs()) accepts a stored v2 config's targets directly; from_eval_target() converts one when building the list by hand.

metric_configs remains a plain, mutable dict — avoid mutating it in place. It is kept out of repr()/str(), and masked in model_dump()/model_dump_json(), since it can carry an inline judge key (see metric_configs["judge_api_key"] on aip_sdk.run.run()) — access the attribute directly to read the real value.

Attributes

  • partition_type PartitionType | None: The target's granularity. Required once more than one target is supplied, so each target's results stay distinguishable.
  • partition_id str | None: A saved Partition's id. For a SESSION/TRACE target it only labels the resulting rows with the partition scored — the selector narrows nothing at that granularity. For a SPAN target it additionally narrows scoring to the spans that partition's selector resolves to.
  • span_kind SpanKind | None: Always rejected — name a SPAN partition_id instead.
  • metrics tuple[str, ...] | None: Metrics to score at this target, overriding the run-level metrics for it. Omit to score the run-level selection.
  • metric_configs dict[str, MetricConfigValue] | None: Per-metric judge configuration for this target, overriding the run-level metric_configs for the same metric. A metric maps to one parameter set, or to a list of them at config schema "3".

aip_sdk.trace_models.RunTarget.from_eval_target​

aip_sdk.trace_models.RunTarget.from_eval_target(target: EvalTarget) -> RunTarget

Build a run target from a stored config's EvalTarget.

The two models are field-congruent, so this is a straight copy; span_kind is copied rather than dropped, so run() refuses it instead of silently widening the target to every span.

Parameters

  • target EvalTarget: One entry from EvalConfig.resolved_targets().

Returns

  • RunTarget: The equivalent RunTarget, ready to pass to aip.run(targets=[...]).

aip_sdk.trace_models.RunTarget.metric_configs​

aip_sdk.trace_models.RunTarget.metric_configs: dict[str, MetricConfigValue] | None = Field(default=None, repr=False)

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.metrics​

aip_sdk.trace_models.RunTarget.metrics: tuple[str, ...] | None = None

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.model_config​

aip_sdk.trace_models.RunTarget.model_config = ConfigDict(extra='forbid', frozen=True)

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.partition_id​

aip_sdk.trace_models.RunTarget.partition_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.partition_type​

aip_sdk.trace_models.RunTarget.partition_type: PartitionType | None = None

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.span_kind​

aip_sdk.trace_models.RunTarget.span_kind: SpanKind | None = None

No docstring is defined in the source.

aip_sdk.trace_models.RunTarget.to_wire_dict​

aip_sdk.trace_models.RunTarget.to_wire_dict() -> dict[str, Any]

Serialise this target for the POST /runs request body.

The single owner of context={"wire": True} — the one opt-out that makes metric_configs reach the platform unmasked (see _serialize_metric_configs()) — so no other call site can forget it and silently POST a masked "***" judge key.

aip_sdk.trace_models.SessionComponent​

aip_sdk.trace_models.SessionComponent

One span of a session, with every result that covered it.

(trace_id, span_id) is the component key. An empty results means no partition covered this span, not that it passed.

Attributes

  • trace_id str: The trace this span belongs to.
  • span_id str: This span's id.
  • parent_id str | None: The parent span's id, or None for a root span.
  • name str | None: The span's name, or None if the platform recorded none.
  • kind SpanKind | None: The span's kind, or None if the platform recorded none.
  • start_ns int | None: The span's start time in nanoseconds since epoch, or None if the platform recorded none.
  • results list[SessionResult]: Every result that covered this span. Empty means no partition covered it, not that it passed.

aip_sdk.trace_models.SessionComponent.kind​

aip_sdk.trace_models.SessionComponent.kind: SpanKind | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.model_config​

aip_sdk.trace_models.SessionComponent.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.name​

aip_sdk.trace_models.SessionComponent.name: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.parent_id​

aip_sdk.trace_models.SessionComponent.parent_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.results​

aip_sdk.trace_models.SessionComponent.results: list[SessionResult] = Field(default_factory=list['SessionResult'])

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.span_id​

aip_sdk.trace_models.SessionComponent.span_id: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.start_ns​

aip_sdk.trace_models.SessionComponent.start_ns: int | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionComponent.trace_id​

aip_sdk.trace_models.SessionComponent.trace_id: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.SessionEndToEndResult​

aip_sdk.trace_models.SessionEndToEndResult

A session- or trace-granularity verdict, grading the session as a whole.

Unlike a per-component SessionResult, partition_type always identifies which granularity (SESSION or TRACE) produced this verdict — read it without a None check.

Attributes

  • partition_type PartitionType: The granularity this verdict was scored at — always SESSION or TRACE.
  • target_ref str | None: The concrete session/trace id this verdict identifies, or None if the platform recorded none.

aip_sdk.trace_models.SessionEndToEndResult.partition_type​

aip_sdk.trace_models.SessionEndToEndResult.partition_type: PartitionType

No docstring is defined in the source.

aip_sdk.trace_models.SessionEndToEndResult.target_ref​

aip_sdk.trace_models.SessionEndToEndResult.target_ref: str | None = None

No docstring is defined in the source.

Inherited members​

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.error​

aip_sdk.trace_models.SessionEndToEndResult.error: str | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.metadata​

aip_sdk.trace_models.SessionEndToEndResult.metadata: dict[str, Any] | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.metric​

aip_sdk.trace_models.SessionEndToEndResult.metric: str = Field(min_length=1)

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.model_config​

aip_sdk.trace_models.SessionEndToEndResult.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.partition_id​

aip_sdk.trace_models.SessionEndToEndResult.partition_id: str | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.partition_name​

aip_sdk.trace_models.SessionEndToEndResult.partition_name: str | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.rationale​

aip_sdk.trace_models.SessionEndToEndResult.rationale: str | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/trace_models.py

aip_sdk.trace_models.SessionEndToEndResult.score​

aip_sdk.trace_models.SessionEndToEndResult.score: float | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionPartition​

aip_sdk.trace_models.SessionPartition

A resolved session target — exactly one session.

aip_sdk.trace_models.SessionPartition.model_config​

aip_sdk.trace_models.SessionPartition.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.SessionPartition.partition_type​

aip_sdk.trace_models.SessionPartition.partition_type: Literal[PartitionType.SESSION] = PartitionType.SESSION

No docstring is defined in the source.

aip_sdk.trace_models.SessionPartition.session​

aip_sdk.trace_models.SessionPartition.session: CanonicalSession

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult​

aip_sdk.trace_models.SessionResult

One metric's verdict on one occurrence within a session.

Attributes

  • partition_id str | None: The partition scored, or None if this verdict named no saved partition.
  • partition_name str | None: The scored partition's name, or None under the same condition as partition_id.
  • metric str: The metric name.
  • score float | None: The score, or None when error is set — an occurrence that errored has no usable score.
  • rationale str | None: The judge's explanation for score, when the metric is judge-based.
  • error str | None: Why this occurrence could not be scored, or None on a successful verdict.
  • metadata dict[str, Any] | None: What the metric judged against — e.g. expected_tools/called_tools/ missing_tools for agent.tool_selection_accuracy. The keys are the metric's own, so read them per metric rather than expecting a fixed shape; None when the platform recorded no metadata for this verdict.

aip_sdk.trace_models.SessionResult.error​

aip_sdk.trace_models.SessionResult.error: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.metadata​

aip_sdk.trace_models.SessionResult.metadata: dict[str, Any] | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.metric​

aip_sdk.trace_models.SessionResult.metric: str = Field(min_length=1)

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.model_config​

aip_sdk.trace_models.SessionResult.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.partition_id​

aip_sdk.trace_models.SessionResult.partition_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.partition_name​

aip_sdk.trace_models.SessionResult.partition_name: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.rationale​

aip_sdk.trace_models.SessionResult.rationale: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SessionResult.score​

aip_sdk.trace_models.SessionResult.score: float | None = None

No docstring is defined in the source.

aip_sdk.trace_models.SpanPartition​

aip_sdk.trace_models.SpanPartition

A resolved span target — exactly one span.

aip_sdk.trace_models.SpanPartition.model_config​

aip_sdk.trace_models.SpanPartition.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.SpanPartition.partition_type​

aip_sdk.trace_models.SpanPartition.partition_type: Literal[PartitionType.SPAN] = PartitionType.SPAN

No docstring is defined in the source.

aip_sdk.trace_models.SpanPartition.span​

aip_sdk.trace_models.SpanPartition.span: CanonicalSpan

No docstring is defined in the source.

aip_sdk.trace_models.SpanStatus​

aip_sdk.trace_models.SpanStatus

Outcome of a span.

aip_sdk.trace_models.SpanStatus.ERROR​

aip_sdk.trace_models.SpanStatus.ERROR = 'ERROR'

No docstring is defined in the source.

aip_sdk.trace_models.SpanStatus.OK​

aip_sdk.trace_models.SpanStatus.OK = 'OK'

No docstring is defined in the source.

aip_sdk.trace_models.SpanStatus.UNSET​

aip_sdk.trace_models.SpanStatus.UNSET = 'UNSET'

No docstring is defined in the source.

aip_sdk.trace_models.ToolCall​

aip_sdk.trace_models.ToolCall

A single tool invocation recorded on a span.

aip_sdk.trace_models.ToolCall.arguments​

aip_sdk.trace_models.ToolCall.arguments: dict[str, Any] | None = None

No docstring is defined in the source.

aip_sdk.trace_models.ToolCall.call_id​

aip_sdk.trace_models.ToolCall.call_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.ToolCall.model_config​

aip_sdk.trace_models.ToolCall.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.ToolCall.name​

aip_sdk.trace_models.ToolCall.name: str

No docstring is defined in the source.

aip_sdk.trace_models.ToolCall.result​

aip_sdk.trace_models.ToolCall.result: Any | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceMetric​

aip_sdk.trace_models.TraceMetric(scorer: str, mean: float, std: float, count: int, pass_rate: float, partition_type: PartitionType | None = None, partition_id: str | None = None, metric: str | None = None)

A Metric from a trace-metric run, identifying its series.

partition_type/partition_id are the identity of the measurement this summarises — present whenever the platform recorded them, regardless of how many targets the run scored — and None only when reading an artifact that predates those columns.

Attributes

  • partition_type PartitionType | None: The granularity this metric was measured at, or None for an artifact written before this column existed.
  • partition_id str | None: The partition scored, or None for a SESSION/TRACE target that named no saved partition, or for an artifact predating this column.
  • metric str | None: The bare metric name (e.g. "agent.custom_judge_rubric") — distinct from scorer, the RESULT COLUMN a metric scored under several stored configs occupies one of ({metric}__cfg__{config_name}). Equal to scorer for a metric resolving a single config.

aip_sdk.trace_models.TraceMetric.metric​

aip_sdk.trace_models.TraceMetric.metric: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceMetric.partition_id​

aip_sdk.trace_models.TraceMetric.partition_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceMetric.partition_type​

aip_sdk.trace_models.TraceMetric.partition_type: PartitionType | None = None

No docstring is defined in the source.

Inherited members​

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceMetric.count​

aip_sdk.trace_models.TraceMetric.count: int

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceMetric.mean​

aip_sdk.trace_models.TraceMetric.mean: float

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceMetric.pass_rate​

aip_sdk.trace_models.TraceMetric.pass_rate: float

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceMetric.scorer​

aip_sdk.trace_models.TraceMetric.scorer: str

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceMetric.std​

aip_sdk.trace_models.TraceMetric.std: float

No docstring is defined in the source.

aip_sdk.trace_models.TracePartition​

aip_sdk.trace_models.TracePartition

A resolved trace target — exactly one trace.

aip_sdk.trace_models.TracePartition.model_config​

aip_sdk.trace_models.TracePartition.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_models.TracePartition.partition_type​

aip_sdk.trace_models.TracePartition.partition_type: Literal[PartitionType.TRACE] = PartitionType.TRACE

No docstring is defined in the source.

aip_sdk.trace_models.TracePartition.trace​

aip_sdk.trace_models.TracePartition.trace: CanonicalTrace

No docstring is defined in the source.

aip_sdk.trace_models.TraceRunResultsPage​

aip_sdk.trace_models.TraceRunResultsPage(results: list[TraceScoreResult], metrics: list[TraceMetric], total: int, page: int, page_size: int)

Paginated result of trace_results().

Identical in shape to RunResultsPage, but declared with the trace-metric row identity so partition_type/partition_id/target_ref/ trace_id type-check without a cast — unlike results(), whose declared return type only names the base ScoreResult/Metric fields.

Attributes

  • results list[TraceScoreResult]: Per-row trace results. A metric measured at more than one target appears once per target here, each entry distinguished by its own identity.
  • metrics list[TraceMetric]: Aggregated per-metric summaries, one entry per ``(metric, partition_type, partition_id)`` measured in this run.
  • total int: Total row count across all pages.
  • page int: The page number returned (1-based).
  • page_size int: Rows requested per page.

aip_sdk.trace_models.TraceRunResultsPage.metrics​

aip_sdk.trace_models.TraceRunResultsPage.metrics: list[TraceMetric]

No docstring is defined in the source.

aip_sdk.trace_models.TraceRunResultsPage.page​

aip_sdk.trace_models.TraceRunResultsPage.page: int

No docstring is defined in the source.

aip_sdk.trace_models.TraceRunResultsPage.page_size​

aip_sdk.trace_models.TraceRunResultsPage.page_size: int

No docstring is defined in the source.

aip_sdk.trace_models.TraceRunResultsPage.results​

aip_sdk.trace_models.TraceRunResultsPage.results: list[TraceScoreResult]

No docstring is defined in the source.

aip_sdk.trace_models.TraceRunResultsPage.total​

aip_sdk.trace_models.TraceRunResultsPage.total: int

No docstring is defined in the source.

aip_sdk.trace_models.TraceScoreResult​

aip_sdk.trace_models.TraceScoreResult(input_id: str, scorer: str, score: float, explanation: str | None = None, config_identity: list[MetricConfigIdentity] = list['MetricConfigIdentity'](), partition_type: PartitionType | None = None, partition_id: str | None = None, target_ref: str | None = None, trace_id: str | None = None, metric: str | None = None)

A ScoreResult from a trace-metric run, identifying its occurrence.

Inherited input_id carries that occurrence's own scope_ref verbatim — a span, trace, or session id depending on the target's partition_type, opaque and not meant to be parsed. Use target_ref/trace_id for the typed identity instead.

Attributes

  • partition_type PartitionType | None: The granularity this occurrence was scored at, or None for an artifact written before this column existed.
  • partition_id str | None: The partition scored, or None for a SESSION/TRACE target that named no saved partition, or for an artifact predating this column.
  • target_ref str | None: The concrete span/trace/session id this row identifies — the typed counterpart to inherited input_id's opaque scope_ref.
  • trace_id str | None: The trace this occurrence belongs to.
  • metric str | None: The bare metric name (e.g. "agent.custom_judge_rubric") — distinct from scorer, the RESULT COLUMN a metric scored under several stored configs occupies one of ({metric}__cfg__{config_name}). Equal to scorer for a metric resolving a single config.

aip_sdk.trace_models.TraceScoreResult.metric​

aip_sdk.trace_models.TraceScoreResult.metric: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceScoreResult.partition_id​

aip_sdk.trace_models.TraceScoreResult.partition_id: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceScoreResult.partition_type​

aip_sdk.trace_models.TraceScoreResult.partition_type: PartitionType | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceScoreResult.target_ref​

aip_sdk.trace_models.TraceScoreResult.target_ref: str | None = None

No docstring is defined in the source.

aip_sdk.trace_models.TraceScoreResult.trace_id​

aip_sdk.trace_models.TraceScoreResult.trace_id: str | None = None

No docstring is defined in the source.

Inherited members​

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceScoreResult.config_identity​

aip_sdk.trace_models.TraceScoreResult.config_identity: list[MetricConfigIdentity] = field(default_factory=list['MetricConfigIdentity'])

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceScoreResult.explanation​

aip_sdk.trace_models.TraceScoreResult.explanation: str | None = None

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceScoreResult.input_id​

aip_sdk.trace_models.TraceScoreResult.input_id: str

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceScoreResult.score​

aip_sdk.trace_models.TraceScoreResult.score: float

No docstring is defined in the source.

Inherited from libs/aip-sdk/src/aip_sdk/models.py

aip_sdk.trace_models.TraceScoreResult.scorer​

aip_sdk.trace_models.TraceScoreResult.scorer: str

No docstring is defined in the source.