Annotation Configs#

class AnnotationConfigsClient(*, sdk_config: SDKConfiguration, generated_client: ApiClient)[source]#

Bases: object

Client for managing annotation configs including creation, retrieval, and deletion.

This class is primarily intended for internal use within the SDK. Users are highly encouraged to access resource-specific functionality via arize.ArizeClient.

The annotation configs client is a thin wrapper around the generated REST API client, using the shared generated API client owned by arize.config.SDKConfiguration.

Parameters:

sdk_config (SDKConfiguration) – Resolved SDK configuration.
generated_client (ApiClient) – Shared generated API client instance.

list(*, name: str | None = None, space: str | None = None, limit: int = DEFAULT_LIST_LIMIT, cursor: str | None = None) → AnnotationConfigListResponse[source]#

List annotation configs the user has access to.

Annotation configs are returned in descending creation order (most recently created first).

Parameters:

name (str | None) – Optional case-insensitive substring filter on the annotation config name.
space (str | None) – Optional space filter. If the value is a base64-encoded resource ID it is treated as a space ID; otherwise it is used as a case-insensitive substring filter on the space name.
limit (int) – Maximum number of annotation configs to return. The server enforces an upper bound.
cursor (str | None) – Opaque pagination cursor returned from a previous response.

Returns:

A response object with the annotation configs and pagination information.

Raises:

ApiException – If the REST API returns an error response (e.g. 401/403/429).

Return type:

AnnotationConfigListResponse

create_continuous(*, name: str, space: str, minimum_score: float | int, maximum_score: float | int, optimization_direction: OptimizationDirection | None = None) → ContinuousAnnotationConfig[source]#

Create a continuous annotation config.

Continuous annotation configs let a scorer enter a numeric score within a fixed range, e.g. a 0-1 quality score.

Parameters:

name (str) – Annotation config name (must be unique within the target space).
space (str) – Space ID or name to create the annotation config in.
minimum_score (float | int) – Minimum score a scorer is allowed to submit.
maximum_score (float | int) – Maximum score a scorer is allowed to submit.
optimization_direction (OptimizationDirection | None) – Optional direction (e.g. maximize or minimize) that indicates which end of the score range is considered better.

Returns:

The created continuous annotation config.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/409/429).

Return type:

ContinuousAnnotationConfig

create_categorical(*, name: str, space: str, values: builtins.list[CategoricalAnnotationValue], optimization_direction: OptimizationDirection | None = None) → CategoricalAnnotationConfig[source]#

Create a categorical annotation config.

Categorical annotation configs let a scorer choose from a fixed set of labeled values, e.g. “correct” / “incorrect”.

Parameters:

name (str) – Annotation config name (must be unique within the target space).
space (str) – Space ID or name to create the annotation config in.
values (builtins.list[CategoricalAnnotationValue]) – The labeled values a scorer can choose from.
optimization_direction (OptimizationDirection | None) – Optional direction (e.g. maximize or minimize) that indicates which values are considered better.

Returns:

The created categorical annotation config.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/409/429).

Return type:

CategoricalAnnotationConfig

create_freeform(*, name: str, space: str) → FreeformAnnotationConfig[source]#

Create a freeform annotation config.

Freeform annotation configs let a scorer leave open-ended text feedback with no predefined scale or set of values.

Parameters:

name (str) – Annotation config name (must be unique within the target space).
space (str) – Space ID or name to create the annotation config in.

Returns:

The created freeform annotation config.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/409/429).

Return type:

FreeformAnnotationConfig

get(*, annotation_config: str, space: str | None = None) → CategoricalAnnotationConfig | ContinuousAnnotationConfig | FreeformAnnotationConfig[source]#

Get an annotation config by ID or name.

Parameters:

annotation_config (str) – Annotation config ID or name. If a name is provided, space is required for resolution.
space (str | None) – Space ID or name. Required when annotation_config is a name so it can be resolved to an ID.

Returns:

The annotation config object.

Raises:

ApiException – If the REST API returns an error response (e.g. 401/403/404/429).

Return type:

CategoricalAnnotationConfig | ContinuousAnnotationConfig | FreeformAnnotationConfig

Update a continuous annotation config by ID or name.

Only the fields you pass are changed; omitted fields are left unchanged. The stored config must already be of type continuous.

Parameters:

annotation_config (str) – Annotation config ID or name. If a name is provided, space is required for resolution.
space (str | None) – Space ID or name. Required when annotation_config is a name so it can be resolved to an ID.
name (str | None) – New name for the annotation config. Must be unique within the space.
minimum_score (float | int | None) – New minimum score.
maximum_score (float | int | None) – New maximum score.
optimization_direction (OptimizationDirection | None) – New optimization direction.

Returns:

The updated annotation config object as returned by the API.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/404/409/422/429).

Return type:

