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

opik/api_objects/span/span_data.py

@@ -5,16 +5,15 @@ from typing import Any, Dict, List, Optional, Union
 
 import opik.api_objects.attachment as attachment
 import opik.datetime_helpers as datetime_helpers
-import opik.dict_utils as dict_utils
 import opik.llm_usage as llm_usage
 from opik.types import (
+    DistributedTraceHeadersDict,
     ErrorInfoDict,
     FeedbackScoreDict,
     LLMProvider,
     SpanType,
 )
-
-from .. import helpers
+from .. import helpers, data_helpers
 
 LOGGER = logging.getLogger(__name__)
 
@@ -97,11 +96,24 @@ class SpanData:
         )
 
     def update(self, **new_data: Any) -> "SpanData":
+        """
+        Updates the attributes of the object with the provided key-value pairs. This method checks if
+        an attribute exists before updating it and merges the data appropriately for specific
+        keywords like metadata, output, input, attachments, and tags. If a key doesn't correspond
+        to an attribute of the object or the provided value is None, the update is skipped.
+
+        Args:
+            **new_data: Key-value pairs of attributes to update. Keys should match existing
+                attributes on the object, and values that are None will not update.
+
+        Returns:
+            SpanData: The updated object instance.
+        """
         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,
@@ -109,40 +121,32 @@ class SpanData:
                 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 _update_output(self, new_output: Dict[str, Any]) -> None:
-        if self.output is None:
-            self.output = new_output
-        else:
-            self.output = dict_utils.deepmerge(self.output, new_output)
-
-    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)
-
     def init_end_time(self) -> "SpanData":
         self.end_time = datetime_helpers.local_timestamp()
 
@@ -199,3 +203,9 @@ class SpanData:
             "total_cost": self.total_cost,
             "attachments": self.attachments,
         }
+
+    def get_distributed_trace_headers(self) -> DistributedTraceHeadersDict:
+        return DistributedTraceHeadersDict(
+            opik_trace_id=self.trace_id,
+            opik_parent_span_id=self.id,
+        )

opik/api_objects/threads/threads_client.py

@@ -3,7 +3,7 @@ from typing import List, Optional
 
 import opik
 from opik.rest_api import TraceThread
-from opik.types import FeedbackScoreDict
+from opik.types import BatchFeedbackScoreDict
 
 from .. import helpers, rest_stream_parser, constants
 from ... import config
@@ -54,8 +54,41 @@ class ThreadsClient:
                 The name of the project to search the threads for. If None, the search
                 will include threads from all projects.
             filter_string:
-                A string used to filter threads based on specific conditions. The
-                format and details of the filter depend on the implementation.
+                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.
@@ -96,7 +129,7 @@ class ThreadsClient:
         return threads
 
     def log_threads_feedback_scores(
-        self, scores: List[FeedbackScoreDict], project_name: Optional[str] = None
+        self, scores: List[BatchFeedbackScoreDict], project_name: Optional[str] = None
     ) -> None:
         """
         Logs feedback scores for threads in a specific project. This method processes the given
@@ -107,7 +140,8 @@ class ThreadsClient:
             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 scores won't be associated with any specific project.
+                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
 

opik/api_objects/trace/trace_client.py

@@ -97,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,
@@ -108,7 +109,6 @@ class Trace:
             error_info=error_info,
             thread_id=thread_id,
         )
-        self._streamer.put(update_trace_message)
 
     def span(
         self,
@@ -215,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

@@ -3,9 +3,7 @@ import datetime
 import logging
 from typing import Any, Dict, List, Optional, Union
 
-import opik.dict_utils as dict_utils
 import opik.api_objects.attachment as attachment
-from .. import span
 import opik.datetime_helpers as datetime_helpers
 import opik.id_helpers as id_helpers
 import opik.llm_usage as llm_usage
@@ -16,6 +14,7 @@ from opik.types import (
     LLMProvider,
     SpanType,
 )
+from .. import span, data_helpers
 
 LOGGER = logging.getLogger(__name__)
 
@@ -97,7 +96,7 @@ class TraceData:
             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,
@@ -105,40 +104,32 @@ 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 _update_output(self, new_output: Dict[str, Any]) -> None:
-        if self.output is None:
-            self.output = new_output
-        else:
-            self.output = dict_utils.deepmerge(self.output, new_output)
-
-    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)
-
     def init_end_time(self) -> "TraceData":
         self.end_time = datetime_helpers.local_timestamp()
         return self

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()

opik/cli/exports/__init__.py

@@ -0,0 +1,131 @@
+"""Download command for Opik CLI."""
+
+from typing import Optional
+
+import click
+
+from .dataset import export_dataset_command
+from .experiment import export_experiment_command
+from .prompt import export_prompt_command
+from .project import export_project_command
+
+EXPORT_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(
+    name="export", context_settings=EXPORT_CONTEXT_SETTINGS, invoke_without_command=True
+)
+@click.argument("workspace", type=str)
+@click.option(
+    "--api-key",
+    type=str,
+    help="Opik API key. If not provided, will use OPIK_API_KEY environment variable or configuration.",
+)
+@click.pass_context
+def export_group(ctx: click.Context, workspace: str, api_key: Optional[str]) -> None:
+    """Export data from Opik workspace.
+
+    This command allows you to export specific data from an Opik workspace to local files.
+    Supported data types include datasets, projects, experiments, and prompts.
+
+    \b
+    General Usage:
+        opik export WORKSPACE ITEM NAME [OPTIONS]
+
+    \b
+    Data Types (ITEM):
+        dataset      Export a dataset by exact name (exports dataset definition and items)
+        project      Export a project by name or ID (exports project traces and metadata)
+        experiment   Export an experiment by name or ID (exports experiment configuration and results)
+        prompt       Export a prompt by exact name (exports prompt templates and versions)
+
+    \b
+    Common Options:
+        --path, -p       Directory to save exported data (default: opik_exports)
+        --format         Export format: json or csv (default: json)
+        --max-results    Maximum number of items to export (varies by data type)
+        --force          Re-download items even if they already exist locally
+        --debug          Show detailed information about the export process
+
+    \b
+    Examples:
+        # Export a specific dataset
+        opik export my-workspace dataset "my-dataset"
+
+        # Export a project with OQL filter
+        opik export my-workspace project "my-project" --filter "status:completed"
+
+        # Export an experiment with dataset filter (by name or ID)
+        opik export my-workspace experiment "my-experiment" --dataset "my-dataset"
+        opik export my-workspace experiment "01234567-89ab-cdef-0123-456789abcdef" --dataset "my-dataset"
+
+        # Export in CSV format to a specific directory
+        opik export my-workspace prompt "my-template" --format csv --path ./custom-exports
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["workspace"] = workspace
+    # Use API key from this command or from parent context
+    ctx.obj["api_key"] = api_key or (
+        ctx.parent.obj.get("api_key") if ctx.parent and ctx.parent.obj else None
+    )
+
+    # If no subcommand was invoked, show helpful error
+    if ctx.invoked_subcommand is None:
+        available_items = ", ".join(
+            sorted(["dataset", "experiment", "prompt", "project"])
+        )
+        click.echo(
+            f"Error: Missing ITEM.\n\n"
+            f"Available items: {available_items}\n\n"
+            f"Usage: opik export {workspace} ITEM NAME [OPTIONS]\n\n"
+            f"Examples:\n"
+            f'  opik export {workspace} dataset "my-dataset"\n'
+            f'  opik export {workspace} project "my-project"\n'
+            f'  opik export {workspace} experiment "my-experiment"\n'
+            f'  opik export {workspace} prompt "my-template"\n\n'
+            f"Run 'opik export {workspace} --help' for more information.",
+            err=True,
+        )
+        ctx.exit(2)
+
+
+# Set subcommand metavar to ITEM instead of COMMAND
+export_group.subcommand_metavar = "ITEM [ARGS]..."
+
+
+def format_commands(
+    self: click.Group, ctx: click.Context, formatter: click.HelpFormatter
+) -> None:
+    """Override to change 'Commands' heading to 'Items'."""
+    commands = []
+    for subcommand in self.list_commands(ctx):
+        cmd = self.get_command(ctx, subcommand)
+        if cmd is None or cmd.hidden:
+            continue
+        commands.append((subcommand, cmd))
+
+    if len(commands):
+        limit = formatter.width - 6 - max(len(cmd[0]) for cmd in commands)
+        rows = []
+        for subcommand, cmd in commands:
+            help = cmd.get_short_help_str(limit)
+            rows.append((subcommand, help))
+
+        if rows:
+            with formatter.section("Items"):
+                formatter.write_dl(rows)
+
+
+# Override format_commands method
+setattr(
+    export_group,
+    "format_commands",
+    format_commands.__get__(export_group, type(export_group)),
+)
+
+
+# Add the subcommands
+export_group.add_command(export_dataset_command)
+export_group.add_command(export_experiment_command)
+export_group.add_command(export_prompt_command)
+export_group.add_command(export_project_command)