ChatPrompt

class opik.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. If omitted, the project from the active project context is used, then the client’s configured project. The resolved name is stored on 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', 'audio'], 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”, “video” or “audio”) and values are booleans indicating support. When a modality is not supported (False or not specified), structured content parts (e.g., images, videos, audio) are replaced with text placeholders like “<<<image>>>” or “<<<video>>>”. When supported (True), the structured content is preserved as-is. Example: {“vision”: True, “video”: False, “audio”: True}

    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