Prompts#

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

Bases: object

Client for managing prompts in the Arize platform.

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

The prompts 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) → PromptListResponse[source]#

List prompts in a space.

Parameters:

  • name (str | None) – Optional case-insensitive substring filter on the prompt 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 prompts to return. The server enforces an upper bound of 100.

  • cursor (str | None) – Opaque pagination cursor returned from a previous response.

Returns:

A response object with the prompts and pagination information.

Raises:

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

Return type:

PromptListResponse

create(*, space: str, name: str, commit_message: str, input_variable_format: InputVariableFormat, provider: LlmProvider, messages: builtins.list[LLMMessage], description: str | None = None, model: str | None = None, invocation_params: InvocationParams | None = None, provider_params: ProviderParams | None = None) → PromptWithVersion[source]#

Create a prompt with an initial version.

Parameters:

  • space (str) – Space ID or name to create the prompt in. If a name is provided it will be resolved to a space ID automatically.

  • name (str) – Prompt name (must be unique within the space).

  • commit_message (str) – Commit message describing the initial version.

  • input_variable_format (InputVariableFormat) – Variable interpolation format for the prompt template (e.g. InputVariableFormat.F_STRING).

  • provider (LlmProvider) – LLM provider for the prompt.

  • messages (builtins.list[LLMMessage]) – Messages that make up the prompt template (at least one required).

  • description (str | None) – Optional description of the prompt.

  • model (str | None) – Optional model name. If omitted, no default model is set on the version.

  • invocation_params (InvocationParams | None) – Optional invocation parameters (e.g. temperature, max_tokens).

  • provider_params (ProviderParams | None) – Optional provider-specific parameters.

Returns:

The created prompt with its initial version.

Raises:

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

Return type:

PromptWithVersion

get(*, prompt: str, space: str | None = None, version_id: str | None = None, label: str | None = None) → PromptWithVersion[source]#

Get a prompt by ID or name.

Optionally resolves a specific version by version_id or a label. If neither is supplied, the latest version is returned.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

  • version_id (str | None) – Optional specific version ID to retrieve.

  • label (str | None) – Optional label name to resolve to a version (e.g. "production").

Returns:

The prompt object with its resolved version.

Raises:

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

Return type:

PromptWithVersion

get_version(*, version_id: str) → PromptVersion[source]#

Get a single prompt version by its ID.

Version IDs are pure IDs with no name resolution.

Parameters:

version_id (str) – Version ID to retrieve.

Returns:

The prompt version.

Raises:

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

Return type:

PromptVersion

update(*, prompt: str, space: str | None = None, description: str) → Prompt[source]#

Update a prompt’s metadata.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

  • description (str) – Updated description for the prompt.

Returns:

The updated prompt object.

Raises:

  • ValueError – If no fields to update are provided.

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

Return type:

Prompt

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

Delete a prompt by ID or name.

This operation is irreversible and removes all associated versions.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

Returns:

None on success (204 No Content).

Raises:

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

Return type:

None

list_versions(*, prompt: str, space: str | None = None, limit: int = DEFAULT_LIST_LIMIT, cursor: str | None = None) → PromptVersionListResponse[source]#

List versions for a prompt.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

  • limit (int) – Maximum number of versions to return. The server enforces an upper bound of 100.

  • cursor (str | None) – Opaque pagination cursor returned from a previous response.

Returns:

A response object with the prompt versions and pagination information.

Raises:

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

Return type:

PromptVersionListResponse

create_version(*, prompt: str, space: str | None = None, commit_message: str, input_variable_format: InputVariableFormat, provider: LlmProvider, messages: builtins.list[LLMMessage], model: str | None = None, invocation_params: InvocationParams | None = None, provider_params: ProviderParams | None = None) → PromptVersion[source]#