ContinuousAnnotationConfig

update_categorical(*, annotation_config: str, space: str | None = None, name: str | None = None, values: builtins.list[CategoricalAnnotationValue] | None = None, optimization_direction: OptimizationDirection | None = None) → CategoricalAnnotationConfig[source]#

Update a categorical annotation config by ID or name.

Only the fields you pass are changed; omitted fields are left unchanged. The stored config must already be of type categorical.

Parameters:

annotation_config (str) – Annotation config ID or name. If a name is provided, space is required for resolution.
space (str | None) – Space ID or name. Required when annotation_config is a name so it can be resolved to an ID.
name (str | None) – New name for the annotation config. Must be unique within the space.
values (builtins.list[CategoricalAnnotationValue] | None) – Replacement set of categorical values. Replaces the full label set.
optimization_direction (OptimizationDirection | None) – New optimization direction.

Returns:

The updated annotation config object as returned by the API.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/404/409/422/429).

Return type:

CategoricalAnnotationConfig

update_freeform(*, annotation_config: str, space: str | None = None, name: str | None = None) → FreeformAnnotationConfig[source]#

Update a freeform annotation config by ID or name.

Only the fields you pass are changed; omitted fields are left unchanged. The stored config must already be of type freeform.

Parameters:

annotation_config (str) – Annotation config ID or name. If a name is provided, space is required for resolution.
space (str | None) – Space ID or name. Required when annotation_config is a name so it can be resolved to an ID.
name (str | None) – New name for the annotation config. Must be unique within the space.

Returns:

The updated annotation config object as returned by the API.

Raises:

ApiException – If the REST API returns an error response (e.g. 400/401/403/404/409/422/429).

Return type:

FreeformAnnotationConfig

delete(*, annotation_config: str, space: str | None = None) → None[source]#

Delete an annotation config by ID or name.

This operation is irreversible.

Parameters:

annotation_config (str) – Annotation config ID or name. If a name is provided, space is required for resolution.
space (str | None) – Space ID or name. Required when annotation_config is a name so it can be resolved to an ID.

Returns:

This method returns None on success (common empty 204 response).

Raises:

ApiException – If the REST API returns an error response (e.g. 401/403/404/429).

Return type:

None

Response Types#

class AnnotationConfigListResponse(*, annotation_configs: list[CategoricalAnnotationConfig | ContinuousAnnotationConfig | FreeformAnnotationConfig], pagination: PaginationMetadata)[source]#

Bases: BaseModel

SDK view of the generated list response with each AnnotationConfig unwrapped.

The annotation_configs field contains the concrete inner types (CategoricalAnnotationConfig, ContinuousAnnotationConfig, or FreeformAnnotationConfig) instead of the oneOf wrapper.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

annotation_configs (list[CategoricalAnnotationConfig | ContinuousAnnotationConfig | FreeformAnnotationConfig])
pagination (PaginationMetadata)

annotation_configs: list[CategoricalAnnotationConfig | ContinuousAnnotationConfig | FreeformAnnotationConfig]#

pagination: PaginationMetadata#

