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

opik/api_objects/opik_client.py

@@ -24,8 +24,8 @@ from .dataset import rest_operations as dataset_rest_operations
 from .experiment import experiments_client
 from .experiment import helpers as experiment_helpers
 from .experiment import rest_operations as experiment_rest_operations
-from .prompt import Prompt, PromptType
-from .prompt.client import PromptClient
+from . import prompt as prompt_module
+from .prompt import client as prompt_client
 from .threads import threads_client
 from .trace import migration as trace_migration, trace_client
 from .. import (
@@ -847,8 +847,13 @@ class Opik:
             self._rest_client, dataset_name
         )
 
+        experiments_client = self.get_experiments_client()
         experiments = dataset_rest_operations.get_dataset_experiments(
-            self._rest_client, dataset_id, max_results, streamer=self._streamer
+            rest_client=self._rest_client,
+            dataset_id=dataset_id,
+            max_results=max_results,
+            streamer=self._streamer,
+            experiments_client=experiments_client,
         )
 
         return experiments
@@ -912,8 +917,8 @@ class Opik:
         dataset_name: str,
         name: Optional[str] = None,
         experiment_config: Optional[Dict[str, Any]] = None,
-        prompt: Optional[Prompt] = None,
-        prompts: Optional[List[Prompt]] = None,
+        prompt: Optional[prompt_module.base_prompt.BasePrompt] = None,
+        prompts: Optional[List[prompt_module.base_prompt.BasePrompt]] = None,
         type: Literal["regular", "trial", "mini-batch"] = "regular",
         optimization_id: Optional[str] = None,
     ) -> experiment.Experiment:
@@ -961,11 +966,48 @@ class Opik:
             dataset_name=dataset_name,
             rest_client=self._rest_client,
             streamer=self._streamer,
+            experiments_client=self.get_experiments_client(),
             prompts=checked_prompts,
         )
 
         return experiment_
 
