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

opik/api_objects/prompt/{chat_content_renderer_registry.py → chat/content_renderer_registry.py}

@@ -1,15 +1,6 @@
-from __future__ import annotations
-
 from typing import Any, Dict, List, Mapping, MutableMapping, Optional, Tuple, Union
 
-from .types import (
-    ContentPart,
-    MessageContent,
-    ModalityName,
-    RendererFn,
-    SupportedModalities,
-    PromptType,
-)
+from .. import types as prompt_types
 
 
 class ChatContentRendererRegistry:
@@ -18,9 +9,13 @@ class ChatContentRendererRegistry:
     """
 
     def __init__(self) -> None:
-        self._part_renderers: MutableMapping[str, RendererFn] = {}
-        self._part_modalities: MutableMapping[str, Optional[ModalityName]] = {}
-        self._modality_placeholders: MutableMapping[ModalityName, Tuple[str, str]] = {
+        self._part_renderers: MutableMapping[str, prompt_types.RendererFn] = {}
+        self._part_modalities: MutableMapping[
+            str, Optional[prompt_types.ModalityName]
+        ] = {}
+        self._modality_placeholders: MutableMapping[
+            prompt_types.ModalityName, Tuple[str, str]
+        ] = {
             "vision": ("<<<image>>>", "<<</image>>>"),
             "video": ("<<<video>>>", "<<</video>>>"),
         }
@@ -30,9 +25,9 @@ class ChatContentRendererRegistry:
     def register_part_renderer(
         self,
         part_type: str,
-        renderer: RendererFn,
+        renderer: prompt_types.RendererFn,
         *,
-        modality: Optional[ModalityName] = None,
+        modality: Optional[prompt_types.ModalityName] = None,
         placeholder: Optional[Tuple[str, str]] = None,
     ) -> None:
         """
@@ -47,12 +42,12 @@ class ChatContentRendererRegistry:
 
     def render_content(
         self,
-        content: MessageContent,
+        content: prompt_types.MessageContent,
         variables: Dict[str, Any],
-        template_type: PromptType,
+        template_type: prompt_types.PromptType,
         *,
-        supported_modalities: Optional[SupportedModalities] = None,
-    ) -> MessageContent:
+        supported_modalities: Optional[prompt_types.SupportedModalities] = None,
+    ) -> prompt_types.MessageContent:
         if supported_modalities is None:
             modality_flags: Dict[str, bool] = {}
         else:
@@ -84,19 +79,21 @@ class ChatContentRendererRegistry:
         return rendered_parts
 
     def normalize_template_type(
-        self, template_type: Union[str, PromptType]
-    ) -> PromptType:
-        if isinstance(template_type, PromptType):
+        self, template_type: Union[str, prompt_types.PromptType]
+    ) -> prompt_types.PromptType:
+        if isinstance(template_type, prompt_types.PromptType):
             return template_type
         try:
-            return PromptType(template_type)
+            return prompt_types.PromptType(template_type)
         except ValueError:
-            return PromptType.MUSTACHE
+            return prompt_types.PromptType.MUSTACHE
 
-    def infer_modalities(self, content: MessageContent) -> set[ModalityName]:
+    def infer_modalities(
+        self, content: prompt_types.MessageContent
+    ) -> set[prompt_types.ModalityName]:
         if not isinstance(content, list):
             return set()
-        modalities: set[ModalityName] = set()
+        modalities: set[prompt_types.ModalityName] = set()
         for part in content:
             if not isinstance(part, dict):
                 continue
@@ -110,9 +107,9 @@ class ChatContentRendererRegistry:
         self,
         content: List[Any],
         variables: Dict[str, Any],
-        template_type: PromptType,
-    ) -> List[ContentPart]:
-        rendered_parts: List[ContentPart] = []
+        template_type: prompt_types.PromptType,
+    ) -> List[prompt_types.ContentPart]:
+        rendered_parts: List[prompt_types.ContentPart] = []
         for part in content:
             if not isinstance(part, dict):
                 continue
@@ -127,7 +124,7 @@ class ChatContentRendererRegistry:
         return rendered_parts
 
     def _should_flatten(
-        self, parts: List[ContentPart], modality_flags: Mapping[str, bool]
+        self, parts: List[prompt_types.ContentPart], modality_flags: Mapping[str, bool]
     ) -> bool:
         for part in parts:
             modality = self._part_modalities.get(part.get("type", "").lower())
