opik 1.8.39__py3-none-any.whl → 1.9.71__py3-none-any.whl

opik/api_objects/prompt/client.py

@@ -1,10 +1,21 @@
-from typing import Any, Dict, List, Optional
+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:
@@ -16,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.
@@ -24,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
@@ -46,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,
@@ -58,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
@@ -65,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.
@@ -86,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.
@@ -95,17 +142,35 @@ class PromptClient:
                 name=name,
                 commit=commit,
             )
-            return prompt_version
 
+            should_skip_validation = (
+                prompt_version.template_structure is None
+                and raise_if_not_template_structure == "text"
+            )
+            if should_skip_validation:
+                return prompt_version
+
+            # Client-side validation for template_structure if requested and not skipped
+            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
     # need to retrieve the prompt id
-    def get_all_prompts(
+    def get_all_prompt_versions(
         self, name: str
     ) -> List[prompt_version_detail.PromptVersionDetail]:
         """
@@ -134,42 +199,119 @@ class PromptClient:
                 raise ValueError("No prompts found for name: " + name)
 
             prompt_id = filtered_prompt_list[0]
+            return self._get_prompt_versions_by_id_paginated(prompt_id)
 
-            page = 1
-            size = 100
+        except rest_api_core.ApiError as e:
+            if e.status_code != 404:
+                raise e
+
+        return []
+
+    def _get_prompt_versions_by_id_paginated(
+        self, prompt_id: str
+    ) -> List[prompt_version_detail.PromptVersionDetail]:
+        page = 1
+        size = 100
+        prompts: List[prompt_version_detail.PromptVersionDetail] = []
+        while True:
+            prompt_versions_page = self._rest_client.prompts.get_prompt_versions(
+                id=prompt_id, page=page, size=size
+            ).content
+
+            versions = prompt_versions_page or []
+            prompts.extend(
+                [
+                    # Converting to PromptVersionDetail for consistency with other methods.
+                    # TODO: backend should implement non-frontend endpoint which will return PromptVersionDetail objects
+                    prompt_version_detail.PromptVersionDetail(
+                        id=version.id,
+                        prompt_id=version.prompt_id,
+                        template=version.template,
+                        type=version.type,
+                        metadata=version.metadata,
+                        commit=version.commit,
+                        created_at=version.created_at,
+                        created_by=version.created_by,
+                    )
+                    for version in versions
+                ]
+            )
+
+            if len(versions) < size:
+                break
+            page += 1
+
+        return prompts
+
+    def search_prompts(
+        self,
+        *,
+        name: Optional[str] = None,
+        parsed_filters: Optional[List[Dict[str, Any]]] = None,
+    ) -> List[PromptSearchResult]:
+        """
+        Search prompt containers by optional name substring and filters, then
+        return the latest version detail for each matched prompt container.
+
+        Parameters:
+            name: Optional substring of the prompt name to search for.
+            parsed_filters: List of parsed filters (OQL) that will be stringified for the backend.
+
+        Returns:
+            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
+            )
 
-            prompts: List[prompt_version_detail.PromptVersionDetail] = []
+            # Page through all prompt containers and collect name + template_structure
+            page = 1
+            size = 1000
+            prompt_info: List[Tuple[str, str]] = []  # (name, template_structure)
             while True:
