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

opik/api_objects/opik_query_language.py

@@ -5,10 +5,12 @@ simple filters without "and" or "or" operators.
 
 import json
 
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Dict, Optional, Tuple, List
 
 COLUMNS = {
+    "id": "string",
     "name": "string",
+    "status": "string",
     "start_time": "date_time",
     "end_time": "date_time",
     "input": "string",
@@ -19,22 +21,119 @@ COLUMNS = {
     "usage.total_tokens": "number",
     "usage.prompt_tokens": "number",
     "usage.completion_tokens": "number",
+    "duration": "number",
+    "number_of_messages": "number",
+    "created_by": "string",
+    "thread_id": "string",
+    "total_estimated_cost": "number",
+    "type": "string",
+    "model": "string",
+    "provider": "string",
+    "template_structure": "string",
 }
 
 SUPPORTED_OPERATORS = {
-    "name": ["=", "contains", "not_contains"],
+    "id": ["=", "contains", "not_contains", "starts_with", "ends_with", "!=", ">", "<"],
+    "name": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "status": ["=", "contains", "not_contains"],
     "start_time": ["=", ">", "<", ">=", "<="],
     "end_time": ["=", ">", "<", ">=", "<="],
-    "input": ["=", "contains", "not_contains"],
+    "input": [
+        "=",
+        "contains",
+        "not_contains",
+    ],
     "output": ["=", "contains", "not_contains"],
     "metadata": ["=", "contains", ">", "<"],
-    "feedback_scores": ["=", ">", "<", ">=", "<="],
+    "feedback_scores": ["=", ">", "<", ">=", "<=", "is_empty", "is_not_empty"],
     "tags": ["contains"],
-    "usage.total_tokens": ["=", ">", "<", ">=", "<="],
-    "usage.prompt_tokens": ["=", ">", "<", ">=", "<="],
-    "usage.completion_tokens": ["=", ">", "<", ">=", "<="],
+    "usage.total_tokens": ["=", "!=", ">", "<", ">=", "<="],
+    "usage.prompt_tokens": ["=", "!=", ">", "<", ">=", "<="],
+    "usage.completion_tokens": ["=", "!=", ">", "<", ">=", "<="],
+    "duration": ["=", "!=", ">", "<", ">=", "<="],
+    "number_of_messages": ["=", "!=", ">", "<", ">=", "<="],
+    "created_by": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "thread_id": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "total_estimated_cost": ["=", "!=", ">", "<", ">=", "<="],
+    "type": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "model": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "provider": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "default": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+        ">",
+        "<",
+    ],
+    "template_structure": [
+        "=",
+        "contains",
+        "not_contains",
+        "starts_with",
+        "ends_with",
+        "!=",
+    ],
 }
 