@@ -136,7 +133,7 @@ class ChatContentRendererRegistry:
         return False
 
     def _flatten_parts_to_text(
-        self, parts: List[ContentPart], modality_flags: Mapping[str, bool]
+        self, parts: List[prompt_types.ContentPart], modality_flags: Mapping[str, bool]
     ) -> str:
         segments: List[str] = []
         for part in parts:
@@ -161,7 +158,7 @@ class ChatContentRendererRegistry:
         return "\n\n".join(segment for segment in segments if segment)
 
     @staticmethod
-    def _extract_placeholder_value(part: ContentPart) -> str:
+    def _extract_placeholder_value(part: prompt_types.ContentPart) -> str:
         part_type = part.get("type", "").lower()
         if part_type == "image_url":
             image_dict = part.get("image_url", {})
@@ -186,9 +183,9 @@ DEFAULT_CHAT_RENDERER_REGISTRY = ChatContentRendererRegistry()
 
 def register_default_chat_part_renderer(
     part_type: str,
-    renderer: RendererFn,
+    renderer: prompt_types.RendererFn,
     *,
-    modality: Optional[ModalityName] = None,
+    modality: Optional[prompt_types.ModalityName] = None,
     placeholder: Optional[Tuple[str, str]] = None,
 ) -> None:
     DEFAULT_CHAT_RENDERER_REGISTRY.register_part_renderer(

opik/api_objects/prompt/client.py

@@ -1,11 +1,21 @@
 from typing import Any, Dict, List, Optional, Tuple
 import json
+import dataclasses
 
+import opik.exceptions
 from opik.rest_api import client as rest_client
 from opik.rest_api import core as rest_api_core
-from opik.rest_api.types import prompt_version_detail, PromptVersionDetailType
+from opik.rest_api.types import prompt_version_detail
+from . import types as prompt_types
 
-from .prompt import PromptType
+
+@dataclasses.dataclass
+class PromptSearchResult:
+    """Result from searching prompts, containing name, template structure, and latest version details."""
+
+    name: str
+    template_structure: str
+    prompt_version_detail: prompt_version_detail.PromptVersionDetail
 
 
 class PromptClient:
@@ -17,7 +27,8 @@ class PromptClient:
         name: str,
         prompt: str,
         metadata: Optional[Dict[str, Any]],
-        type: PromptType = PromptType.MUSTACHE,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+        template_structure: str = "text",
     ) -> prompt_version_detail.PromptVersionDetail:
         """
         Creates the prompt detail for the given prompt name and template.
@@ -25,20 +36,59 @@ class PromptClient:
         Parameters:
         - name: The name of the prompt.
         - prompt: The template content for the prompt.
+        - metadata: Optional metadata for the prompt.
+        - type: The template type (MUSTACHE or JINJA2).
+        - template_structure: Either "text" (default) or "chat".
 
         Returns:
         - A Prompt object for the provided prompt name and template.
+
+        Raises:
+        - PromptTemplateStructureMismatch: If a prompt with the same name already exists but has a different
+          template_structure (e.g., trying to create a text prompt when a chat prompt exists, or vice versa).
+          Template structure is immutable after prompt creation.
         """
         prompt_version = self._get_latest_version(name)
 
+        # For chat prompts, compare parsed JSON to avoid formatting differences
+        templates_equal = False
+
+        if prompt_version is not None:
+            if prompt_version.template_structure != template_structure:
+                raise opik.exceptions.PromptTemplateStructureMismatch(
+                    prompt_name=name,
+                    existing_structure=prompt_version.template_structure,
+                    attempted_structure=template_structure,
+                )
+
+            if template_structure == "chat":
+                try:
+                    existing_messages = json.loads(prompt_version.template)
+                    new_messages = json.loads(prompt)
+                    templates_equal = existing_messages == new_messages
+                except (json.JSONDecodeError, TypeError):
+                    templates_equal = prompt_version.template == prompt
+            else:
+                templates_equal = prompt_version.template == prompt
+
+        # Create a new version if:
+        # - No version exists yet (new prompt)
+        # - Template content has changed
+        # - Metadata has changed
+        # - Type has changed
+        # Note: template_structure is immutable and used by the backend only if it is the first prompt version.
         if (
             prompt_version is None
-            or prompt_version.template != prompt
+            or not templates_equal
             or prompt_version.metadata != metadata
             or prompt_version.type != type.value
         ):
             prompt_version = self._create_new_version(
-                name=name, prompt=prompt, type=type, metadata=metadata
+                name=name,
+                prompt=prompt,
+                type=type,
+                metadata=metadata,
+                template_structure=template_structure,
             )
 
         return prompt_version