Create a new version for an existing prompt.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

  • commit_message (str) – Commit message describing this version.

  • input_variable_format (InputVariableFormat) – Variable interpolation format for the prompt template (e.g. InputVariableFormat.F_STRING).

  • provider (LlmProvider) – LLM provider for this version.

  • messages (builtins.list[LLMMessage]) – Messages that make up the prompt template (at least one required).

  • model (str | None) – Optional model name. If omitted, no default model is set on this version.

  • invocation_params (InvocationParams | None) – Optional invocation parameters (e.g. temperature, max_tokens).

  • provider_params (ProviderParams | None) – Optional provider-specific parameters.

Returns:

The created prompt version.

Raises:

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

Return type:

PromptVersion

get_version_by_label(*, prompt: str, space: str | None = None, label_name: str) → PromptVersion[source]#

Resolve a label to a prompt version.

Parameters:

  • prompt (str) – Prompt ID or name. If a name is provided, space must also be supplied so the name can be resolved.

  • space (str | None) – Optional space ID or name. Required when prompt is a name.

  • label_name (str) – Label name to resolve (e.g. "production", "staging").

Returns:

The prompt version the label currently points to.

Raises:

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

Return type:

PromptVersion

set_labels(*, version_id: str, labels: builtins.list[str]) → PromptVersionLabelsResponse[source]#

Set labels on a prompt version.

Replaces all existing labels on the version with the provided list.

Parameters:

  • version_id (str) – Version ID to set labels on.

  • labels (builtins.list[str]) – List of label names to assign (replaces all existing labels).

Returns:

The response with the updated labels.

Raises:

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

Return type:

PromptVersionLabelsResponse

delete_label(*, version_id: str, label_name: str) → None[source]#

Remove a label from a prompt version.

Parameters:

  • version_id (str) – Version ID to remove the label from.

  • label_name (str) – Label name to remove (e.g. "production", "staging").

Returns:

None on success (204 No Content).

Raises:

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

Return type:

None

Response Types#

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

Bases: str, Enum

The format for input variables in the prompt messages. Defaults to f_string if not provided. - f_string: Single curly braces ({variable_name}) - mustache: Double curly braces ({{variable_name}}) - none: Deprecated. Treated as f_string. Will be removed in a future version.

F_STRING = 'f_string'#
MUSTACHE = 'mustache'#
NONE = 'none'#
classmethod from_json(json_str: str) → Self[source]#

Create an instance of InputVariableFormat from a JSON string

Parameters:

json_str (str)

Return type:

Self

class InvocationParams(*, temperature: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None = None, max_tokens: Annotated[int, Strict(strict=True)] | None = None, max_completion_tokens: Annotated[int, Strict(strict=True)] | None = None, top_p: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None = None, frequency_penalty: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None = None, presence_penalty: Annotated[float, Strict(strict=True)] | Annotated[int, Strict(strict=True)] | None = None, stop: List[Annotated[str, Strict(strict=True)]] | None = None, response_format: ResponseFormat | None = None, tool_config: ToolConfig | None = None, top_k: Annotated[int, Strict(strict=True)] | None = None, thinking_level: Annotated[str, Strict(strict=True)] | None = None, thinking_budget: Annotated[int, Strict(strict=True)] | None = None, reasoning_effort: Annotated[str, Strict(strict=True)] | None = None, verbosity: Annotated[str, Strict(strict=True)] | None = None, additional_properties: Dict[str, Any] = {})[source]#

Bases: InvocationParams

Invocation parameters with a clean string representation.

Omits fields whose value is None so that an all-None object displays as an empty string rather than leaking internal repr.

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:
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].

class LLMMessage(*, role: MessageRole, content: Annotated[str, Strict(strict=True)] | None = None, tool_call_id: Annotated[str, Strict(strict=True)] | None = None, tool_calls: List[ToolCall] | None = None)[source]#

Bases: BaseModel

A message in the prompt template

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:

  • role (MessageRole)

  • content (Annotated[str, Strict(strict=True)] | None)

  • tool_call_id (Annotated[str, Strict(strict=True)] | None)

  • tool_calls (List[ToolCall] | None)