-                prompt_versions = self._rest_client.prompts.get_prompt_versions(
-                    id=prompt_id, page=page, size=size
-                ).content
-
-                prompts.extend(
-                    [
-                        # Converting to PromptVersionDetail for consistency with other methods.
-                        # TODO: backend should implement non-frontend endpoint which will return PromptVersionDetail objects
-                        prompt_version_detail.PromptVersionDetail(
-                            id=version.id,
-                            prompt_id=version.prompt_id,
-                            template=version.template,
-                            type=version.type,
-                            metadata=version.metadata,
-                            commit=version.commit,
-                            created_at=version.created_at,
-                            created_by=version.created_by,
-                        )
-                        for version in prompt_versions
-                    ]
+                prompts_page = self._rest_client.prompts.get_prompts(
+                    page=page,
+                    size=size,
+                    name=name,
+                    filters=filters_str,
                 )
-
-                if len(prompt_versions) < size:
+                content = prompts_page.content or []
+                if len(content) == 0:
+                    break
+                prompt_info.extend(
+                    [(p.name, p.template_structure or "text") for p in content]
+                )
+                if len(content) < size:
                     break
                 page += 1
 
-            return prompts
+            if len(prompt_info) == 0:
+                return []
+
+            # Retrieve latest version for each container name
+            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
 
         except rest_api_core.ApiError as e:
             if e.status_code != 404:
                 raise e
-
-        return []
+            return []

opik/api_objects/prompt/text/__init__.py

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

opik/api_objects/prompt/text/prompt.py

@@ -0,0 +1,174 @@
+import copy
+import json
+import logging
+from typing import Any, Dict, Optional, Union, List
+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(base_prompt.BasePrompt):
+    """
+    Prompt class represents a prompt with a name, prompt text/template and commit hash.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        prompt: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        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 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 = prompt_template.PromptTemplate(
+            template=prompt, type=type, validate_placeholders=validate_placeholders
+        )
+        self._name = name
+        self._metadata = metadata
+        self._type = type
+
+        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)
+        prompt_version = prompt_client_.create_prompt(
+            name=self._name,
+            prompt=self._template.text,
+            metadata=self._metadata,
+            type=self._type,
+        )
+
+        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 prompt(self) -> str:
+        """The latest template of the 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
+    @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.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments where the key represents the placeholder
+                      in the template and the value is the value to replace the placeholder with.
+
+        Returns:
+            A string with all placeholders replaced by their corresponding values from kwargs.
+        """
+        is_playground_chat_prompt = (
+            self._metadata is not None
+            and self._metadata.get("created_from") == "opik_ui"
+            and self._metadata.get("type") == "messages_json"
+        )
+        formatted_string = self._template.format(**kwargs)
+
+        if is_playground_chat_prompt:
+            try:
+                return json.loads(formatted_string)
+            except json.JSONDecodeError:
+                LOGGER.error(
+                    f"Failed to parse JSON string: {formatted_string}. Make sure chat prompt is valid JSON. Returning the raw string."
+                )
+                return formatted_string
+
+        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: rest_api_types.PromptVersionDetail,
+    ) -> "Prompt":
+        # will not call __init__ to avoid API calls, create new instance with __new__
+        prompt = cls.__new__(cls)
+
+        prompt.__internal_api__version_id__ = prompt_version.id
+        prompt.__internal_api__prompt_id__ = prompt_version.prompt_id
+
+        prompt._name = name
+        prompt._template = prompt_template.PromptTemplate(
+            template=prompt_version.template,
+            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

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())
@@ -33,9 +36,10 @@ class PromptTemplate:
                 )
 
             for key, value in kwargs.items():
-                template = template.replace(f"{{{{{key}}}}}", str(value))
+                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/api_objects/prompt/types.py

@@ -1,6 +1,29 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Literal, Mapping, Optional, Union, Set
+
 import enum
 
 
 class PromptType(str, enum.Enum):
     MUSTACHE = "mustache"
     JINJA2 = "jinja2"
+
+
+# Core multimodal/chat prompt related types
+MessageContent = Union[str, List[Dict[str, Any]]]
+ContentPart = Dict[str, Any]
+RendererFn = Callable[[ContentPart, Dict[str, Any], PromptType], Optional[ContentPart]]
+ModalityName = Literal["vision", "video"]
+SupportedModalities = Mapping[ModalityName, bool]
+ModalitySet = Set[ModalityName]
+
+__all__ = [
+    "PromptType",
+    "MessageContent",
+    "ContentPart",
+    "RendererFn",
+    "ModalityName",
+    "SupportedModalities",
+    "ModalitySet",
+]

opik/api_objects/search_helpers.py

@@ -0,0 +1,89 @@
+from typing import Optional, List, Callable, Any
+
+from opik import synchronization
+from opik.api_objects import rest_stream_parser
+from opik.api_objects.helpers import OptionalFilterParsedItemList
+from opik.rest_api import client as rest_api_client
+from opik.rest_api.types import span_public, trace_public
+
+
+def search_spans_with_filters(
+    rest_client: rest_api_client.OpikApi,
+    trace_id: Optional[str],
+    project_name: str,
+    filters: Optional[OptionalFilterParsedItemList],
+    max_results: int,
+    truncate: bool,
+) -> List[span_public.SpanPublic]:
+    spans = rest_stream_parser.read_and_parse_full_stream(
+        read_source=lambda current_batch_size,
+        last_retrieved_id: rest_client.spans.search_spans(
+            trace_id=trace_id,
+            project_name=project_name,
+            filters=filters,
+            limit=current_batch_size,
+            truncate=truncate,
+            last_retrieved_id=last_retrieved_id,
+        ),
+        max_results=max_results,
+        parsed_item_class=span_public.SpanPublic,
+    )
+
+    return spans
+
+
+def search_traces_with_filters(
+    rest_client: rest_api_client.OpikApi,
+    project_name: Optional[str],
+    filters: Optional[OptionalFilterParsedItemList],
+    max_results: int,
+    truncate: bool,
+) -> List[trace_public.TracePublic]:
+    traces = rest_stream_parser.read_and_parse_full_stream(
+        read_source=lambda current_batch_size,
+        last_retrieved_id: rest_client.traces.search_traces(
+            project_name=project_name,
+            filters=filters,
+            limit=current_batch_size,
+            truncate=truncate,
+            last_retrieved_id=last_retrieved_id,
+        ),
+        max_results=max_results,
+        parsed_item_class=trace_public.TracePublic,
+    )
+    return traces
+
+
+def search_and_wait_for_done(
+    search_functor: Callable[[], List[Any]],
+    wait_for_at_least: int,
+    wait_for_timeout: int,
+    sleep_time: float,
+) -> List[Any]:
+    """
+    The expected behavior is to keep making repeated calls until either the specified number of
+    results is found or the timeout is reached. The function will then return the best possible
+    attempt results to meet these conditions.
+    Args:
+        search_functor: The function to call to retrieve the results.
+        wait_for_at_least: The minimum number of results to return.
+        wait_for_timeout: The timeout for waiting for results.
+        sleep_time: The time to sleep between calls to search_functor.
+
+    Returns:
+        The function returns the results of the best possible attempt to meet both waiting conditions.
+    """
+    result: List[Any] = []
+
+    def search() -> List[Any]:
+        nonlocal result
+        result = search_functor()
+        return result
+
+    synchronization.wait_for_done(
+        check_function=lambda: len(search()) >= wait_for_at_least,
+        timeout=wait_for_timeout,
+        sleep_time=sleep_time,
+    )
+
+    return result