@@ -47,8 +97,9 @@ class PromptClient:
         self,
         name: str,
         prompt: str,
-        type: PromptVersionDetailType,
+        type: prompt_version_detail.PromptVersionDetailType,
         metadata: Optional[Dict[str, Any]],
+        template_structure: str = "text",
     ) -> prompt_version_detail.PromptVersionDetail:
         new_prompt_version_detail_data = prompt_version_detail.PromptVersionDetail(
             template=prompt,
@@ -59,6 +110,7 @@ class PromptClient:
             self._rest_client.prompts.create_prompt_version(
                 name=name,
                 version=new_prompt_version_detail_data,
+                template_structure=template_structure,
             )
         )
         return new_prompt_version_detail
@@ -66,20 +118,13 @@ class PromptClient:
     def _get_latest_version(
         self, name: str
     ) -> Optional[prompt_version_detail.PromptVersionDetail]:
-        try:
-            prompt_latest_version = self._rest_client.prompts.retrieve_prompt_version(
-                name=name
-            )
-            return prompt_latest_version
-        except rest_api_core.ApiError as e:
-            if e.status_code != 404:
-                raise e
-            return None
+        return self.get_prompt(name=name, commit=None)
 
     def get_prompt(
         self,
         name: str,
         commit: Optional[str] = None,
+        raise_if_not_template_structure: Optional[str] = None,
     ) -> Optional[prompt_version_detail.PromptVersionDetail]:
         """
         Retrieve the prompt detail for a given prompt name and commit version.
@@ -87,6 +132,7 @@ class PromptClient:
         Parameters:
             name: The name of the prompt.
             commit: An optional commit version of the prompt. If not provided, the latest version is retrieved.
+            raise_if_not_template_structure: Optional template structure validation. If provided and doesn't match, raises PromptTemplateStructureMismatch.
 
         Returns:
             Prompt: The details of the specified prompt.
@@ -96,12 +142,23 @@ class PromptClient:
                 name=name,
                 commit=commit,
             )
-            return prompt_version
 
+            # Client-side validation for template_structure if requested
+            if (
+                raise_if_not_template_structure is not None
+                and prompt_version.template_structure != raise_if_not_template_structure
+            ):
+                raise opik.exceptions.PromptTemplateStructureMismatch(
+                    prompt_name=name,
+                    existing_structure=prompt_version.template_structure,
+                    attempted_structure=raise_if_not_template_structure,
+                )
+
+            return prompt_version
         except rest_api_core.ApiError as e:
             if e.status_code != 404:
                 raise e
-
+            # 400, 404 - not found
         return None
 
     # TODO: Need to add support for prompt name in the BE so we don't
@@ -184,7 +241,7 @@ class PromptClient:
         *,
         name: Optional[str] = None,
         parsed_filters: Optional[List[Dict[str, Any]]] = None,
-    ) -> List[Tuple[str, prompt_version_detail.PromptVersionDetail]]:
+    ) -> List[PromptSearchResult]:
         """
         Search prompt containers by optional name substring and filters, then
         return the latest version detail for each matched prompt container.
@@ -194,17 +251,17 @@ class PromptClient:
             parsed_filters: List of parsed filters (OQL) that will be stringified for the backend.
 
         Returns:
