opik 1.6.4__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
+from . import types as prompt_types
 
-from . import prompt as opik_prompt
+
+@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,48 +27,90 @@ class PromptClient:
         name: str,
         prompt: str,
         metadata: Optional[Dict[str, Any]],
-    ) -> opik_prompt.Prompt:
+        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.
 
         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, metadata=metadata
+                name=name,
+                prompt=prompt,
+                type=type,
+                metadata=metadata,
+                template_structure=template_structure,
             )
 
-        prompt_obj = opik_prompt.Prompt.from_fern_prompt_version(
-            name=name, prompt_version=prompt_version
-        )
-
-        return prompt_obj
+        return prompt_version
 
     def _create_new_version(
         self,
         name: str,
         prompt: str,
+        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,
             metadata=metadata,
+            type=type,
         )
         new_prompt_version_detail: prompt_version_detail.PromptVersionDetail = (
             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,27 +118,21 @@ 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,
-    ) -> Optional[opik_prompt.Prompt]:
+        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.
 
         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,22 +142,37 @@ class PromptClient:
                 name=name,
                 commit=commit,
             )
-            prompt_obj = opik_prompt.Prompt.from_fern_prompt_version(
-                name=name,
-                prompt_version=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
 
-            return prompt_obj
+            # 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(self, name: str) -> List[opik_prompt.Prompt]:
+    def get_all_prompt_versions(
+        self, name: str
+    ) -> List[prompt_version_detail.PromptVersionDetail]:
         """
         Retrieve all the prompt details for a given prompt name.
 
@@ -137,29 +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
 
-            prompts: List[opik_prompt.Prompt] = []
+        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
+            )
+
+            # 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(
-                    [
-                        opik_prompt.Prompt.from_fern_prompt_version(name, version)
-                        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/text/prompt_template.py

@@ -0,0 +1,55 @@
+import re
+from typing import Any, Set
+from typing_extensions import override
+import jinja2
+
+import opik.exceptions as exceptions
+from .. import types as prompt_types
+from .. import base_prompt_template
+
+
+class PromptTemplate(base_prompt_template.BasePromptTemplate):
+    def __init__(
+        self,
+        template: str,
+        validate_placeholders: bool = True,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+    ) -> None:
+        self._template = template
+        self._type = type
+        self._validate_placeholders = validate_placeholders
+
+    @property
+    def text(self) -> str:
+        return self._template
+
+    @override
+    def format(self, **kwargs: Any) -> str:
+        if self._type == prompt_types.PromptType.MUSTACHE:
+            template = self._template
+            placeholders = _extract_mustache_placeholder_keys(self._template)
+            kwargs_keys: Set[str] = set(kwargs.keys())
+
+            if kwargs_keys != placeholders and self._validate_placeholders:
+                raise exceptions.PromptPlaceholdersDontMatchFormatArguments(
+                    prompt_placeholders=placeholders, format_arguments=kwargs_keys
+                )
+
+            for key, value in kwargs.items():
+                replacement = "" if value is None else str(value)
+                template = template.replace(f"{{{{{key}}}}}", replacement)
+
+        elif self._type == prompt_types.PromptType.JINJA2:
+            template = jinja2.Template(self._template).render(**kwargs)
+        else:
+            template = self._template
+
+        return template
+
+    def __str__(self) -> str:
+        return self._template
+
+
+def _extract_mustache_placeholder_keys(prompt_template: str) -> Set[str]:
+    pattern = r"\{\{(.*?)\}\}"
+    return set(re.findall(pattern, prompt_template))

opik/api_objects/prompt/types.py

@@ -0,0 +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/rest_stream_parser.py

@@ -0,0 +1,98 @@
+import json
+import logging
+from typing import Callable, Iterable, Type, List, Optional, TypeVar, Any
+
+LOGGER = logging.getLogger(__name__)
+
+
+# this is the constant for the maximum number of objects sent from the backend side
+MAX_ENDPOINT_BATCH_SIZE = 2_000
+
+
+T = TypeVar("T")
+
+
+def read_and_parse_full_stream(
+    read_source: Callable[[int, int], List[Any]],
+    parsed_item_class: Type[T],
+    max_results: Optional[int],
+    max_endpoint_batch_size: int = MAX_ENDPOINT_BATCH_SIZE,
+) -> List[T]:
+    result: List[T] = []
+    while True:
+        if max_results is None:
+            current_batch_size = max_endpoint_batch_size
+        else:
+            amount_left = max_results - len(result)
+            current_batch_size = min(amount_left, max_endpoint_batch_size)
+
+        if current_batch_size <= 0:
+            # no more data to request
+            break
+
+        last_retrieved_id = result[-1].id if len(result) > 0 else None  # type: ignore
+        results_stream = read_source(current_batch_size, last_retrieved_id)
+
+        parsed_items = read_and_parse_stream(
+            stream=results_stream, item_class=parsed_item_class
+        )
+        result.extend(parsed_items)
+
+        if current_batch_size > len(parsed_items):
+            break
+
+    return result
+
+
+def read_and_parse_stream(
+    stream: Iterable[bytes],
+    item_class: Type[T],
+    nb_samples: Optional[int] = None,
+) -> List[T]:
+    result: List[T] = []
+
+    # last record in chunk may be incomplete, we will use this buffer to concatenate strings
+    buffer = b""
+
+    for chunk in stream:
+        buffer += chunk
+        lines = buffer.split(b"\n")
+
+        # last record in chunk may be incomplete
+        for line in lines[:-1]:
+            item = _parse_stream_line(line=line, item_class=item_class)
+            if item is not None:
+                result.append(item)
+
+                if nb_samples is not None and len(result) == nb_samples:
+                    return result
+
+        # Keep the last potentially incomplete line in buffer
+        buffer = lines[-1]
+
+    # Process any remaining data in the buffer after the stream ends
+    if buffer:
+        item = _parse_stream_line(line=buffer, item_class=item_class)
+        if item is not None:
+            result.append(item)
+
+    return result
+
+
+def _parse_stream_line(
+    line: bytes,
+    item_class: Type[T],
+) -> Optional[T]:
+    try:
+        item_dict = json.loads(line.decode("utf-8"))
+        item_obj = item_class(**item_dict)
+        return item_obj
+
+    except json.JSONDecodeError as e:
+        LOGGER.error(f"Error decoding {item_class.__name__}, reason: {e}")
+    except (TypeError, ValueError) as e:
+        LOGGER.error(f"Error parsing {item_class.__name__}, reason: {e}")
+    except Exception as e:
+        LOGGER.error(f"Error decoding or parsing {item_class.__name__}, reason: {e}")
+
+    return None