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

opik/decorator/opik_args/api_classes.py

@@ -0,0 +1,71 @@
+import logging
+from typing import Any, Dict, List, Optional
+
+import pydantic
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class OpikArgsSpan(pydantic.BaseModel):
+    """
+    Configuration for span updates passed via opik_args parameter.
+    """
+
+    tags: Optional[List[str]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class OpikArgsTrace(pydantic.BaseModel):
+    """
+    Configuration for trace updates passed via opik_args parameter.
+    """
+
+    thread_id: Optional[str] = None
+    tags: Optional[List[str]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class OpikArgs(pydantic.BaseModel):
+    """
+    Configuration structure for special opik arguments passed to tracked functions.
+
+    This allows users to specify span and trace updates without modifying function bodies.
+    Tags and metadata are merged (not overwritten) with existing values.
+    """
+
+    span_args: Optional[OpikArgsSpan] = None
+    trace_args: Optional[OpikArgsTrace] = None
+
+    @classmethod
+    def from_dict(cls, config_dict: Optional[Dict[str, Any]]) -> Optional["OpikArgs"]:
+        """Create OpikArgs from dictionary, with validation."""
+        if not isinstance(config_dict, dict):
+            LOGGER.warning("opik_args must be a dictionary, got %s", type(config_dict))
+            return None
+
+        span_args = None
+        trace_args = None
+
+        if "span" in config_dict:
+            span_data = config_dict["span"]
+            if isinstance(span_data, dict):
+                span_args = OpikArgsSpan(
+                    tags=span_data.get("tags"),
+                    metadata=span_data.get("metadata"),
+                )
+            else:
+                LOGGER.warning("opik_args['span'] must be a dictionary")
+
+        if "trace" in config_dict:
+            trace_data = config_dict["trace"]
+            if isinstance(trace_data, dict):
+                trace_args = OpikArgsTrace(
+                    thread_id=trace_data.get("thread_id"),
+                    tags=trace_data.get("tags"),
+                    metadata=trace_data.get("metadata"),
+                )
+            else:
+                LOGGER.warning("opik_args['trace'] must be a dictionary")
+
+        return cls(span_args=span_args, trace_args=trace_args)

opik/decorator/opik_args/helpers.py

@@ -0,0 +1,120 @@
+import inspect
+import logging
+from typing import Any, Dict, Optional, Callable
+
+from .. import arguments_helpers
+from ...api_objects import trace, data_helpers
+from . import api_classes
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+def extract_opik_args(
+    kwargs: Dict[str, Any], func: Callable
+) -> Optional[api_classes.OpikArgs]:
+    """
+    Extracts opik_args from kwargs and returns the parsed OpikArgs or None.
+
+    Mutates kwargs in place by removing "opik_args" if the function does not explicitly
+    declare opik_args as a parameter.
+
+    Args:
+        kwargs: Function keyword arguments
+        func: The function being decorated
+
+    Returns:
+        opik_args if found, otherwise None.
+    """
+
+    # Check if a function has opik_args in its signature
+    try:
+        sig = inspect.signature(func)
+        has_opik_args_param = "opik_args" in sig.parameters
+    except (ValueError, TypeError):
+        # If we can't inspect the signature, assume no opik_args parameter
+        has_opik_args_param = False
+
+    # If function explicitly has opik_args parameter, just get it without popping
+    if has_opik_args_param:
+        opik_args_dict = kwargs.get("opik_args", None)
+    else:
+        # If function doesn't have opik_args parameter, pop it from kwargs
+        opik_args_dict = kwargs.pop("opik_args", None)
+
+    if opik_args_dict is None:
+        return None
+
+    return api_classes.OpikArgs.from_dict(opik_args_dict)
+
+
+def apply_opik_args_to_trace(
+    opik_args: Optional[api_classes.OpikArgs],
+    trace_data: Optional[trace.TraceData],
+) -> None:
+    """
+    Apply opik_args to the trace data, including thread_id, tags, and metadata.
+
+    Args:
+        opik_args: The configuration extracted from function arguments
+        trace_data: The current trace data to modify
+    """
+    if opik_args is None or opik_args.trace_args is None or trace_data is None:
+        return
+
+    # Handle thread_id
+    if opik_args.trace_args.thread_id is not None:
+        # Check for thread_id conflict
+        if (
+            trace_data.thread_id is not None
+            and trace_data.thread_id != opik_args.trace_args.thread_id
+        ):
+            LOGGER.warning(
+                "Trace already has thread_id='%s', but opik_args specifies thread_id='%s'. Keeping existing thread_id.",
+                trace_data.thread_id,
+                opik_args.trace_args.thread_id,
+            )
+        else:
+            # Apply thread_id to trace
+            trace_data.thread_id = opik_args.trace_args.thread_id
+
+    # Apply trace tags if specified
+    if opik_args.trace_args.tags:
+        existing_tags = trace_data.tags or []
+        merged_tags = data_helpers.merge_tags(existing_tags, opik_args.trace_args.tags)
+        trace_data.tags = merged_tags
+
+    # Apply trace metadata if specified
+    if opik_args.trace_args.metadata:
+        existing_metadata = trace_data.metadata or {}
+        merged_metadata = data_helpers.merge_metadata(
+            existing_metadata, opik_args.trace_args.metadata
+        )
+        trace_data.metadata = merged_metadata
+
+
+def apply_opik_args_to_start_span_params(
+    params: arguments_helpers.StartSpanParameters,
+    opik_args: Optional[api_classes.OpikArgs],
+) -> arguments_helpers.StartSpanParameters:
+    """Apply opik_args to StartSpanParameters, merging tags and metadata."""
+    if opik_args is None or opik_args.span_args is None:
+        return params
+
+    span_config = opik_args.span_args
+
+    # Merge tags and metadata
+    merged_tags = data_helpers.merge_tags(params.tags, span_config.tags)
+    merged_metadata = data_helpers.merge_metadata(params.metadata, span_config.metadata)
+
+    # Create updated parameters
+    return arguments_helpers.StartSpanParameters(
+        type=params.type,
+        name=params.name,
+        tags=merged_tags,
+        metadata=merged_metadata,
+        input=params.input,
+        project_name=params.project_name,
+        model=params.model,
+        provider=params.provider,
+    )

opik/decorator/span_creation_handler.py

@@ -1,6 +1,6 @@
 from typing import (
     Optional,
-    Tuple,
+    NamedTuple,
 )
 
 import opik.context_storage as context_storage
@@ -11,11 +11,29 @@ from opik.types import DistributedTraceHeadersDict
 from . import arguments_helpers
 
 
+class SpanCreationResult(NamedTuple):
+    """
+    Represents the result of a span creation process.
+
+    This class encapsulates the data resulting from the creation of a new
+    span, including trace information and span-specific details.
+
+    Attributes:
+        trace_data: Trace-related data associated
+            with the span if a new trace was created. Can be None if no new trace was created.
+        span_data : Data specific to the created span, containing
+            information such as span identifiers and timestamps.
+    """
+
+    trace_data: Optional[trace.TraceData]
+    span_data: span.SpanData
+
+
 def create_span_respecting_context(
     start_span_arguments: arguments_helpers.StartSpanParameters,
     distributed_trace_headers: Optional[DistributedTraceHeadersDict],
     opik_context_storage: Optional[context_storage.OpikContextStorage] = None,
-) -> Tuple[Optional[trace.TraceData], span.SpanData]:
+) -> SpanCreationResult:
     """
     Handles different span creation flows.
     """
@@ -30,7 +48,7 @@ def create_span_respecting_context(
             trace_id=distributed_trace_headers["opik_trace_id"],
         )
 
-        return None, span_data
+        return SpanCreationResult(None, span_data)
 
     current_span_data = opik_context_storage.top_span_data()
     current_trace_data = opik_context_storage.get_trace_data()
@@ -60,7 +78,7 @@ def create_span_respecting_context(
             trace_id=current_span_data.trace_id,
         )
 
-        return None, span_data
+        return SpanCreationResult(None, span_data)
 
     if current_trace_data is not None and current_span_data is None:
         # By default, we expect trace to be created with a span.
@@ -82,7 +100,7 @@ def create_span_respecting_context(
             trace_id=current_trace_data.id,
         )
 
-        return None, span_data
+        return SpanCreationResult(None, span_data)
 
     if current_span_data is None and current_trace_data is None:
         # Create a trace and root span because it is
@@ -95,6 +113,7 @@ def create_span_respecting_context(
             metadata=start_span_arguments.metadata,
             tags=start_span_arguments.tags,
             project_name=start_span_arguments.project_name,
+            thread_id=start_span_arguments.thread_id,
         )
 
         current_span_data = arguments_helpers.create_span_data(
@@ -103,4 +122,4 @@ def create_span_respecting_context(
             trace_id=current_trace_data.id,
         )
 
-    return current_trace_data, current_span_data
+    return SpanCreationResult(current_trace_data, current_span_data)

opik/dict_utils.py

@@ -1,6 +1,6 @@
 import copy
 import logging
-from typing import Any, Dict, Mapping, Optional, List, Tuple, TypeVar, Type
+from typing import Any, Dict, Optional, List, Tuple, TypeVar, Type
 
 from . import logging_messages
 
@@ -11,7 +11,7 @@ def flatten_dict(
     d: Dict[str, Any], parent_key: str, delim: str = "."
 ) -> Dict[str, Any]:
     """
-    Current implementation does not have max depth restrictions or cyclic references handling!
+    The current implementation does not have max depth restrictions or cyclic references handling!
     """
     items = []  # type: ignore
 
@@ -60,7 +60,7 @@ def deepmerge(
     return merged
 
 
-def remove_none_from_dict(original: Mapping[str, Optional[Any]]) -> Mapping[str, Any]:
+def remove_none_from_dict(original: Dict[str, Optional[Any]]) -> Dict[str, Any]:
     new: Dict[str, Any] = {}
 
     for key, value in original.items():

opik/evaluation/__init__.py

@@ -1,4 +1,15 @@
-from .evaluator import evaluate, evaluate_prompt, evaluate_experiment
+from .evaluator import (
+    evaluate,
+    evaluate_prompt,
+    evaluate_experiment,
+    evaluate_on_dict_items,
+)
 from .threads.evaluator import evaluate_threads
 
-__all__ = ["evaluate", "evaluate_prompt", "evaluate_experiment", "evaluate_threads"]
+__all__ = [
+    "evaluate",
+    "evaluate_prompt",
+    "evaluate_experiment",
+    "evaluate_on_dict_items",
+    "evaluate_threads",
+]