Implementation:Arize ai Phoenix Generated V1 Types

Knowledge Sources	Arize_ai_Phoenix
Domains	AI_Observability, Client_SDK, API_Types
Last Updated	2026-02-14 05:30 GMT

Overview

Auto-generated TypedDict definitions derived from the Phoenix OpenAPI specification, providing strongly typed Python representations of all V1 REST API request and response payloads.

Description

The Generated V1 Types module is a machine-generated file (marked with "Do not edit") containing TypedDict class definitions that correspond to the Phoenix server's V1 REST API schema. These types are produced by the codegen transform script which converts dataclass definitions from the OpenAPI spec into TypedDict form.

The module defines approximately 90+ TypedDict classes organized into several categories:

Core Data Types:

• Dataset, DatasetExample, DatasetVersion, DatasetWithExampleCount -- Types for dataset management including examples, versions, and metadata.
• Experiment, ExperimentRun, ExperimentEvaluationResult -- Types for experiment execution and evaluation results.
• Project -- Phoenix project metadata.
• Span, SpanContext, SpanEvent -- Trace span data with context propagation.
• Prompt, PromptVersion, PromptVersionData -- Prompt management types with full template and invocation parameter support.

Annotation Types:

• SpanAnnotation, TraceAnnotation, SessionAnnotation -- Annotation data for spans, traces, and sessions.
• AnnotationResult -- Shared result type with optional label, score, and explanation.
• CategoricalAnnotationConfig, ContinuousAnnotationConfig, FreeformAnnotationConfig -- Annotation configuration variants.

Request/Response Bodies:

• CreateExperimentRequestBody, CreateExperimentResponseBody -- Experiment CRUD.
• AnnotateSpansRequestBody, AnnotateSpansResponseBody -- Span annotation endpoints.
• CreatePromptRequestBody, CreatePromptResponseBody -- Prompt management endpoints.
• ListDatasetsResponseBody, ListExperimentsResponseBody -- Paginated list responses with next_cursor.

Prompt Template System:

• PromptChatTemplate, PromptStringTemplate -- Chat and string template formats.
• PromptMessage -- Messages with roles (user, assistant, system, developer, tool, model, ai).
• TextContentPart, ToolCallContentPart, ToolResultContentPart -- Message content parts.
• PromptTools, PromptToolFunction, PromptToolFunctionDefinition -- Tool use definitions.
• Provider-specific invocation parameters: PromptOpenAIInvocationParametersContent, PromptAnthropicInvocationParametersContent, PromptGoogleInvocationParametersContent, PromptDeepSeekInvocationParametersContent, PromptXAIInvocationParametersContent, PromptOllamaInvocationParametersContent, PromptAwsInvocationParametersContent, PromptAzureOpenAIInvocationParametersContent.

OTLP Types:

• OtlpSpan, OtlpEvent, OtlpKeyValue, OtlpAnyValue, OtlpArrayValue -- OpenTelemetry Protocol span representations.

User Management:

• LocalUser, OAuth2User, LDAPUser -- User types for different authentication methods.

The module uses NotRequired from typing_extensions for optional fields, preserving the distinction between required and optional API fields. Inheritance is used where appropriate (e.g., SpanAnnotation extends SpanAnnotationData) to avoid field duplication.

Usage

Import these types for type checking when constructing API requests or processing API responses through the Phoenix client. Do not edit this file directly; instead modify the source dataclass definitions and re-run the codegen transform script.

Code Reference

Source Location

• Repository: Arize_ai_Phoenix
• File: packages/phoenix-client/src/phoenix/client/__generated__/v1/__init__.py

Signature

# Selected representative types (file contains ~90+ TypedDicts)

class Dataset(TypedDict):
    id: str
    name: str
    description: Optional[str]
    metadata: Mapping[str, Any]
    created_at: str
    updated_at: str
    example_count: int

class DatasetExample(TypedDict):
    id: str
    input: Mapping[str, Any]
    output: Mapping[str, Any]
    metadata: Mapping[str, Any]
    updated_at: str

class Experiment(TypedDict):
    id: str
    dataset_id: str
    dataset_version_id: str
    repetitions: int
    metadata: Mapping[str, Any]
    project_name: Optional[str]
    created_at: str
    updated_at: str
    example_count: int
    successful_run_count: int
    failed_run_count: int
    missing_run_count: int

class ExperimentRun(TypedDict):
    dataset_example_id: str
    output: Any
    repetition_number: int
    start_time: str
    end_time: str
    id: str
    experiment_id: str
    trace_id: NotRequired[str]
    error: NotRequired[str]

class Span(TypedDict):
    name: str
    context: SpanContext
    span_kind: str
    start_time: str
    end_time: str
    status_code: str
    id: NotRequired[str]
    parent_id: NotRequired[str]
    attributes: NotRequired[Mapping[str, Any]]
    events: NotRequired[Sequence[SpanEvent]]

class PromptVersion(PromptVersionData):
    id: str

Import

from phoenix.client.__generated__ import v1

# Access types via the v1 module
example: v1.DatasetExample = {
    "id": "...",
    "input": {},
    "output": {},
    "metadata": {},
    "updated_at": "2025-01-01T00:00:00Z",
}

# Or import specific types
from phoenix.client.__generated__.v1 import Dataset, Experiment, Span

I/O Contract

Pagination Pattern

List response types follow a consistent cursor-based pagination pattern:

Field	Type	Description
data	Sequence[T]	The list of items in the current page
next_cursor	Optional[str]	Cursor for fetching the next page; None when no more pages

Common Field Patterns

Pattern	Type Convention	Description
Timestamps	str (ISO 8601)	Created/updated timestamps (exception: DatasetVersion.created_at is datetime)
IDs	str	All entity identifiers are strings
Optional fields	NotRequired[T]	Fields that may be omitted from the payload
Nullable fields	Optional[T]	Fields that are always present but may be None
Metadata	Mapping[str, Any]	Arbitrary key-value metadata
Enum-like fields	Literal[...]	Constrained string values (e.g., roles, annotator kinds)

Usage Examples

from phoenix.client.__generated__ import v1

# Constructing an experiment run payload
run: v1.CreateExperimentRunRequestBody = {
    "dataset_example_id": "example-123",
    "output": {"answer": "42"},
    "repetition_number": 1,
    "start_time": "2025-06-01T10:00:00Z",
    "end_time": "2025-06-01T10:00:05Z",
}

# Processing a list response
def process_experiments(response: v1.ListExperimentsResponseBody) -> None:
    for experiment in response["data"]:
        print(f"Experiment {experiment['id']}: {experiment['successful_run_count']} successes")
    if response["next_cursor"]:
        print(f"More results available at cursor: {response['next_cursor']}")

# Type-safe annotation creation
annotation: v1.SpanAnnotationData = {
    "name": "quality",
    "annotator_kind": "LLM",
    "span_id": "span-456",
    "result": {"label": "good", "score": 0.95},
}

Related Pages

• Principle:Arize_ai_Phoenix_Client_Initialization
• Arize_ai_Phoenix_Codegen_Transform -- The script that generates this file
• Arize_ai_Phoenix_Experiment_Types -- Experiment types that extend these generated types