+    def update_experiment(
+        self,
+        id: str,
+        name: Optional[str] = None,
+        experiment_config: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Update an experiment's name and/or configuration.
+
+        Args:
+            id: The experiment ID.
+            name: The new name for the experiment. If None, the name will not be updated.
+            experiment_config: The new configuration for the experiment. If None, the configuration will not be updated.
+
+        Raises:
+            ValueError: if id is None or empty, or if both name and experiment_config are None
+        """
+        if not id:
+            raise ValueError(
+                f"id must be provided and can not be None or empty, id: {id}"
+            )
+
+        if name is None and experiment_config is None:
+            raise ValueError(
+                "At least one of 'name' or 'experiment_config' must be provided"
+            )
+
+        # Only include parameters that are provided to avoid clearing fields
+        request_params: Dict[str, Any] = {}
+        if name is not None:
+            request_params["name"] = name
+        if experiment_config is not None:
+            request_params["metadata"] = experiment_config
+
+        self._rest_client.experiments.update_experiment(id, **request_params)
+
     def get_experiment_by_name(self, name: str) -> experiment.Experiment:
         """
         Returns an existing experiment by its name.
@@ -985,18 +1027,20 @@ class Opik:
 
         return experiment.Experiment(
             id=experiment_public.id,
-            name=name,
+            name=experiment_public.name,
             dataset_name=experiment_public.dataset_name,
             rest_client=self._rest_client,
             streamer=self._streamer,
+            experiments_client=self.get_experiments_client(),
         )
 
     def get_experiments_by_name(self, name: str) -> List[experiment.Experiment]:
         """
-        Returns a list of existing experiments by its name.
+        Returns a list of existing experiments containing the given string in their name.
+        Search is case-insensitive.
 
         Args:
-            name: The name of the experiment(s).
+            name: The string to search for in the experiment names.
 
         Returns:
             List[experiment.Experiment]: List of existing experiments.
@@ -1009,10 +1053,11 @@ class Opik:
         for public_experiment in experiments_public:
             experiment_ = experiment.Experiment(
                 id=public_experiment.id,
-                name=name,
+                name=public_experiment.name,
                 dataset_name=public_experiment.dataset_name,
                 rest_client=self._rest_client,
                 streamer=self._streamer,
+                experiments_client=self.get_experiments_client(),
             )
             result.append(experiment_)
 
@@ -1045,6 +1090,7 @@ class Opik:
             dataset_name=experiment_public.dataset_name,
             rest_client=self._rest_client,
             streamer=self._streamer,
+            experiments_client=self.get_experiments_client(),
         )
 
     def end(self, timeout: Optional[int] = None) -> None:
@@ -1348,70 +1394,188 @@ class Opik:
         name: str,
         prompt: str,
         metadata: Optional[Dict[str, Any]] = None,
-        type: PromptType = PromptType.MUSTACHE,
-    ) -> Prompt:
+        type: prompt_module.PromptType = prompt_module.PromptType.MUSTACHE,
+    ) -> prompt_module.Prompt:
         """
-        Creates a new prompt with the given name and template.
-        If a prompt with the same name already exists, it will create a new version of the existing prompt if the templates differ.
+        Creates a new text prompt with the given name and template.
+        If a text prompt with the same name already exists, it will create a new version of the existing prompt if the templates differ.
 
         Parameters:
             name: The name of the prompt.
             prompt: The template content of the prompt.
             metadata: Optional metadata to be included in the prompt.
+            type: The template type (MUSTACHE or JINJA2).
 
         Returns:
             A Prompt object containing details of the created or retrieved prompt.
 
         Raises:
-            ApiError: If there is an error during the creation of the prompt and the status code is not 409.
+            PromptTemplateStructureMismatch: If a chat prompt with the same name already exists (template structure is immutable).
+            ApiError: If there is an error during the creation of the prompt.
         """
-        prompt_client = PromptClient(self._rest_client)
-        prompt_version = prompt_client.create_prompt(
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+        prompt_version = prompt_client_.create_prompt(
             name=name, prompt=prompt, metadata=metadata, type=type
         )
-        return Prompt.from_fern_prompt_version(name, prompt_version)
+        return prompt_module.Prompt.from_fern_prompt_version(name, prompt_version)
+
+    def create_chat_prompt(
+        self,
+        name: str,
+        messages: List[Dict[str, Any]],
+        metadata: Optional[Dict[str, Any]] = None,
+        type: prompt_module.PromptType = prompt_module.PromptType.MUSTACHE,
+    ) -> prompt_module.ChatPrompt:
+        """
+        Creates a new chat prompt with the given name and message templates.
+        If a chat prompt with the same name already exists, it will create a new version if the messages differ.
+
+        Parameters:
+            name: The name of the chat prompt.
+            messages: List of message dictionaries with 'role' and 'content' fields.
+            metadata: Optional metadata to be included in the prompt.
+            type: The template type (MUSTACHE or JINJA2).
+
+        Returns:
+            A ChatPrompt object containing details of the created or retrieved chat prompt.
+
+        Raises:
+            PromptTemplateStructureMismatch: If a text prompt with the same name already exists (template structure is immutable).
+            ApiError: If there is an error during the creation of the prompt.
+        """
+        return prompt_module.ChatPrompt(
+            name=name, messages=messages, metadata=metadata, type=type
+        )
 
     def get_prompt(
         self,
         name: str,
         commit: Optional[str] = None,
-    ) -> Optional[Prompt]:
+    ) -> Optional[prompt_module.Prompt]:
         """
-        Retrieve the prompt detail for a given prompt name and commit version.
+        Retrieve a text prompt by name and optional commit version.
+
+        This method only returns text prompts.
 
         Parameters:
             name: The name of the prompt.
             commit: An optional commit version of the prompt. If not provided, the latest version is retrieved.
 
         Returns:
-            Prompt: The details of the specified prompt.
+            Prompt: The details of the specified text prompt, or None if not found.
+
+        Raises:
+            PromptTemplateStructureMismatch: If the prompt exists but is a chat prompt (template structure mismatch).
         """
-        prompt_client = PromptClient(self._rest_client)
-        fern_prompt_version = prompt_client.get_prompt(name=name, commit=commit)
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+        fern_prompt_version = prompt_client_.get_prompt(
+            name=name, commit=commit, raise_if_not_template_structure="text"
+        )
+
         if fern_prompt_version is None:
             return None
 
-        return Prompt.from_fern_prompt_version(name, fern_prompt_version)
+        return prompt_module.Prompt.from_fern_prompt_version(name, fern_prompt_version)
 
-    def get_prompt_history(self, name: str) -> List[Prompt]:
+    def get_chat_prompt(
+        self,
+        name: str,
+        commit: Optional[str] = None,
+    ) -> Optional[prompt_module.ChatPrompt]:
         """
-        Retrieve all the prompt versions history for a given prompt name.
+        Retrieve a chat prompt by name and optional commit version.
+
+        This method only returns chat prompts.
 
         Parameters:
             name: The name of the prompt.
+            commit: An optional commit version of the prompt. If not provided, the latest version is retrieved.
 
         Returns:
-            List[Prompt]: A list of Prompt instances for the given name.
+            ChatPrompt: The details of the specified chat prompt, or None if not found.
+
+        Raises:
+            PromptTemplateStructureMismatch: If the prompt exists but is a text prompt (template structure mismatch).
         """
-        prompt_client = PromptClient(self._rest_client)
-        fern_prompt_versions = prompt_client.get_all_prompt_versions(name=name)
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+        fern_prompt_version = prompt_client_.get_prompt(
+            name=name, commit=commit, raise_if_not_template_structure="chat"
+        )
+
+        if fern_prompt_version is None:
+            return None
+
+        return prompt_module.ChatPrompt.from_fern_prompt_version(
+            name, fern_prompt_version
+        )
+
+    def get_prompt_history(self, name: str) -> List[prompt_module.Prompt]:
+        """
+        Retrieve all text prompt versions history for a given prompt name.
+
+        Parameters:
+            name: The name of the prompt.
+
+        Returns:
+            List[Prompt]: A list of text Prompt instances for the given name, or an empty list if not found.
+
+        Raises:
+            PromptTemplateStructureMismatch: If the prompt exists but is a chat prompt (template structure mismatch).
+        """
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+
+        # First, validate that this is a text prompt by trying to get the latest version
+        # Let PromptTemplateStructureMismatch exception propagate - this is a hard error
+        latest_version = prompt_client_.get_prompt(
+            name=name, raise_if_not_template_structure="text"
+        )
+
+        if latest_version is None:
+            return []
+
+        # Now get all versions (we know it's a text prompt)
+        fern_prompt_versions = prompt_client_.get_all_prompt_versions(name=name)
+
         result = [
-            Prompt.from_fern_prompt_version(name, version)
+            prompt_module.Prompt.from_fern_prompt_version(name, version)
             for version in fern_prompt_versions
         ]
         return result
 
-    def get_all_prompts(self, name: str) -> List[Prompt]:
+    def get_chat_prompt_history(self, name: str) -> List[prompt_module.ChatPrompt]:
+        """
+        Retrieve all chat prompt versions history for a given prompt name.
+
+        Parameters:
+            name: The name of the prompt.
+
+        Returns:
+            List[ChatPrompt]: A list of ChatPrompt instances for the given name, or an empty list if not found.
+
+        Raises:
+            PromptTemplateStructureMismatch: If the prompt exists but is a text prompt (template structure mismatch).
+        """
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+
+        # First, validate that this is a chat prompt by trying to get the latest version
+        # Let PromptTemplateStructureMismatch exception propagate - this is a hard error
+        latest_version = prompt_client_.get_prompt(
+            name=name, raise_if_not_template_structure="chat"
+        )
+
+        if latest_version is None:
+            return []
+
+        # Now get all versions (we know it's a chat prompt)
+        fern_prompt_versions = prompt_client_.get_all_prompt_versions(name=name)
+
+        result = [
+            prompt_module.ChatPrompt.from_fern_prompt_version(name, version)
+            for version in fern_prompt_versions
+        ]
+        return result
+
+    def get_all_prompts(self, name: str) -> List[prompt_module.Prompt]:
         """
         DEPRECATED: Please use Opik.get_prompt_history() instead.
         Retrieve all the prompt versions history for a given prompt name.
@@ -1420,16 +1584,18 @@ class Opik:
             name: The name of the prompt.
 
         Returns:
-            List[Prompt]: A list of Prompt instances for the given name.
+            List[prompt_module.Prompt]: A list of Prompt instances for the given name.
         """
         LOGGER.warning(
             "Opik.get_all_prompts() is deprecated. Please use Opik.get_prompt_history() instead."
         )
         return self.get_prompt_history(name)
 
-    def search_prompts(self, filter_string: Optional[str] = None) -> List[Prompt]:
+    def search_prompts(
+        self, filter_string: Optional[str] = None
+    ) -> List[Union[prompt_module.Prompt, prompt_module.ChatPrompt]]:
         """
-        Retrieve the latest prompt versions for the given search parameters.
+        Retrieve the latest prompt versions (both string and chat prompts) for the given search parameters.
 
         Parameters:
             filter_string: A filter string to narrow down the search using Opik Query Language (OQL).
@@ -1439,11 +1605,13 @@ class Opik:
                 - `id`, `name`: String fields
                 - `tags`: List field (use "contains" operator only)
                 - `created_by`: String field
+                - `template_structure`: String field ("string" or "chat")
 
                 Supported operators by column:
                 - `id`: =, !=, contains, not_contains, starts_with, ends_with, >, <
                 - `name`: =, !=, contains, not_contains, starts_with, ends_with, >, <
                 - `created_by`: =, !=, contains, not_contains, starts_with, ends_with, >, <
+                - `template_structure`: =, !=
                 - `tags`: contains (only)
 
                 Examples:
@@ -1452,23 +1620,36 @@ class Opik:
                 - `name contains "summary"` - Filter by name substring
                 - `created_by = "user@example.com"` - Filter by creator
                 - `id starts_with "prompt_"` - Filter by ID prefix
+                - `template_structure = "text"` - Only text prompts
+                - `template_structure = "chat"` - Only chat prompts
 
-                If not provided, all prompts matching the name filter will be returned.
+                If not provided, all prompts (both text and chat) will be returned.
 
         Returns:
-            List[Prompt]: A list of Prompt instances found.
-        """
-        parsed_filters = None
-        if filter_string:
-            oql = opik_query_language.OpikQueryLanguage(filter_string)
-            parsed_filters = oql.get_filter_expressions()
-
-        prompt_client = PromptClient(self._rest_client)
-        name_and_versions = prompt_client.search_prompts(parsed_filters=parsed_filters)
-        prompts: List[Prompt] = [
-            Prompt.from_fern_prompt_version(prompt_name, version)
-            for (prompt_name, version) in name_and_versions
-        ]
+            List[Union[Prompt, ChatPrompt]]: A list of Prompt and/or ChatPrompt instances found.
+        """
+        oql = opik_query_language.OpikQueryLanguage(filter_string or "")
+        parsed_filters = oql.get_filter_expressions()
+
+        prompt_client_ = prompt_client.PromptClient(self._rest_client)
+        search_results = prompt_client_.search_prompts(parsed_filters=parsed_filters)
+
+        # Convert to Prompt or ChatPrompt objects based on template_structure
+        prompts: List[Union[prompt_module.Prompt, prompt_module.ChatPrompt]] = []
+        for result in search_results:
+            if result.template_structure == "chat":
+                prompts.append(
+                    prompt_module.ChatPrompt.from_fern_prompt_version(
+                        result.name, result.prompt_version_detail
+                    )
+                )
+            else:
+                prompts.append(
+                    prompt_module.Prompt.from_fern_prompt_version(
+                        result.name, result.prompt_version_detail
+                    )
+                )
+
         return prompts
 
     def create_optimization(
@@ -1477,8 +1658,9 @@ class Opik:
         objective_name: str,
         name: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
+        optimization_id: Optional[str] = None,
     ) -> optimization.Optimization:
-        id = id_helpers.generate_id()
+        id = optimization_id or id_helpers.generate_id()
 
         self._rest_client.optimizations.create_optimization(
             id=id,

opik/api_objects/opik_query_language.py

@@ -29,6 +29,7 @@ COLUMNS = {
     "type": "string",
     "model": "string",
     "provider": "string",
+    "template_structure": "string",
 }
 
 SUPPORTED_OPERATORS = {
@@ -121,6 +122,14 @@ SUPPORTED_OPERATORS = {
         ">",
         "<",
     ],
+    "template_structure": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+    ],
 }
 
 

opik/api_objects/prompt/__init__.py

@@ -1,9 +1,17 @@
-from .prompt import Prompt
+from .text.prompt import Prompt
+from .text.prompt_template import PromptTemplate
+from .chat.chat_prompt import ChatPrompt
+from .chat.chat_prompt_template import ChatPromptTemplate
 from .types import PromptType
-from .chat_prompt_template import ChatPromptTemplate
+from .base_prompt import BasePrompt
+from .base_prompt_template import BasePromptTemplate
 
 __all__ = [
-    "Prompt",
     "PromptType",
+    "Prompt",
+    "ChatPrompt",
+    "PromptTemplate",
     "ChatPromptTemplate",
+    "BasePrompt",
+    "BasePromptTemplate",
 ]

opik/api_objects/prompt/base_prompt.py

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

opik/api_objects/prompt/base_prompt_template.py

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

opik/api_objects/prompt/chat/__init__.py

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