model_config: ClassVar[ConfigDict] = {'from_attributes': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_df(by_alias: bool = False, exclude_none: str | bool = True, json_normalize: bool = False, convert_dtypes: bool = True, expand_field: str = 'additional_properties', expand_prefix: str = '') → pd.DataFrame#

Convert a list of objects to a pandas.DataFrame.

Behavior:

If an item is a Pydantic v2 model, use .model_dump(by_alias=…).
If an item is a mapping (dict-like), use it as-is.
Otherwise, raise a ValueError (unsupported row type).

Parameters:

self (object) – The object instance containing the field to convert.
by_alias (bool) – Use field aliases when dumping Pydantic models.
exclude_none (str | bool) – Control None/NaN column dropping. - False: keep Nones as-is - “all”: drop columns where all values are None/NaN - “any”: drop columns where any value is None/NaN - True: alias for “all”
json_normalize (bool) – If True, flatten nested dicts via pandas.json_normalize.
convert_dtypes (bool) – If True, call DataFrame.convert_dtypes() at the end.
expand_field (str) – If set, look for this field in each row and expand its keys into top-level columns.
expand_prefix (str) – If set, prefix expanded column names with this string.

Returns:

The converted DataFrame.

Return type:

pandas.DataFrame

class AnnotationConfigType(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: str, Enum

The type of annotation config: - continuous: a numeric score within a defined range - categorical: a set of labeled values each with an optional score - freeform: free-text annotation with no structured scoring

CONTINUOUS = 'continuous'#

CATEGORICAL = 'categorical'#

FREEFORM = 'freeform'#

classmethod from_json(json_str: str) → Self[source]#

Create an instance of AnnotationConfigType from a JSON string

Parameters:: json_str (str)
Return type:: Self

class CategoricalAnnotationConfig(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], created_at: datetime, space_id: Annotated[str, Strict(strict=True)], type: Annotated[str, Strict(strict=True)], values: List[CategoricalAnnotationValue], optimization_direction: OptimizationDirection | None = None)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

id (Annotated[str, Strict(strict=True)])
name (Annotated[str, Strict(strict=True)])
created_at (datetime)
space_id (Annotated[str, Strict(strict=True)])
type (Annotated[str, Strict(strict=True)])
values (List[CategoricalAnnotationValue])
optimization_direction (OptimizationDirection | None)

id: StrictStr#

name: StrictStr#

created_at: datetime#

space_id: StrictStr#

type: StrictStr#

values: List[CategoricalAnnotationValue]#

optimization_direction: OptimizationDirection | None#

classmethod type_validate_enum(value)[source]#: Validates the enum

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:: str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:: str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of CategoricalAnnotationConfig from a JSON string

Parameters:: json_str (str)
Return type:: Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:: Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of CategoricalAnnotationConfig from a dict

Parameters:: obj (Dict[str, Any] | None)
Return type:: Self | None

class CategoricalAnnotationValue(*, label: Annotated[str, Strict(strict=True)], score: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None = None)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

label (Annotated[str, Strict(strict=True)])
score (Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None)

label: StrictStr#

score: StrictFloat | StrictInt | None#

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:: str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:: str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of CategoricalAnnotationValue from a JSON string

Parameters:: json_str (str)
Return type:: Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:: Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of CategoricalAnnotationValue from a dict

Parameters:: obj (Dict[str, Any] | None)
Return type:: Self | None

class ContinuousAnnotationConfig(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], created_at: datetime, space_id: Annotated[str, Strict(strict=True)], type: Annotated[str, Strict(strict=True)], minimum_score: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)], maximum_score: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)], optimization_direction: OptimizationDirection | None = None)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

id (Annotated[str, Strict(strict=True)])
name (Annotated[str, Strict(strict=True)])
created_at (datetime)
space_id (Annotated[str, Strict(strict=True)])
type (Annotated[str, Strict(strict=True)])
minimum_score (Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)])
maximum_score (Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)])
optimization_direction (OptimizationDirection | None)

id: StrictStr#

name: StrictStr#

created_at: datetime#

space_id: StrictStr#

type: StrictStr#

minimum_score: StrictFloat | StrictInt#

maximum_score: StrictFloat | StrictInt#

optimization_direction: OptimizationDirection | None#

classmethod type_validate_enum(value)[source]#: Validates the enum

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:: str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:: str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of ContinuousAnnotationConfig from a JSON string

Parameters:: json_str (str)
Return type:: Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:: Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of ContinuousAnnotationConfig from a dict

Parameters:: obj (Dict[str, Any] | None)
Return type:: Self | None

class FreeformAnnotationConfig(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], created_at: datetime, space_id: Annotated[str, Strict(strict=True)], type: Annotated[str, Strict(strict=True)])[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

id (Annotated[str, Strict(strict=True)])
name (Annotated[str, Strict(strict=True)])
created_at (datetime)
space_id (Annotated[str, Strict(strict=True)])
type (Annotated[str, Strict(strict=True)])

id: StrictStr#

name: StrictStr#

created_at: datetime#

space_id: StrictStr#

type: StrictStr#

classmethod type_validate_enum(value)[source]#: Validates the enum

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:: str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:: str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of FreeformAnnotationConfig from a JSON string

Parameters:: json_str (str)
Return type:: Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:: Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of FreeformAnnotationConfig from a dict

Parameters:: obj (Dict[str, Any] | None)
Return type:: Self | None

class OptimizationDirection(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: str, Enum

The direction for optimization. Defaults to none when omitted. - maximize: higher scores are better - minimize: lower scores are better - none: higher or lower scores are neither better nor worse

MAXIMIZE = 'maximize'#

MINIMIZE = 'minimize'#

NONE = 'none'#

classmethod from_json(json_str: str) → Self[source]#

Create an instance of OptimizationDirection from a JSON string

Parameters:: json_str (str)
Return type:: Self

class PaginationMetadata(*, next_cursor: Annotated[str, Strict(strict=True)] | None = None, has_more: Annotated[bool, Strict(strict=True)])[source]#

Bases: BaseModel

Cursor-based pagination metadata. Use next_cursor in the subsequent request’s cursor query parameter.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

next_cursor (Annotated[str, Strict(strict=True)] | None)
has_more (Annotated[bool, Strict(strict=True)])

next_cursor: StrictStr | None#

has_more: StrictBool#

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:: str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:: str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of PaginationMetadata from a JSON string

Parameters:: json_str (str)
Return type:: Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:: Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of PaginationMetadata from a dict

Parameters:: obj (Dict[str, Any] | None)
Return type:: Self | None