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

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/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

@@ -14,7 +14,7 @@ class PromptType(str, enum.Enum):
 MessageContent = Union[str, List[Dict[str, Any]]]
 ContentPart = Dict[str, Any]
 RendererFn = Callable[[ContentPart, Dict[str, Any], PromptType], Optional[ContentPart]]
-ModalityName = Literal["vision"]
+ModalityName = Literal["vision", "video"]
 SupportedModalities = Mapping[ModalityName, bool]
 ModalitySet = Set[ModalityName]
 

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/cli/usage_report/charts.py

@@ -513,7 +513,7 @@ def create_individual_chart(
         else:
             period_labels.append(period)
 
-    # Create figure - use same size as reference file for consistency
+    # Create figure with consistent size for all charts (same as reference implementation)
     fig, ax = plt.subplots(figsize=(14, 8))
     unit_label = unit.capitalize()
     x = range(n_periods)
@@ -681,19 +681,44 @@ def create_individual_chart(
     ax.set_xlabel(unit_label)
     ax.set_xticks(x)
     ax.set_xticklabels(period_labels, rotation=45, ha="right")
-    if chart_type in ["trace_count", "token_count", "cost", "span_count"]:
-        # Use compact legend with top projects only (max 19 items: 18 top + Others)
+    # Set x-axis limits to use full width, with small padding on edges
+    ax.set_xlim(-0.5, n_periods - 0.5)
+
+    ax.grid(axis="y", alpha=0.3)
+
+    # Configure legend for charts that need it - place inside figure bounds
+    has_legend = chart_type in ["trace_count", "token_count", "cost", "span_count"]
+    if has_legend:
+        # Truncate legend labels to maximum length to prevent overly wide legends
+        handles, labels = ax.get_legend_handles_labels()
+        max_label_length = 40  # Maximum characters per legend label
+        truncated_labels = []
+        for label in labels:
+            if len(label) > max_label_length:
+                truncated_labels.append(label[: max_label_length - 3] + "...")
+            else:
+                truncated_labels.append(label)
+
+        # Position legend inside the plot area at the bottom, with more space below
+        # This allows us to use bbox_inches=None for fixed image sizes
+        # Use 3 columns to ensure items wrap into multiple rows
         ax.legend(
-            bbox_to_anchor=(0.5, -0.25),
+            handles,
+            truncated_labels,
             loc="upper center",
-            ncol=4,
-            fontsize=9,
+            bbox_to_anchor=(0.5, -0.35),  # Lower in plot area, ~1.5 inches below chart
+            ncol=3,  # 3 columns ensures wrapping into multiple rows
+            fontsize=8,
             framealpha=0.9,
         )
-    ax.grid(axis="y", alpha=0.3)
 
-    # Use rect parameter to make room for legends below charts (more space for lower legends)
-    plt.tight_layout(rect=[0, 0.05, 1, 1])
+    # Explicitly set margins to ensure chart uses full width consistently
+    # Left margin (10%) accounts for y-axis labels (including formatted labels like "500.00M" or "$350.00")
+    # Right margin (5%) is minimal to maximize chart width
+    # Bottom margin (42.5%) accommodates legend positioned below the plot area (outside axes bounds) with ~1 inch of space below
+    # Top margin (8%) for title
+    # This ensures ALL charts have identical dimensions regardless of y-axis formatter
+    fig.subplots_adjust(left=0.10, right=0.95, top=0.92, bottom=0.425)
 
     # Save chart to temporary file (use absolute path)
     chart_filename = os.path.join(
@@ -707,7 +732,11 @@ def create_individual_chart(
         os.makedirs(chart_dir, exist_ok=True)
 
     try:
-        plt.savefig(chart_filename, dpi=300, bbox_inches="tight")
+        # Use bbox_inches=None to preserve exact figure size (14x8 inches)
+        # Since legend is now inside figure bounds, we can use fixed dimensions
+        # This ensures ALL charts have identical dimensions (4200x2400 pixels at 300 DPI)
+        # regardless of y-axis label widths or content
+        plt.savefig(chart_filename, dpi=300, bbox_inches=None)
         plt.close()
 
         # Ensure file is fully written to disk using file system sync operations