opik 1.9.26__py3-none-any.whl → 1.9.39__py3-none-any.whl

opik/api_objects/prompt/base_prompt.py

@@ -0,0 +1,69 @@
+"""
+Base class for prompts.
+
+Defines abstract interface that both string and chat prompt variants must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+from . import types as prompt_types
+
+
+class BasePrompt(ABC):
+    """
+    Abstract base class for prompts (string and chat).
+
+    All prompt implementations must provide common properties and methods
+    for interacting with the backend API.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The name of the prompt."""
+        pass
+
+    @property
+    @abstractmethod
+    def commit(self) -> Optional[str]:
+        """The commit hash of the prompt version."""
+        pass
+
+    @property
+    @abstractmethod
+    def metadata(self) -> Optional[Dict[str, Any]]:
+        """The metadata dictionary associated with the prompt."""
+        pass
+
+    @property
+    @abstractmethod
+    def type(self) -> prompt_types.PromptType:
+        """The prompt type (MUSTACHE or JINJA2)."""
+        pass
+
+    # Internal API fields for backend synchronization
+    __internal_api__prompt_id__: str
+    __internal_api__version_id__: str
+
+    @abstractmethod
+    def format(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Format the prompt with the provided variables.
+
+        Returns:
+            Formatted output. Type depends on the implementation:
+            - Prompt returns str
+            - ChatPrompt returns List[Dict[str, MessageContent]]
+        """
+        pass
+
+    @abstractmethod
+    def __internal_api__to_info_dict__(self) -> Dict[str, Any]:
+        """
+        Convert the prompt to an info dictionary for serialization.
+
+        Returns:
+            Dictionary containing prompt metadata and version information.
+        """
+        pass

opik/api_objects/prompt/base_prompt_template.py

@@ -0,0 +1,29 @@
+"""
+Base class for prompt templates.
+
+Defines abstract interface that both string and chat template variants must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BasePromptTemplate(ABC):
+    """
+    Abstract base class for prompt templates (string and chat).
+
+    All prompt template implementations must provide a format method
+    that takes variables and returns formatted output.
+    """
+
+    @abstractmethod
+    def format(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Format the template with the provided variables.
+
+        Returns:
+            Formatted output. Type depends on the implementation:
+            - PromptTemplate returns str
+            - ChatPromptTemplate returns List[Dict[str, MessageContent]]
+        """
+        pass

opik/api_objects/prompt/chat/__init__.py

@@ -0,0 +1 @@
+# Empty - all exports handled by parent __init__.py

opik/api_objects/prompt/chat/chat_prompt.py

