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

opik/api_objects/threads/threads_client.py

@@ -0,0 +1,185 @@
+import logging
+from typing import List, Optional
+
+import opik
+from opik.rest_api import TraceThread
+from opik.types import BatchFeedbackScoreDict
+
+from .. import helpers, rest_stream_parser, constants
+from ... import config
+from ...message_processing import messages
+from ...message_processing.batching import sequence_splitter
+from ...rest_api.types import trace_thread_filter
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class ThreadsClient:
+    """
+    Client for managing and interacting with conversational threads.
+
+    This class provides methods for searching threads and logging feedback scores
+    related to threads using an underlying client instance. It is intended to be
+    used in scenarios where thread management and feedback tracking are required.
+
+    Args:
+        client: Instance of the underlying OPIK client.
+    """
+
+    def __init__(self, client: "opik.Opik"):
+        self._opik_client = client
+
+    def search_threads(
+        self,
+        project_name: Optional[str] = None,
+        filter_string: Optional[str] = None,
+        max_results: int = 1000,
+        truncate: bool = True,
+    ) -> List[TraceThread]:
+        """Search for threads in a given project based on specific criteria.
+
+        This method retrieves a list of TraceThread objects that match the specified
+        filter criteria. It takes an optional project name, a filter string to narrow
+        down the results, and a maximum number of threads to return.
+
+        The filter string should be a string that represents a filter condition in the
+        form of a string expression. For example, to search for threads with a specific
+        status, you could use the following filter string: `filter_string = 'status = "active"'`.
+        The filter string can include logical operators (AND) to combine
+        multiple conditions, for example, `filter_string = 'status = "active" and id = "{thread_id}"'`.
+
+        Args:
+            project_name:
+                The name of the project to search the threads for. If None, the search
+                will include threads from all projects.
+            filter_string:
+                A filter string to narrow down the search using Opik Query Language (OQL).
+                The format is: "<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*"
+
+                Supported columns include:
+                - `id`, `name`, `created_by`, `thread_id`, `type`, `model`, `provider`: String fields with full operator support
+                - `status`: String field (=, contains, not_contains only)
+                - `start_time`, `end_time`: DateTime fields (use ISO 8601 format, e.g., "2024-01-01T00:00:00Z")
+                - `input`, `output`: String fields for content (=, contains, not_contains only)
+                - `metadata`: Dictionary field (use dot notation, e.g., "metadata.model")
+                - `feedback_scores`: Numeric field (use dot notation, e.g., "feedback_scores.accuracy")
+                - `tags`: List field (use "contains" operator only)
+                - `usage.total_tokens`, `usage.prompt_tokens`, `usage.completion_tokens`: Numeric usage fields
+                - `duration`, `number_of_messages`, `total_estimated_cost`: Numeric fields
+
+                Supported operators by column:
+                - `id`, `name`, `created_by`, `thread_id`, `type`, `model`, `provider`: =, !=, contains, not_contains, starts_with, ends_with, >, <
+                - `status`: =, contains, not_contains
+                - `start_time`, `end_time`: =, >, <, >=, <=
+                - `input`, `output`: =, contains, not_contains
+                - `metadata`: =, contains, >, <
+                - `feedback_scores`: =, >, <, >=, <=, is_empty, is_not_empty
+                - `tags`: contains (only)
+                - `usage.total_tokens`, `usage.prompt_tokens`, `usage.completion_tokens`, `duration`, `number_of_messages`, `total_estimated_cost`: =, !=, >, <, >=, <=
+
+                Examples:
+                - `status = "inactive"` - Filter by thread status
+                - `id = "thread_123"` - Filter by specific thread ID
+                - `duration > 300` - Filter by thread duration (seconds)
+                - `number_of_messages >= 5` - Filter by message count
+                - `feedback_scores.user_frustration > 0.5` - Filter by feedback score
+                - `feedback_scores.my_metric is_empty` - Filter threads with empty feedback score
+                - `feedback_scores.my_metric is_not_empty` - Filter threads with non-empty feedback score
+                - `tags contains "important"` - Filter by tag
+
+                If not provided, all threads in the project will be returned up to the limit.
+            max_results:
+                The maximum number of threads to retrieve. The default value is 1000
+                if not specified.
+            truncate:
+                Whether to truncate image data stored in input, output, or metadata
+
+        Returns:
+            List[TraceThread]: A list of TraceThread objects that match the search
+            criteria.
+
+        Example:
+            >>> from opik import Opik
+            >>> client = Opik(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME")
+            >>> thread_id = "your_thread_id"
+            >>> threads = client.get_threads_client().search_threads(
+            >>>     project_name="Demo Project",
+            >>>     filter_string=f'id = "{thread_id}"',
+            >>>     max_results=10)
+        """
+        filters = helpers.parse_filter_expressions(
+            filter_string, parsed_item_class=trace_thread_filter.TraceThreadFilter
+        )
+
+        project_name = project_name or self._opik_client.project_name
+
+        threads = rest_stream_parser.read_and_parse_full_stream(
+            read_source=lambda current_batch_size,
+            last_retrieved_id: self._opik_client.rest_client.traces.search_trace_threads(
+                project_name=project_name,
+                filters=filters,
+                limit=current_batch_size,
+                truncate=truncate,
+                last_retrieved_thread_model_id=last_retrieved_id,
+            ),
+            max_results=max_results,
+            parsed_item_class=TraceThread,
+        )
+        return threads
+
+    def log_threads_feedback_scores(
+        self, scores: List[BatchFeedbackScoreDict], project_name: Optional[str] = None
+    ) -> None:
+        """
+        Logs feedback scores for threads in a specific project. This method processes the given
+        feedback scores and associates them with the specified project if a project name is
+        provided. It is designed to handle multiple scores in a structured manner.
+
+        Args:
+            scores: A list of dictionaries containing feedback scores
+                for threads to be logged. Specifying a thread id via `id` key for each score is mandatory.
+            project_name: The name of the project to associate with the logged
+                scores. If not provided, the project name configured in the Opik client will be used.
+                This parameter is used as a fallback if `project_name` is not specified in the score dictionary.
+        """
+        project_name = project_name or self._opik_client.project_name
+
+        score_messages = helpers.parse_feedback_score_messages(
+            scores=scores,
+            project_name=project_name,
+            parsed_item_class=messages.ThreadsFeedbackScoreMessage,
+            logger=LOGGER,
+        )
+        if score_messages is None:
+            LOGGER.error(
+                f"No valid threads feedback scores to log from provided ones: {scores}"
+            )
+            return
+
+        for batch in sequence_splitter.split_into_batches(
+            score_messages,
+            max_payload_size_MB=config.MAX_BATCH_SIZE_MB,
+            max_length=constants.FEEDBACK_SCORES_MAX_BATCH_SIZE,
+        ):
+            add_threads_feedback_scores_batch_message = (
+                messages.AddThreadsFeedbackScoresBatchMessage(batch=batch)
+            )
+
+            self._opik_client._streamer.put(add_threads_feedback_scores_batch_message)
+
+    def close_thread(self, thread_id: str, project_name: str) -> None:
+        """
+        Closes a thread in a specific project.
+
+        Args:
+            thread_id: The identifier of the thread to close.
+            project_name: The name of the project to close the thread in.
+        """
+        self._opik_client.rest_client.traces.close_trace_thread(
+            thread_id=thread_id, project_name=project_name
+        )
+
+    @property
+    def opik_client(self) -> "opik.Opik":
+        return self._opik_client