+OPERATORS_WITHOUT_VALUES = {"is_empty", "is_not_empty"}
+
 
 class OpikQueryLanguage:
     """
@@ -45,10 +144,10 @@ class OpikQueryLanguage:
 
     When converting a query string into another format, a common approach is:
     1. First convert the string into a series of tokens using a tokenizer
-    2. Convert the list of tokens into a Abstract Syntax Tree (AST) using a parser
+    2. Convert the list of tokens into an Abstract Syntax Tree (AST) using a parser
     3. Traverse the AST and convert it into the desired format using a formatter
 
-    Due to the simple nature of the queries we currently support (no support for and/or operators, etc), we have have
+    Due to the simple nature of the queries we currently support (no support for and/or operators, etc.), we have
     combined the tokenizer and formatter steps into a single parse method.
 
     The parse method works by iterating over the string character by character and extracting / validating the tokens.
@@ -58,7 +157,13 @@ class OpikQueryLanguage:
         self.query_string = query_string or ""
 
         self._cursor = 0
-        self.parsed_filters = self._parse()
+        self._filter_expressions = self._parse_expressions()
+        self.parsed_filters = None
+        if self._filter_expressions is not None:
+            self.parsed_filters = json.dumps(self._filter_expressions)
+
+    def get_filter_expressions(self) -> Optional[List[Dict[str, Any]]]:
+        return self._filter_expressions
 
     def _is_valid_field_char(self, char: str) -> bool:
         return char.isalnum() or char == "_"
@@ -168,16 +273,25 @@ class OpikQueryLanguage:
                         "key": "",
                         "type": COLUMNS[f"usage.{key}"],
                     }
-            else:
+            elif field in COLUMNS:
                 return {"field": field, "key": key, "type": COLUMNS[field]}
+            else:
+                # defaults to string
+                return {"field": field, "key": key, "type": "string"}
 
-        else:
+        elif field in COLUMNS:
             return {"field": field, "key": "", "type": COLUMNS[field]}
+        else:
+            # defaults to string
+            return {"field": field, "key": "", "type": "string"}
 
     def _parse_operator(self, parsed_field: str) -> Dict[str, Any]:
         # Skip whitespace
         self._skip_whitespace()
 
+        if parsed_field not in SUPPORTED_OPERATORS:
+            parsed_field = "default"
+
         # Parse the operator
         if self.query_string[self._cursor] == "=":
             operator = "="
@@ -206,7 +320,7 @@ class OpikQueryLanguage:
                 self._cursor += 1
 
             operator = self.query_string[start : self._cursor]
-            if operator not in ["contains", "not_contains"]:
+            if operator not in SUPPORTED_OPERATORS[parsed_field]:
                 raise ValueError(
                     f"Operator {operator} is not supported for field {parsed_field}, only the operators {SUPPORTED_OPERATORS[parsed_field]} are supported."
                 )
@@ -256,10 +370,10 @@ class OpikQueryLanguage:
             return {"value": value}
         else:
             raise ValueError(
-                f'Invalid value {self.query_string[start:self._cursor]}, expected an string in double quotes("value") or a number'
+                f'Invalid value {self.query_string[start : self._cursor]}, expected an string in double quotes("value") or a number'
             )
 
-    def _parse(self) -> Optional[str]:
+    def _parse_expressions(self) -> Optional[List[Dict[str, Any]]]:
         if len(self.query_string) == 0:
             return None
 
@@ -272,8 +386,12 @@ class OpikQueryLanguage:
             # Parse operators
             parsed_operator = self._parse_operator(parsed_field["field"])
 
-            # Parse values
-            parsed_value = self._parse_value()
+            operator_name = parsed_operator.get("operator", "")
+            if operator_name in OPERATORS_WITHOUT_VALUES:
+                # For operators without values, use empty string as value
+                parsed_value = {"value": ""}
+            else:
+                parsed_value = self._parse_value()
 
             expressions.append({**parsed_field, **parsed_operator, **parsed_value})
 
@@ -296,4 +414,4 @@ class OpikQueryLanguage:
             else:
                 break
 
-        return json.dumps(expressions)
+        return expressions

opik/api_objects/optimization/__init__.py

@@ -0,0 +1,3 @@
+from .optimization import Optimization
+
+__all__ = ["Optimization"]

opik/api_objects/optimization/optimization.py

@@ -0,0 +1,39 @@
+import logging
+from typing import Optional, Literal
+
+from opik.rest_api import client as rest_api_client
+from opik.rest_api import types as rest_api_types
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Optimization:
+    def __init__(
+        self,
+        id: str,
+        rest_client: rest_api_client.OpikApi,
+    ) -> None:
+        self._id = id
+        self._rest_client = rest_client
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def update(
+        self,
+        name: Optional[str] = None,
+        status: Optional[Literal["running", "completed", "cancelled"]] = None,
+    ) -> None:
+        LOGGER.debug(
+            f"Updating optimization {self.id} with name {name} and status {status}"
+        )
+        self._rest_client.optimizations.update_optimizations_by_id(
+            id=self.id,
+            name=name,
+            status=status,
+        )
+
+    def fetch_content(self) -> rest_api_types.OptimizationPublic:
+        LOGGER.debug(f"Fetching optimization data {self.id}")
+        return self._rest_client.optimizations.get_optimization_by_id(id=self.id)

opik/api_objects/prompt/__init__.py

@@ -1,5 +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 .base_prompt import BasePrompt
+from .base_prompt_template import BasePromptTemplate
 
 __all__ = [
+    "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

opik/api_objects/prompt/chat/chat_prompt.py

@@ -0,0 +1,210 @@
+import copy
+import json
+from typing import Any, Dict, List, Optional, Tuple, Type
+
+from typing_extensions import override
+
+from opik.rest_api import types as rest_api_types
+from opik.validation import chat_prompt_messages, validator
+from . import chat_prompt_template
+from .. import client as prompt_client
+from .. import types as prompt_types
+from .. import base_prompt
+
+
+class ChatPrompt(base_prompt.BasePrompt):
+    """
+    ChatPrompt class represents a chat-style prompt with a name, message array template and commit hash.
+    Similar to Prompt but uses a list of chat messages instead of a string template.
+    """
+
+    _parameter_validators: List[Tuple[str, Type[validator.RaisableValidator]]] = [
+        ("messages", chat_prompt_messages.ChatPromptMessagesValidator),
+    ]
+
+    def __init__(
+        self,
+        name: str,
+        messages: List[Dict[str, prompt_types.MessageContent]],
+        metadata: Optional[Dict[str, Any]] = None,
+        type: prompt_types.PromptType = prompt_types.PromptType.MUSTACHE,
+        validate_placeholders: bool = False,
+    ) -> None:
+        """
+        Initializes a new instance of the ChatPrompt class.
+        Creates a new chat prompt using the opik client and sets the initial state.
+
+        Parameters:
+            name: The name for the 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).
+            validate_placeholders: Whether to validate template placeholders.
+
+        Raises:
+            PromptTemplateStructureMismatch: If a text prompt with the same name already exists (template structure is immutable).
+            ValidationError: If messages structure is invalid.
+        """
+
+        # Validate messages structure
+        self._validate_inputs(messages=messages)
+
+        self._chat_template = chat_prompt_template.ChatPromptTemplate(
+            messages=messages,
+            template_type=type,
+            validate_placeholders=validate_placeholders,
+        )
+        self._name = name
+        self._metadata = metadata
+        self._type = type
+        self._messages = messages
+        self._commit: Optional[str] = None
+        self.__internal_api__prompt_id__: str
+        self.__internal_api__version_id__: str
+
+        self._sync_with_backend()
+
+    def _validate_inputs(self, **kwargs: Any) -> None:
+        for parameter, validator_class in self._parameter_validators:
+            if parameter in kwargs:
+                validator_instance = validator_class(kwargs[parameter])
+                validator_instance.validate()
+                validator_instance.raise_if_validation_failed()
+
+    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)
+
+        # Convert messages array to JSON string for backend storage
+        messages_str = json.dumps(self._messages)
+
+        prompt_version = prompt_client_.create_prompt(
+            name=self._name,
+            prompt=messages_str,
+            metadata=self._metadata,
+            type=self._type,
+            template_structure="chat",
+        )
+
+        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 template(self) -> List[Dict[str, prompt_types.MessageContent]]:
+        """The chat messages template."""
+        return copy.deepcopy(self._messages)
+
+    @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,
+        variables: Dict[str, Any],
+        supported_modalities: Optional[prompt_types.SupportedModalities] = None,
+    ) -> List[Dict[str, prompt_types.MessageContent]]:
+        """
+        Renders the chat template with provided variables.
+
+        Args:
+            variables: Dictionary of variables to substitute in the template.
+            supported_modalities: Optional dictionary specifying which modalities are supported
+                by the target model. Keys are modality names ("vision" or "video") and values
+                are booleans indicating support. When a modality is not supported (False or not
+                specified), structured content parts (e.g., images, videos) are replaced with
+                text placeholders like "<<<image>>>" or "<<<video>>>". When supported (True),
+                the structured content is preserved as-is.
+                Example: {"vision": True, "video": False}
+
+                If not specified, all modalities default to SUPPORTED. Example: {"vision": True, "video": False}
+
+        Returns:
+            A list of rendered message dictionaries with variables substituted and multimodal
+            content either preserved or replaced with placeholders based on supported_modalities.
+        """
+        if supported_modalities is None:
+            supported_modalities = {
+                "vision": True,
+                "video": True,
+            }
+
+        return self._chat_template.format(
+            variables=variables, supported_modalities=supported_modalities
+        )
+
+    @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.template,
+            },
+        }
+
+        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,
+    ) -> "ChatPrompt":
+        # will not call __init__ to avoid API calls, create new instance with __new__
+        chat_prompt = cls.__new__(cls)
+
+        chat_prompt.__internal_api__version_id__ = prompt_version.id
+        chat_prompt.__internal_api__prompt_id__ = prompt_version.prompt_id
+
+        chat_prompt._name = name
+
+        # Parse messages from JSON string
+        messages = json.loads(prompt_version.template)
+        chat_prompt._messages = messages
+        chat_prompt._chat_template = chat_prompt_template.ChatPromptTemplate(
+            messages=messages,
+            template_type=prompt_types.PromptType(prompt_version.type)
+            or prompt_types.PromptType.MUSTACHE,
+        )
+        chat_prompt._commit = prompt_version.commit
+        chat_prompt._metadata = prompt_version.metadata
+        chat_prompt._type = prompt_version.type
+        return chat_prompt