-            List[Tuple[str, PromptVersionDetail]]: (prompt name, latest version) for each matched prompt container.
+            List[PromptSearchResult]: Each result contains name, template_structure, and prompt_version_detail.
         """
         try:
             filters_str = (
                 json.dumps(parsed_filters) if parsed_filters is not None else None
             )
 
-            # Page through all prompt containers
+            # Page through all prompt containers and collect name + template_structure
             page = 1
-            size = 100
-            all_prompt_names: List[str] = []
+            size = 1000
+            prompt_info: List[Tuple[str, str]] = []  # (name, template_structure)
             while True:
                 prompts_page = self._rest_client.prompts.get_prompts(
                     page=page,
@@ -215,21 +272,35 @@ class PromptClient:
                 content = prompts_page.content or []
                 if len(content) == 0:
                     break
-                all_prompt_names.extend([p.name for p in content])
+                prompt_info.extend(
+                    [(p.name, p.template_structure or "text") for p in content]
+                )
                 if len(content) < size:
                     break
                 page += 1
 
-            if len(all_prompt_names) == 0:
+            if len(prompt_info) == 0:
                 return []
 
             # Retrieve latest version for each container name
-            results: List[Tuple[str, prompt_version_detail.PromptVersionDetail]] = []
-            for prompt_name in all_prompt_names:
-                latest_version = self._rest_client.prompts.retrieve_prompt_version(
-                    name=prompt_name
-                )
-                results.append((prompt_name, latest_version))
+            results: List[PromptSearchResult] = []
+            for prompt_name, template_structure in prompt_info:
+                try:
+                    latest_version = self._rest_client.prompts.retrieve_prompt_version(
+                        name=prompt_name,
+                    )
+                    results.append(
+                        PromptSearchResult(
+                            name=prompt_name,
+                            template_structure=template_structure,
+                            prompt_version_detail=latest_version,
+                        )
+                    )
+                except rest_api_core.ApiError as e:
+                    # Skip prompts that can't be retrieved (e.g., deleted between search and retrieval)
+                    if e.status_code == 404:
+                        continue
+                    raise e
 
             return results
 

opik/api_objects/prompt/text/__init__.py

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

opik/api_objects/prompt/{prompt.py → text/prompt.py}

@@ -2,16 +2,17 @@ import copy
 import json
 import logging
 from typing import Any, Dict, Optional, Union, List
-
-from opik.rest_api.types import PromptVersionDetail
-from .prompt_template import PromptTemplate
-from .types import PromptType
-from opik.api_objects.prompt import client as prompt_client
+from typing_extensions import override
+from opik.rest_api import types as rest_api_types
+from . import prompt_template
+from .. import types as prompt_types
+from .. import client as prompt_client
+from .. import base_prompt
 
 LOGGER = logging.getLogger(__name__)
 
 
-class Prompt:
+class Prompt(base_prompt.BasePrompt):
     """
     Prompt class represents a prompt with a name, prompt text/template and commit hash.
     """
@@ -21,18 +22,27 @@ class Prompt:
         name: str,
         prompt: str,
         metadata: Optional[Dict[str, Any]] = None,
-        type: PromptType = PromptType.MUSTACHE,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+        validate_placeholders: bool = True,
     ) -> None:
         """
         Initializes a new instance of the class with the given parameters.
-        Creates a new prompt using the opik client and sets the initial state of the instance attributes based on the created prompt.
+        Creates a new text prompt using the opik client and sets the initial state of the instance attributes based on the created prompt.
 
         Parameters:
             name: The name for the prompt.
             prompt: The template for the prompt.
+            metadata: Optional metadata for the prompt.
+            type: The template type (MUSTACHE or JINJA2).
+            validate_placeholders: Whether to validate template placeholders.
+
+        Raises:
+            PromptTemplateStructureMismatch: If a chat prompt with the same name already exists (template structure is immutable).
         """
 
-        self._template = PromptTemplate(template=prompt, type=type)
+        self._template = prompt_template.PromptTemplate(
+            template=prompt, type=type, validate_placeholders=validate_placeholders
+        )
         self._name = name
         self._metadata = metadata
         self._type = type
@@ -56,6 +66,7 @@ class Prompt:
         self.__internal_api__version_id__ = prompt_version.id
 
     @property
+    @override
     def name(self) -> str:
         """The name of the prompt."""
         return self._name
@@ -66,20 +77,24 @@ class Prompt:
         return str(self._template)
 
     @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
-    def type(self) -> PromptType:
+    @override
+    def type(self) -> prompt_types.PromptType:
         """The prompt type of the prompt."""
         return self._type
 
+    @override
     def format(self, **kwargs: Any) -> Union[str, List[Dict[str, Any]]]:
         """
         Replaces placeholders in the template with provided keyword arguments.
@@ -109,11 +124,37 @@ class Prompt:
 
         return formatted_string
 
+    @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.prompt,
+            },
+        }
+
+        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: PromptVersionDetail,
+        prompt_version: rest_api_types.PromptVersionDetail,
     ) -> "Prompt":
         # will not call __init__ to avoid API calls, create new instance with __new__
         prompt = cls.__new__(cls)
