ChatPrompt

class opik.api_objects.prompt.chat.chat_prompt.ChatPrompt(name: str, messages: List[Dict[str, str | List[Dict[str, Any]]]], metadata: Dict[str, Any] | None = None, type: PromptType = prompt_types.PromptType.MUSTACHE, validate_placeholders: bool = False, id: str | None = None, description: str | None = None, change_description: str | None = None, tags: List[str] | None = None, project_name: str | None = None)

Bases: BasePrompt

ChatPrompt class represents a chat-style prompt with a name, message array template and commit hash. Similar to Prompt but uses a list of chat messages instead of a string template.

__init__(name: str, messages: List[Dict[str, str | List[Dict[str, Any]]]], metadata: Dict[str, Any] | None = None, type: PromptType = prompt_types.PromptType.MUSTACHE, validate_placeholders: bool = False, id: str | None = None, description: str | None = None, change_description: str | None = None, tags: List[str] | None = None, project_name: str | None = None) → None

Initializes a new instance of the ChatPrompt class. Creates a new chat prompt using the opik client and sets the initial state.

Parameters:

• name – The name for the prompt.

• messages – List of message dictionaries with ‘role’ and ‘content’ fields.

• metadata – Optional metadata to be included in the prompt.

• type – The template type (MUSTACHE or JINJA2).

• validate_placeholders – Whether to validate template placeholders.

• id – Optional unique identifier (UUID) for the prompt.

• description – Optional description of the prompt (up to 255 characters).

• change_description – Optional description of changes in this version.

• tags – Optional list of tags to associate with the prompt.

• project_name – Optional project name for the prompt.

Raises:

• PromptTemplateStructureMismatch – If a text prompt with the same name already exists (template structure is immutable).

• ValidationError – If messages structure is invalid.

property synced: bool

Whether the chat prompt has been successfully synced with the backend.

sync_with_backend() → bool

Synchronize the chat prompt with the backend.

Creates or updates the chat prompt on the Opik server. If the sync fails, a warning is logged and the prompt continues to work locally.

Returns:

True if the sync succeeded, False otherwise.

property name: str

The name of the prompt.

property template: List[Dict[str, str | List[Dict[str, Any]]]]

The chat messages template.

property commit: str | None

Legacy commit hash of the prompt version.

DEPRECATED — use version (e.g. "v3") instead. commit is no longer surfaced in the Opik UI and is kept only for backwards compatibility with older SDK callers.

property version: str | None

The sequential version selector for the prompt (e.g. "v3").

property version_id: str | None

The unique identifier of the prompt version.

property metadata: Dict[str, Any] | None

The metadata dictionary associated with the prompt

property type: PromptType

The prompt type of the prompt.

property id: str | None

The unique identifier (UUID) of the prompt.

property description: str | None

The description of the prompt.

property change_description: str | None

The description of changes in this version.

property project_name: str | None

The name of the project this prompt belongs to.

property environments: List[str] | None

The environments that currently own this prompt version, or None if unowned.

property tags: List[str] | None

The list of tags associated with the prompt.

format(variables: Dict[str, Any], supported_modalities: Mapping[Literal['vision', 'video'], bool] | None = None) → List[Dict[str, str | List[Dict[str, Any]]]]

Renders the chat template with provided variables.

Parameters:

• variables – Dictionary of variables to substitute in the template.

• supported_modalities –

  Optional dictionary specifying which modalities are supported by the target model. Keys are modality names (“vision” or “video”) and values are booleans indicating support. When a modality is not supported (False or not specified), structured content parts (e.g., images, videos) are replaced with text placeholders like “<<<image>>>” or “<<<video>>>”. When supported (True), the structured content is preserved as-is. Example: {“vision”: True, “video”: False}

  If not specified, all modalities default to SUPPORTED. Example: {“vision”: True, “video”: False}

Returns:

A list of rendered message dictionaries with variables substituted and multimodal content either preserved or replaced with placeholders based on supported_modalities.

classmethod from_fern_prompt_version(name: str, prompt_version: PromptVersionDetail, project_name: str | None = None) → ChatPrompt