@@ -0,0 +1,193 @@
+import copy
+import json
+from typing import Any, Dict, List, Optional
+from typing_extensions import override
+
+from opik.rest_api import types as rest_api_types
+from . import chat_prompt_template
+from .. import client as prompt_client
+from .. import types as prompt_types
+from .. import base_prompt
+
+
+class ChatPrompt(base_prompt.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.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        messages: List[Dict[str, prompt_types.MessageContent]],
+        metadata: Optional[Dict[str, Any]] = None,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+        validate_placeholders: bool = False,
+    ) -> 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.
+
+        Raises:
+            PromptTemplateStructureMismatch: If a text prompt with the same name already exists (template structure is immutable).
+        """
+
+        self._chat_template = chat_prompt_template.ChatPromptTemplate(
+            messages=messages,
+            template_type=type,
+            validate_placeholders=validate_placeholders,
+        )
+        self._name = name
+        self._metadata = metadata
+        self._type = type
+        self._messages = messages
+        self._commit: Optional[str] = None
+        self.__internal_api__prompt_id__: str
+        self.__internal_api__version_id__: str
+
+        self._sync_with_backend()
+
+    def _sync_with_backend(self) -> None:
+        from opik.api_objects import opik_client
+
+        opik_client_ = opik_client.get_client_cached()
+        prompt_client_ = prompt_client.PromptClient(opik_client_.rest_client)
+
+        # Convert messages array to JSON string for backend storage
+        messages_str = json.dumps(self._messages)
+
+        prompt_version = prompt_client_.create_prompt(
+            name=self._name,
+            prompt=messages_str,
+            metadata=self._metadata,
+            type=self._type,
+            template_structure="chat",
+        )
+
+        self._commit = prompt_version.commit
+        self.__internal_api__prompt_id__ = prompt_version.prompt_id
+        self.__internal_api__version_id__ = prompt_version.id
+
+    @property
+    @override
+    def name(self) -> str:
+        """The name of the prompt."""
+        return self._name
+
+    @property
+    def template(self) -> List[Dict[str, prompt_types.MessageContent]]:
+        """The chat messages template."""
+        return copy.deepcopy(self._messages)
+
+    @property
+    @override
+    def commit(self) -> Optional[str]:
+        """The commit hash of the prompt."""
+        return self._commit
+
+    @property
+    @override
+    def metadata(self) -> Optional[Dict[str, Any]]:
+        """The metadata dictionary associated with the prompt"""
+        return copy.deepcopy(self._metadata)
+
+    @property
+    @override
+    def type(self) -> prompt_types.PromptType:
+        """The prompt type of the prompt."""
+        return self._type
+
+    @override
+    def format(
+        self,
+        variables: Dict[str, Any],
+        supported_modalities: Optional[prompt_types.SupportedModalities] = None,
+    ) -> List[Dict[str, prompt_types.MessageContent]]:
+        """
+        Renders the chat template with provided variables.
+
+        Args:
+            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.
+        """
+        if supported_modalities is None:
+            supported_modalities = {
+                "vision": True,
+                "video": True,
+            }
+
+        return self._chat_template.format(
+            variables=variables, supported_modalities=supported_modalities
+        )
+
+    @override
+    def __internal_api__to_info_dict__(self) -> Dict[str, Any]:
+        """
+        Convert the prompt to an info dictionary for serialization.
+
+        Returns:
+            Dictionary containing prompt metadata and version information.
+        """
+        info_dict: Dict[str, Any] = {
+            "name": self.name,
+            "version": {
+                "template": self.template,
+            },
+        }
+
+        if self.__internal_api__prompt_id__ is not None:
+            info_dict["id"] = self.__internal_api__prompt_id__
+
+        if self.commit is not None:
+            info_dict["version"]["commit"] = self.commit
+
+        if self.__internal_api__version_id__ is not None:
+            info_dict["version"]["id"] = self.__internal_api__version_id__
+
+        return info_dict
+
+    @classmethod
+    def from_fern_prompt_version(
+        cls,
+        name: str,
+        prompt_version: rest_api_types.PromptVersionDetail,
+    ) -> "ChatPrompt":
+        # will not call __init__ to avoid API calls, create new instance with __new__
+        chat_prompt = cls.__new__(cls)
+
+        chat_prompt.__internal_api__version_id__ = prompt_version.id
+        chat_prompt.__internal_api__prompt_id__ = prompt_version.prompt_id
+
+        chat_prompt._name = name
+
+        # Parse messages from JSON string
+        messages = json.loads(prompt_version.template)
+        chat_prompt._messages = messages
+        chat_prompt._chat_template = chat_prompt_template.ChatPromptTemplate(
+            messages=messages,
+            template_type=prompt_types.PromptType(prompt_version.type)
+            or prompt_types.PromptType.MUSTACHE,
+        )
+        chat_prompt._commit = prompt_version.commit
+        chat_prompt._metadata = prompt_version.metadata
+        chat_prompt._type = prompt_version.type
+        return chat_prompt

opik/api_objects/prompt/chat/chat_prompt_template.py

@@ -0,0 +1,350 @@
+"""
+Tools for rendering chat-style prompts with multimodal content.
+
+The template mirrors :class:`PromptTemplate` but works on a list of OpenAI-like
+messages. Rendering is handled by a registry of part renderers so additional
+modalities can be plugged in without changing the core implementation.
+"""
+
+import re
+from typing import Any, Dict, List, Optional, Set, Union, cast
+from typing_extensions import override
+
+import opik.exceptions as exceptions
+
+from ..text import prompt_template
+from .. import types as prompt_types
+from .. import base_prompt_template
+from . import content_renderer_registry
+
+
+class ChatPromptTemplate(base_prompt_template.BasePromptTemplate):
+    """
+    Prompt template for chat-style prompts with multimodal content.
+
+    This class handles OpenAI-like message formats with support for text, images,
+    and video content. Templates use Mustache syntax (``{{variable}}``) by default
+    for variable substitution.
+
+    Args:
+        messages: List of message dictionaries with "role" and "content" keys.
+            Content can be a string or a list of content parts (text, image_url, video_url).
+        template_type: Template syntax to use for variable substitution.
+            Defaults to :class:`~opik.api_objects.prompt.types.PromptType.MUSTACHE`.
+        registry: Custom content renderer registry. If None, uses the default registry
+            with built-in support for text, image, and video rendering.
+        validate_placeholders: If True, raises an exception when template placeholders
+            don't match the provided variables during formatting.
+
+    Example:
+        Simple text-based chat template with variables::
+
+            template = ChatPromptTemplate([
+                {
+                    "role": "system",
+                    "content": "You are a helpful assistant specializing in {{domain}}."
+                },
+                {
+                    "role": "user",
+                    "content": "Explain {{topic}} in simple terms."
+                }
+            ])
+
+            messages = template.format({
+                "domain": "physics",
+                "topic": "quantum entanglement"
+            })
+
+        Multimodal template with image content::
+
+            template = ChatPromptTemplate([
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "What is in this image from {{location}}?"
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": "{{image_path}}",
+                                "detail": "high"
+                            }
+                        }
+                    ]
+                }
+            ])
+
+            messages = template.format({
+                "location": "Paris",
+                "image_path": "https://example.com/photo.jpg"
+            })
+
+        Template with video content::
+
+            template = ChatPromptTemplate([
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Analyze this video: {{description}}"
+                        },
+                        {
+                            "type": "video_url",
+                            "video_url": {
+                                "url": "{{video_url}}",
+                                "mime_type": "video/mp4"
+                            }
+                        }
+                    ]
+                }
+            ])
+
+            messages = template.format({
+                "description": "traffic analysis",
+                "video_url": "https://example.com/traffic.mp4"
+            })
+
+        When formatting with unsupported modalities, the content is replaced with
+        placeholders::
+
+            messages = template.format(
+                {"video_url": "https://example.com/video.mp4"},
+                supported_modalities={"text"}  # video not supported
+            )
+            # Returns: [{"role": "user", "content": "Analyze this video\\n<<<video>>><<</video>>>"}]
+    """
+
+    def __init__(
+        self,
+        messages: List[Dict[str, prompt_types.MessageContent]],
+        template_type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+        *,
+        registry: Optional[
+            content_renderer_registry.ChatContentRendererRegistry
+        ] = None,
+        validate_placeholders: bool = False,
+    ) -> None:
+        self._messages = messages
+        self._template_type = template_type
+        self._registry = (
+            registry or content_renderer_registry.DEFAULT_CHAT_RENDERER_REGISTRY
+        )
+        self._validate_placeholders = validate_placeholders
+
+    @property
+    def messages(self) -> List[Dict[str, prompt_types.MessageContent]]:
+        return self._messages
+
+    def required_modalities(self) -> prompt_types.ModalitySet:
+        """
+        Return the union of modalities referenced across all template messages.
+        """
+        required: prompt_types.ModalitySet = set()
+        for message in self._messages:
+            content = cast(prompt_types.MessageContent, message.get("content", ""))
+            required.update(self._registry.infer_modalities(content))
+        return required
+
+    def _extract_placeholders(self, template_type: prompt_types.PromptType) -> Set[str]:
+        """
+        Extract all placeholders from all messages.
+        """
+        placeholders: Set[str] = set()
+        for message in self._messages:
+            content = cast(prompt_types.MessageContent, message.get("content", ""))
+            if isinstance(content, str):
+                placeholders.update(
+                    _extract_placeholders_from_string(content, template_type)
+                )
+            elif isinstance(content, list):
+                for part in content:
+                    if not isinstance(part, dict):
+                        continue
+                    # Extract from text parts
+                    if "text" in part:
+                        text = str(part["text"])
+                        placeholders.update(
+                            _extract_placeholders_from_string(text, template_type)
+                        )
+                    # Extract from image_url parts
+                    if "image_url" in part and isinstance(part["image_url"], dict):
+                        url = str(part["image_url"].get("url", ""))
+                        placeholders.update(
+                            _extract_placeholders_from_string(url, template_type)
+                        )
+        return placeholders
+
+    @override
+    def format(
+        self,
+        variables: Dict[str, Any],
+        supported_modalities: Optional[prompt_types.SupportedModalities] = None,
+        *,
+        template_type: Optional[Union[str, prompt_types.PromptType]] = None,
+    ) -> List[Dict[str, prompt_types.MessageContent]]:
+        """
+        Render the template messages with the provided variables.
+
+        When a part declares a modality that is not supported, the registry replaces
+        it with the configured placeholder pair (for example ``<<<image>>>``) so
+        downstream consumers receive a textual anchor while unsupported structured
+        content is gracefully elided.
+        """
+        resolved_template_type = self._registry.normalize_template_type(
+            template_type or self._template_type
+        )
+
+        # Validate placeholders if enabled and using Mustache templates
+        if (
+            self._validate_placeholders
+            and resolved_template_type == prompt_types.PromptType.MUSTACHE
+        ):
+            placeholders = self._extract_placeholders(resolved_template_type)
+            variables_keys: Set[str] = set(variables.keys())
+
+            if variables_keys != placeholders:
+                raise exceptions.PromptPlaceholdersDontMatchFormatArguments(
+                    prompt_placeholders=placeholders, format_arguments=variables_keys
+                )
+
+        rendered_messages: List[Dict[str, prompt_types.MessageContent]] = []
+
+        for message in self._messages:
+            role = message.get("role")
+            if role is None:
+                continue
+
+            content = cast(prompt_types.MessageContent, message.get("content", ""))
+            rendered_content: prompt_types.MessageContent
+            if isinstance(content, str):
+                rendered_content = _render_template_string(
+                    content, variables, resolved_template_type
+                )
+            else:
+                rendered_content = self._registry.render_content(
+                    content=cast(prompt_types.MessageContent, content),
+                    variables=variables,
+                    template_type=resolved_template_type,
+                    supported_modalities=supported_modalities,
+                )
+            rendered_messages.append(
+                {
+                    "role": role,
+                    "content": rendered_content,
+                }
+            )
+
+        return rendered_messages
+
+
+def _render_template_string(
+    template: str,
+    variables: Dict[str, Any],
+    template_type: prompt_types.PromptType,
+) -> str:
+    if not template:
+        return ""
+
+    try:
+        return prompt_template.PromptTemplate(
+            template,
+            validate_placeholders=False,
+            type=template_type,
+        ).format(**variables)
+    except Exception:
+        # Fall back to the raw template if formatting fails so evaluation keeps running.
+        return template
+
+
+def render_text_part(
+    part: prompt_types.ContentPart,
+    variables: Dict[str, Any],
+    template_type: prompt_types.PromptType,
+) -> Optional[prompt_types.ContentPart]:
+    text_template = part.get("text", "")
+    rendered_text = _render_template_string(text_template, variables, template_type)
+    return {"type": "text", "text": rendered_text}
+
+
+def render_image_url_part(
+    part: prompt_types.ContentPart,
+    variables: Dict[str, Any],
+    template_type: prompt_types.PromptType,
+) -> Optional[prompt_types.ContentPart]:
+    image_dict = part.get("image_url", {})
+    if not isinstance(image_dict, dict):
+        return None
+
+    url_template = image_dict.get("url", "")
+    rendered_url = _render_template_string(url_template, variables, template_type)
+    if not rendered_url:
+        return None
+
+    rendered_image: Dict[str, Any] = {"url": rendered_url}
+    if "detail" in image_dict:
+        rendered_image["detail"] = image_dict["detail"]
+
+    return {"type": "image_url", "image_url": rendered_image}
+
+
+def render_video_url_part(
+    part: prompt_types.ContentPart,
+    variables: Dict[str, Any],
+    template_type: prompt_types.PromptType,
+) -> Optional[prompt_types.ContentPart]:
+    """
+    Render a ``video_url`` part and preserve optional metadata.
+
+    In addition to the rendered ``url`` we keep:
+
+    - ``detail``: free-form provider hints (mirrors the image renderer semantics).
+    - ``mime_type``: the content type callers expect the downstream model to load.
+    - ``duration``: client-supplied duration in seconds to give hosts extra context.
+    - ``format``: a short format label (``mp4``, ``webm``, etc.) when known.
+    """
+    video_dict = part.get("video_url", {})
+    if not isinstance(video_dict, dict):
+        return None
+
+    url_template = video_dict.get("url", "")
+    rendered_url = _render_template_string(url_template, variables, template_type)
+    if not rendered_url:
+        return None
+
+    rendered_video: Dict[str, Any] = {"url": rendered_url}
+    for key in ("detail", "mime_type", "duration", "format"):
+        if key in video_dict:
+            rendered_video[key] = video_dict[key]
+
+    return {"type": "video_url", "video_url": rendered_video}
+
+
+def _extract_placeholders_from_string(
+    text: str, template_type: prompt_types.PromptType
+) -> Set[str]:
+    """
+    Extract placeholder keys from a string template.
+    Only supports Mustache templates for now.
+    """
+    if template_type == prompt_types.PromptType.MUSTACHE:
+        pattern = r"\{\{(.*?)\}\}"
+        return set(re.findall(pattern, text))
+    return set()
+
+
+content_renderer_registry.register_default_chat_part_renderer("text", render_text_part)
+content_renderer_registry.register_default_chat_part_renderer(
+    "image_url",
+    render_image_url_part,
+    modality="vision",
+    placeholder=("<<<image>>>", "<<</image>>>"),
+)
+content_renderer_registry.register_default_chat_part_renderer(
+    "video_url",
+    render_video_url_part,
+    modality="video",
+    placeholder=("<<<video>>>", "<<</video>>>"),
+)