opik/api_objects/trace/trace_client.py

@@ -2,11 +2,12 @@ import datetime
 import logging
 from typing import Any, Dict, List, Optional, Union
 
-
-from opik import datetime_helpers, id_helpers, llm_usage
+import opik.datetime_helpers as datetime_helpers
+import opik.llm_usage as llm_usage
+import opik.api_objects.attachment as attachment
 from opik.message_processing import messages, streamer
 from opik.types import ErrorInfoDict, SpanType, LLMProvider
-from .. import constants, span, validation_helpers, helpers
+from .. import constants, span
 
 LOGGER = logging.getLogger(__name__)
 
@@ -17,6 +18,7 @@ class Trace:
         id: str,
         message_streamer: streamer.Streamer,
         project_name: str,
+        url_override: str,
     ):
         """
         A Trace object. This object should not be created directly, instead use :meth:`opik.Opik.trace` to create a new trace.
@@ -24,6 +26,7 @@ class Trace:
         self.id = id
         self._streamer = message_streamer
         self._project_name = project_name
+        self._url_override = url_override
 
     def end(
         self,
@@ -94,9 +97,10 @@ class Trace:
         Returns:
             None
         """
-        update_trace_message = messages.UpdateTraceMessage(
+        update_trace(
             trace_id=self.id,
             project_name=self._project_name,
+            message_streamer=self._streamer,
             end_time=end_time,
             metadata=metadata,
             input=input,
@@ -105,7 +109,6 @@ class Trace:
             error_info=error_info,
             thread_id=thread_id,
         )
-        self._streamer.put(update_trace_message)
 
     def span(
         self,
@@ -124,75 +127,58 @@ class Trace:
         provider: Optional[Union[LLMProvider, str]] = None,
         error_info: Optional[ErrorInfoDict] = None,
         total_cost: Optional[float] = None,
+        attachments: Optional[List[attachment.Attachment]] = None,
     ) -> span.Span:
         """
         Create a new span within the trace.
 
         Args:
-            id: The ID of the span, should be in UUIDv7 format. If not provided, a new ID will be generated.
+            id: The ID of the span should be in UUIDv7 format. If not provided, a new ID will be generated.
             parent_span_id: The ID of the parent span, if any.
             name: The name of the span.
             type: The type of the span. Defaults to "general".
-            start_time: The start time of the span. If not provided, current time will be used.
+            start_time: The start time of the span. If not provided, the current time will be used.
             end_time: The end time of the span.
             metadata: Additional metadata to be associated with the span.
             input: The input data for the span.
             output: The output data for the span.
             tags: A list of tags to be associated with the span.
             usage: Usage data for the span. In order for input, output and total tokens to be visible in the UI,
-                the usage must contain OpenAI-formatted keys (they can be passed additionaly to original usage on the top level of the dict):  prompt_tokens, completion_tokens and total_tokens.
+                the usage must contain OpenAI-formatted keys (they can be passed additionally to the original usage on the top level of the dict): prompt_tokens, completion_tokens and total_tokens.
                 If OpenAI-formatted keys were not found, Opik will try to calculate them automatically if the usage
                 format is recognized (you can see which provider's formats are recognized in opik.LLMProvider enum), but it is not guaranteed.
             model: The name of LLM (in this case `type` parameter should be == `llm`)
             provider: The provider of LLM. You can find providers officially supported by Opik for cost tracking
-                in `opik.LLMProvider` enum. If your provider is not here, please open an issue in our github - https://github.com/comet-ml/opik.
-                If your provider not in the list, you can still specify it but the cost tracking will not be available
+                in `opik.LLMProvider` enum. If your provider is not here, please open an issue in our GitHub - https://github.com/comet-ml/opik.
+                If your provider is not in the list, you can still specify it, but the cost tracking will not be available
             error_info: The dictionary with error information (typically used when the span function has failed).
             total_cost: The cost of the span in USD. This value takes priority over the cost calculated by Opik from the usage.
+            attachments: The list of attachments to be uploaded to the span.
 
         Returns:
             span.Span: The created span object.
         """
-        span_id = id if id is not None else id_helpers.generate_id()
-        start_time = (
-            start_time if start_time is not None else datetime_helpers.local_timestamp()
-        )
-        backend_compatible_usage = validation_helpers.validate_and_parse_usage(
-            usage=usage,
-            logger=LOGGER,
-            provider=provider,
-        )
-
-        if backend_compatible_usage is not None:
-            metadata = helpers.add_usage_to_metadata(usage=usage, metadata=metadata)
-
-        create_span_message = messages.CreateSpanMessage(
-            span_id=span_id,
+        return span.span_client.create_span(
             trace_id=self.id,
             project_name=self._project_name,
+            url_override=self._url_override,
+            message_streamer=self._streamer,
+            span_id=id,
             parent_span_id=parent_span_id,
             name=name,
             type=type,
             start_time=start_time,
             end_time=end_time,
+            metadata=metadata,
             input=input,
             output=output,
-            metadata=metadata,
             tags=tags,
-            usage=backend_compatible_usage,
+            usage=usage,
             model=model,
             provider=provider,
             error_info=error_info,
             total_cost=total_cost,
-        )
-        self._streamer.put(create_span_message)
-
-        return span.Span(
-            id=span_id,
-            parent_span_id=parent_span_id,
-            trace_id=self.id,
-            message_streamer=self._streamer,
-            project_name=self._project_name,
+            attachments=attachments,
         )
 
     def log_feedback_score(
@@ -229,3 +215,53 @@ class Trace:
         )
 
         self._streamer.put(add_trace_feedback_batch_message)
+
+
+def update_trace(
+    trace_id: str,
+    project_name: str,
+    message_streamer: streamer.Streamer,
+    end_time: Optional[datetime.datetime] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    input: Optional[Dict[str, Any]] = None,
+    output: Optional[Dict[str, Any]] = None,
+    tags: Optional[List[Any]] = None,
+    error_info: Optional[ErrorInfoDict] = None,
+    thread_id: Optional[str] = None,
+) -> None:
+    """
+    Update an existing trace with new information.
+    This function sends an UpdateTraceMessage to the provided message_streamer,
+    allowing you to update various fields of a trace, such as its end time,
+    metadata, input, output, tags, error information and thread association.
+
+    Args:
+        trace_id: The unique identifier of the trace to update.
+        project_name: The name of the project associated with the trace.
+        message_streamer: The message streamer used to send the update.
+        end_time: The end time of the trace. Defaults to None.
+        metadata: Additional metadata for the trace. Defaults to None.
+        input: Input data associated with the trace. Defaults to None.
+        output: Output data associated with the trace. Defaults to None.
+        tags: List of tags to associate with the trace. Defaults to None.
+        error_info: Error information related to the trace. Defaults to None.
+        thread_id : The thread ID associated with the trace. Defaults to None.
+    Returns:
+        None
+    Usage Notes:
+        - This function does not return a value; it sends an update message to the message streamer.
+        - All parameters except trace_id, project_name and message_streamer are optional.
+        - Only the fields provided will be updated in the trace.
+    """
+    update_trace_message = messages.UpdateTraceMessage(
+        trace_id=trace_id,
+        project_name=project_name,
+        end_time=end_time,
+        metadata=metadata,
+        input=input,
+        output=output,
+        tags=tags,
+        error_info=error_info,
+        thread_id=thread_id,
+    )
+    message_streamer.put(update_trace_message)

opik/api_objects/trace/trace_data.py

@@ -1,16 +1,20 @@
 import dataclasses
 import datetime
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
-from opik import dict_utils
-
-from ... import datetime_helpers, id_helpers
-from ...types import (
+import opik.api_objects.attachment as attachment
+import opik.datetime_helpers as datetime_helpers
+import opik.id_helpers as id_helpers
+import opik.llm_usage as llm_usage
+from opik.types import (
     CreatedByType,
     ErrorInfoDict,
     FeedbackScoreDict,
+    LLMProvider,
+    SpanType,
 )
+from .. import span, data_helpers
 
 LOGGER = logging.getLogger(__name__)
 
@@ -43,13 +47,56 @@ class TraceData:
     created_by: Optional[CreatedByType] = None
     error_info: Optional[ErrorInfoDict] = None
     thread_id: Optional[str] = None
+    attachments: Optional[List[attachment.Attachment]] = None
+
+    def create_child_span_data(
+        self,
+        name: Optional[str] = None,
+        type: SpanType = "general",
+        start_time: Optional[datetime.datetime] = None,
+        end_time: Optional[datetime.datetime] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        input: Optional[Dict[str, Any]] = None,
+        output: Optional[Dict[str, Any]] = None,
+        tags: Optional[List[str]] = None,
+        usage: Optional[Union[Dict[str, Any], llm_usage.OpikUsage]] = None,
+        feedback_scores: Optional[List[FeedbackScoreDict]] = None,
+        model: Optional[str] = None,
+        provider: Optional[Union[str, LLMProvider]] = None,
+        error_info: Optional[ErrorInfoDict] = None,
+        total_cost: Optional[float] = None,
+        attachments: Optional[List[attachment.Attachment]] = None,
+    ) -> span.SpanData:
+        start_time = (
+            start_time if start_time is not None else datetime_helpers.local_timestamp()
+        )
+        return span.SpanData(
+            trace_id=self.id,
+            parent_span_id=None,
+            project_name=self.project_name,
+            name=name,
+            type=type,
+            start_time=start_time,
+            end_time=end_time,
+            metadata=metadata,
+            input=input,
+            output=output,
+            tags=tags,
+            usage=usage,
+            feedback_scores=feedback_scores,
+            model=model,
+            provider=provider,
+            error_info=error_info,
+            total_cost=total_cost,
+            attachments=attachments,
+        )
 
     def update(self, **new_data: Any) -> "TraceData":
         for key, value in new_data.items():
             if value is None:
                 continue
 
-            if key not in self.__dict__:
+            if key not in self.__dict__ and key != "prompts":
                 LOGGER.debug(
                     "An attempt to update span with parameter name it doesn't have: %s",
                     key,
@@ -57,37 +104,76 @@ class TraceData:
                 continue
 
             if key == "metadata":
-                self._update_metadata(value)
+                self.metadata = data_helpers.merge_metadata(
+                    self.metadata, new_metadata=value
+                )
                 continue
             elif key == "output":
-                self._update_output(value)
+                self.output = data_helpers.merge_outputs(self.output, new_outputs=value)
                 continue
             elif key == "input":
-                self._update_input(value)
+                self.input = data_helpers.merge_inputs(self.input, new_inputs=value)
+                continue
+            elif key == "attachments":
+                self._update_attachments(value)
+                continue
+            elif key == "tags":
+                self.tags = data_helpers.merge_tags(self.tags, new_tags=value)
+                continue
+            elif key == "prompts":
+                self.metadata = data_helpers.merge_metadata(
+                    self.metadata, new_metadata=new_data.get("metadata"), prompts=value
+                )
                 continue
 
             self.__dict__[key] = value
 
         return self
 
-    def _update_metadata(self, new_metadata: Dict[str, Any]) -> None:
-        if self.metadata is None:
-            self.metadata = new_metadata
-        else:
-            self.metadata = dict_utils.deepmerge(self.metadata, new_metadata)
+    def init_end_time(self) -> "TraceData":
+        self.end_time = datetime_helpers.local_timestamp()
+        return self
 
-    def _update_output(self, new_output: Dict[str, Any]) -> None:
-        if self.output is None:
-            self.output = new_output
+    def _update_attachments(self, attachments: List[attachment.Attachment]) -> None:
+        if self.attachments is None:
+            self.attachments = attachments
         else:
-            self.output = dict_utils.deepmerge(self.output, new_output)
+            self.attachments.extend(attachments)
 
-    def _update_input(self, new_input: Dict[str, Any]) -> None:
-        if self.input is None:
-            self.input = new_input
-        else:
-            self.input = dict_utils.deepmerge(self.input, new_input)
+    @property
+    def as_start_parameters(self) -> Dict[str, Any]:
+        """Returns parameters of this trace to be sent to the server when starting a new trace."""
+        start_parameters: Dict[str, Any] = {
+            "id": self.id,
+            "start_time": self.start_time,
+            "project_name": self.project_name,
+        }
+        if self.name is not None:
+            start_parameters["name"] = self.name
+        if self.input is not None:
+            start_parameters["input"] = self.input
+        if self.metadata is not None:
+            start_parameters["metadata"] = self.metadata
+        if self.tags is not None:
+            start_parameters["tags"] = self.tags
 
-    def init_end_time(self) -> "TraceData":
-        self.end_time = datetime_helpers.local_timestamp()
-        return self
+        return start_parameters
+
+    @property
+    def as_parameters(self) -> Dict[str, Any]:
+        """Returns all parameters of this trace to be sent to the server."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "metadata": self.metadata,
+            "input": self.input,
+            "output": self.output,
+            "tags": self.tags,
+            "feedback_scores": self.feedback_scores,
+            "project_name": self.project_name,
+            "error_info": self.error_info,
+            "thread_id": self.thread_id,
+            "attachments": self.attachments,
+        }

opik/api_objects/validation_helpers.py

@@ -1,7 +1,7 @@
 import logging
 from typing import Any, Optional, cast, Union, Dict
 
-from ..types import FeedbackScoreDict
+from ..types import BatchFeedbackScoreDict
 from ..validation import feedback_score as feedback_score_validator
 from .. import logging_messages, llm_usage
 from opik.types import LLMProvider
@@ -38,7 +38,7 @@ def validate_and_parse_usage(
 
 def validate_feedback_score(
     feedback_score: Any, logger: logging.Logger
-) -> Optional[FeedbackScoreDict]:
+) -> Optional[BatchFeedbackScoreDict]:
     feedback_score_validator_ = feedback_score_validator.FeedbackScoreValidator(
         feedback_score
     )
@@ -51,4 +51,4 @@ def validate_feedback_score(
         )
         return None
 
-    return cast(FeedbackScoreDict, feedback_score)
+    return cast(BatchFeedbackScoreDict, feedback_score)

opik/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI commands for Opik."""
+
+from .main import cli
+
+__all__ = ["cli"]

opik/cli/__main__.py

@@ -0,0 +1,6 @@
+"""CLI module entry point."""
+
+from . import cli
+
+if __name__ == "__main__":
+    cli()

opik/cli/configure.py

@@ -0,0 +1,66 @@
+"""Configure command for Opik CLI."""
+
+import logging
+
+import click
+
+from opik.configurator import configure as opik_configure, interactive_helpers
+
+LOGGER = logging.getLogger(__name__)
+
+
+@click.command(context_settings={"ignore_unknown_options": True})
+@click.option(
+    "--use_local",
+    "--use-local",
+    is_flag=True,
+    default=False,
+    help="Flag to configure the Opik Python SDK for local Opik deployments.",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    default=False,
+    help="Flag to automatically answer `yes` whenever a user approval might be required",
+)
+def configure(use_local: bool, yes: bool) -> None:
+    """
+    Create a configuration file for the Opik Python SDK, if a configuration file already exists, it will be overwritten.
+    This is also available as a function in the Python SDK.
+    """
+    automatic_approvals = yes
+
+    if use_local:
+        opik_configure.configure(
+            use_local=True, force=True, automatic_approvals=automatic_approvals
+        )
+    else:
+        deployment_type_choice = interactive_helpers.ask_user_for_deployment_type()
+
+        if deployment_type_choice == interactive_helpers.DeploymentType.CLOUD:
+            configurator = opik_configure.OpikConfigurator(
+                url=opik_configure.OPIK_BASE_URL_CLOUD,
+                use_local=False,
+                force=True,
+                self_hosted_comet=False,
+                automatic_approvals=automatic_approvals,
+            )
+        elif deployment_type_choice == interactive_helpers.DeploymentType.SELF_HOSTED:
+            configurator = opik_configure.OpikConfigurator(
+                use_local=False,
+                force=True,
+                self_hosted_comet=True,
+                automatic_approvals=automatic_approvals,
+            )
+        elif deployment_type_choice == interactive_helpers.DeploymentType.LOCAL:
+            configurator = opik_configure.OpikConfigurator(
+                use_local=True,
+                force=True,
+                self_hosted_comet=False,
+                automatic_approvals=automatic_approvals,
+            )
+        else:
+            raise click.ClickException("Unknown deployment type was selected. Exiting.")
+
+        configurator.configure()