role: MessageRole#
content: StrictStr | None#
tool_call_id: StrictStr | None#
tool_calls: List[ToolCall] | 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 LLMMessage 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 LLMMessage from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

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

Bases: str, Enum

The LLM provider to use

OPEN_AI = 'open_ai'#
AZURE_OPEN_AI = 'azure_open_ai'#
AWS_BEDROCK = 'aws_bedrock'#
VERTEX_AI = 'vertex_ai'#
ANTHROPIC = 'anthropic'#
CUSTOM = 'custom'#
classmethod from_json(json_str: str) → Self[source]#

Create an instance of LlmProvider from a JSON string

Parameters:

json_str (str)

Return type:

Self

class Prompt(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], description: Annotated[str, Strict(strict=True)] | None = None, space_id: Annotated[str, Strict(strict=True)], created_at: datetime, updated_at: datetime, created_by_user_id: Annotated[str, Strict(strict=True)])[source]#

Bases: BaseModel

A prompt is a reusable template for LLM interactions. Prompts can be versioned and labeled to track changes over time. Use prompts to standardize how you interact with LLMs across your application.

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: StrictStr#
name: StrictStr#
description: StrictStr | None#
space_id: StrictStr#
created_at: datetime#
updated_at: datetime#
created_by_user_id: StrictStr#
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 Prompt 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 Prompt from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

class PromptWithVersion(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], description: Annotated[str, Strict(strict=True)] | None = None, space_id: Annotated[str, Strict(strict=True)], created_at: datetime, updated_at: datetime, created_by_user_id: Annotated[str, Strict(strict=True)], version: PromptVersion)[source]#

Bases: PromptWithVersion

SDK view of a prompt with its resolved version.

Overrides the version field type to PromptVersion so that the nested version object renders cleanly via __str__ when displayed by the CLI’s generic formatter.

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:
version: PromptVersion#
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].

class PromptVersion(*, id: Annotated[str, Strict(strict=True)], prompt_id: Annotated[str, Strict(strict=True)], commit_hash: Annotated[str, Strict(strict=True)], commit_message: Annotated[str, Strict(strict=True)], messages: List[LLMMessage], input_variable_format: InputVariableFormat, provider: LlmProvider, model: Annotated[str, Strict(strict=True)], invocation_params: InvocationParams | None = None, provider_params: ProviderParams | None = None, created_at: datetime, created_by_user_id: Annotated[str, Strict(strict=True)], labels: List[Annotated[str, Strict(strict=True)]] | None = None)[source]#

Bases: PromptVersion

SDK view of a prompt version with a clean string representation.

Used when the version is displayed as a nested field inside PromptWithVersion — avoids leaking internal SDK repr strings for enum values, messages, and invocation params.

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:
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].

class ProviderParams(*, azure_params: ProviderParamsAzureParams | None = None, anthropic_headers: ProviderParamsAnthropicHeaders | None = None, anthropic_version: Annotated[str, Strict(strict=True)] | None = None, bedrock_options: ProviderParamsBedrockOptions | None = None, region: Annotated[str, Strict(strict=True)] | None = None, additional_properties: Dict[str, Any] = {})[source]#

Bases: BaseModel

Provider-specific parameters

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:

  • azure_params (ProviderParamsAzureParams | None)

  • anthropic_headers (ProviderParamsAnthropicHeaders | None)

  • anthropic_version (Annotated[str, Strict(strict=True)] | None)

  • bedrock_options (ProviderParamsBedrockOptions | None)

  • region (Annotated[str, Strict(strict=True)] | None)

  • additional_properties (Dict[str, Any])

azure_params: ProviderParamsAzureParams | None#
anthropic_headers: ProviderParamsAnthropicHeaders | None#
anthropic_version: StrictStr | None#
bedrock_options: ProviderParamsBedrockOptions | None#
region: StrictStr | None#
additional_properties: Dict[str, Any]#
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 ProviderParams 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.

  • Fields in self.additional_properties are added to the output dict.

Return type:

Dict[str, Any]

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

Create an instance of ProviderParams from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

On this page