@@ -122,30 +163,12 @@ class Prompt:
         prompt.__internal_api__prompt_id__ = prompt_version.prompt_id
 
         prompt._name = name
-        prompt._template = PromptTemplate(
+        prompt._template = prompt_template.PromptTemplate(
             template=prompt_version.template,
-            type=PromptType(prompt_version.type) or PromptType.MUSTACHE,
+            type=prompt_types.PromptType(prompt_version.type)
+            or prompt_types.PromptType.MUSTACHE,
         )
         prompt._commit = prompt_version.commit
         prompt._metadata = prompt_version.metadata
         prompt._type = prompt_version.type
         return prompt
-
-
-def to_info_dict(prompt: Prompt) -> Dict[str, Any]:
-    info_dict: Dict[str, Any] = {
-        "name": prompt.name,
-        "version": {
-            "template": prompt.prompt,
-        },
-    }
-    if prompt.__internal_api__prompt_id__ is not None:
-        info_dict["id"] = prompt.__internal_api__prompt_id__
-
-    if prompt.commit is not None:
-        info_dict["version"]["commit"] = prompt.commit
-
-    if prompt.__internal_api__version_id__ is not None:
-        info_dict["version"]["id"] = prompt.__internal_api__version_id__
-
-    return info_dict

opik/api_objects/prompt/{prompt_template.py → text/prompt_template.py}

@@ -1,17 +1,19 @@
 import re
 from typing import Any, Set
+from typing_extensions import override
 import jinja2
 
 import opik.exceptions as exceptions
-from .types import PromptType
+from .. import types as prompt_types
+from .. import base_prompt_template
 
 
-class PromptTemplate:
+class PromptTemplate(base_prompt_template.BasePromptTemplate):
     def __init__(
         self,
         template: str,
         validate_placeholders: bool = True,
-        type: PromptType = PromptType.MUSTACHE,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
     ) -> None:
         self._template = template
         self._type = type
@@ -21,8 +23,9 @@ class PromptTemplate:
     def text(self) -> str:
         return self._template
 
+    @override
     def format(self, **kwargs: Any) -> str:
-        if self._type == PromptType.MUSTACHE:
+        if self._type == prompt_types.PromptType.MUSTACHE:
             template = self._template
             placeholders = _extract_mustache_placeholder_keys(self._template)
             kwargs_keys: Set[str] = set(kwargs.keys())
@@ -36,7 +39,7 @@ class PromptTemplate:
                 replacement = "" if value is None else str(value)
                 template = template.replace(f"{{{{{key}}}}}", replacement)
 
-        elif self._type == PromptType.JINJA2:
+        elif self._type == prompt_types.PromptType.JINJA2:
             template = jinja2.Template(self._template).render(**kwargs)
         else:
             template = self._template

opik/cli/export.py

@@ -457,14 +457,18 @@ def _export_prompts(
                 prompt_data = {
                     "name": prompt.name,
                     "current_version": {
-                        "prompt": prompt.prompt,
+                        "prompt": prompt.prompt
+                        if isinstance(prompt, opik.Prompt)
+                        else None,  # TODO: add support for chat prompts
                         "metadata": prompt.metadata,
                         "type": prompt.type if prompt.type else None,
                         "commit": prompt.commit,
                     },
                     "history": [
                         {
-                            "prompt": version.prompt,
+                            "prompt": version.prompt
+                            if isinstance(version, opik.Prompt)
+                            else None,  # TODO: add support for chat prompts
                             "metadata": version.metadata,
                             "type": version.type if version.type else None,
                             "commit": version.commit,

opik/config.py

@@ -7,7 +7,6 @@ import pathlib
 import urllib.parse
 from typing import Any, Dict, Final, List, Literal, Optional, Tuple, Type, Union
 
-import opik.decorator.tracing_runtime_config as tracing_runtime_config
 import pydantic
 import pydantic_settings
 from pydantic_settings import BaseSettings, InitSettingsSource
@@ -257,10 +256,6 @@ class OpikConfig(pydantic_settings.BaseSettings):
     def guardrails_backend_host(self) -> str:
         return url_helpers.get_base_url(self.url_override) + "guardrails/"
 
-    @property
-    def runtime(self) -> tracing_runtime_config.TracingRuntimeConfig:
-        return tracing_runtime_config.runtime_cfg
-
     @pydantic.model_validator(mode="after")
     def _set_url_override_from_api_key(self) -> "OpikConfig":
         url_was_not_provided = (