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

opik/api_objects/attachment/client.py

@@ -0,0 +1,220 @@
+import base64
+import logging
+import os
+import mimetypes
+import httpx
+import json.decoder
+from opik import s3_httpx_client
+from typing import Iterator, List, Literal, Optional
+from typing_extensions import TypeAlias
+
+from opik.file_upload import file_uploader, upload_options
+from opik.rest_api import client as rest_api_client
+from opik.rest_api.types import attachment as rest_api_attachment
+from opik.rest_api import core as rest_api_core
+from opik import url_helpers
+
+LOGGER = logging.getLogger(__name__)
+
+RESTAttachmentDetails: TypeAlias = rest_api_attachment.Attachment
+
+
+class AttachmentClient:
+    """
+    Client for interacting with attachment-related operations.
+
+    This client provides methods to retrieve attachment lists, download attachments,
+    and upload attachments for traces and spans.
+
+    The AttachmentClient supports:
+    - Listing attachments associated with traces or spans
+    - Downloading attachment content as a byte stream
+    - Uploading files as attachments to traces or spans
+
+    All operations are performed within the context of a specific project and require
+    the project name to be provided.
+    """
+
+    def __init__(
+        self,
+        rest_client: rest_api_client.OpikApi,
+        url_override: str,
+        workspace_name: str,
+        rest_httpx_client: httpx.Client,
+    ) -> None:
+        """
+        Initialize the AttachmentClient.
+        It is typically created via ``Opik.get_attachment_client()`` rather
+        than being instantiated directly.
+
+        Parameters:
+            rest_client: The REST API client instance for making backend requests.
+            url_override: The base URL for the Opik server.
+            workspace_name: The workspace name used for download operations.
+            rest_httpx_client: The httpx client instance to use for making file uploads.
+
+        Returns:
+            None
+        """
+        self._rest_client = rest_client
+        self._url_override = url_override
+        self._workspace_name = workspace_name
+        self._rest_httpx_client = rest_httpx_client
+
+    def get_attachment_list(
+        self,
+        project_name: str,
+        entity_id: str,
+        entity_type: Literal["span", "trace"],
+    ) -> List[RESTAttachmentDetails]:  # type: ignore
+        """
+        Get a list of attachments for a specific entity (trace or span).
+
+        Parameters:
+            project_name: The name of the project containing the entity.
+            entity_id: The ID of the trace or span to retrieve attachments for.
+            entity_type: The type of entity ("trace" or "span").
+
+        Returns:
+            List[RESTAttachmentDetails]: List of attachment detail objects containing metadata about each attachment.
+        """
+        project_id = self._resolve_project_id(project_name)
+        url_override_path = base64.b64encode(self._url_override.encode("utf-8")).decode(
+            "utf-8"
+        )
+
+        response = self._rest_client.attachments.attachment_list(
+            project_id=project_id,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            path=url_override_path,
+        )
+
+        return response.content or []
+
+    def download_attachment(
+        self,
+        project_name: str,
+        entity_type: Literal["trace", "span"],
+        entity_id: str,
+        file_name: str,
+        mime_type: str,
+    ) -> Iterator[bytes]:
+        """
+        Download an attachment as a stream of bytes.
+
+        Parameters:
+            project_name: The name of the project containing the entity.
+            entity_type: The type of entity ("trace" or "span").
+            entity_id: The ID of the trace or span containing the attachment.
+            file_name: The name of the file to download.
+            mime_type: The MIME type of the file.
+
+        Returns:
+            Iterator[bytes]: Iterator yielding bytes of the attachment content.
+        """
+        attachments_details = self.get_attachment_list(
+            project_name=project_name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        attachment_to_download: Optional[RESTAttachmentDetails] = None
+
+        for attachment_details in attachments_details:
+            if (
+                attachment_details.file_name == file_name
+                and attachment_details.mime_type == mime_type
+            ):
+                attachment_to_download = attachment_details
+                break
+
+        if attachment_to_download is None:
+            raise ValueError(f"Attachment not found: {file_name}")
+
+        if attachment_to_download.link is None:
+            raise ValueError(f"No download URL available for attachment: {file_name}")
+
+        httpx_client_upload = (
+            s3_httpx_client.get_cached()
+            if url_helpers.is_aws_presigned_url(attachment_to_download.link)
+            else self._rest_httpx_client
+        )
+
+        with httpx_client_upload.stream("GET", attachment_to_download.link) as response:
+            try:
+                if 200 <= response.status_code < 300:
+                    for chunk in response.iter_bytes():
+                        yield chunk
+                    return
+                response.read()
+                response_json = response.json()
+            except json.decoder.JSONDecodeError:
+                raise rest_api_core.ApiError(
+                    status_code=response.status_code,
+                    headers=dict(response.headers),
+                    body=response.text,
+                )
+            raise rest_api_core.ApiError(
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                body=response_json,
+            )
+
+    def upload_attachment(
+        self,
+        project_name: str,
+        entity_type: Literal["trace", "span"],
+        entity_id: str,
+        file_path: str,
+        file_name: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> None:
+        """
+        Upload an attachment for a specific entity (trace or span).
+
+        Parameters:
+            project_name: The name of the project containing the entity.
+            entity_type: The type of entity ("trace" or "span").
+            entity_id: The ID of the trace or span to attach the file to.
+            file_path: The path to the file to upload on the local filesystem.
+            file_name: The name to assign to the uploaded file. If not provided, uses the basename of file_path.
+            mime_type: The MIME type of the file. If not provided, attempts to automatically detect based on the file extension.
+
+        Returns:
+            None
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if file_name is None:
+            file_name = os.path.basename(file_path)
+
+        if mime_type is None:
+            mime_type, _ = mimetypes.guess_type(file_path)
+
+        file_size = os.path.getsize(file_path)
+        encoded_url_override = base64.b64encode(
+            self._url_override.encode("utf-8")
+        ).decode("utf-8")
+
+        upload_opts = upload_options.FileUploadOptions(
+            file_path=file_path,
+            file_name=file_name,
+            file_size=file_size,
+            mime_type=mime_type,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            project_name=project_name,
+            encoded_url_override=encoded_url_override,
+            delete_after_upload=False,
+        )
+
+        file_uploader.upload_attachment(
+            upload_options=upload_opts,
+            rest_client=self._rest_client,
+            upload_httpx_client=self._rest_httpx_client,
+        )
+
+    def _resolve_project_id(self, project_name: str) -> str:
+        project = self._rest_client.projects.retrieve_project(name=project_name)
+        return project.id

opik/api_objects/attachment/converters.py

@@ -0,0 +1,51 @@
+import base64
+import os
+from typing import Literal, Optional
+
+from ...file_upload import mime_type
+from ...message_processing import messages
+from . import attachment
+
+
+def attachment_to_message(
+    attachment_data: attachment.Attachment,
+    entity_type: Literal["trace", "span"],
+    entity_id: str,
+    project_name: str,
+    url_override: str,
+    delete_after_upload: bool = False,
+) -> messages.CreateAttachmentMessage:
+    if attachment_data.data is None:
+        raise ValueError("Attachment data cannot be None")
+
+    mimetype = guess_attachment_type(attachment_data)
+    base_url_path = base64.b64encode(url_override.encode("utf-8")).decode("utf-8")
+    file_path = attachment_data.data
+    file_name = attachment_data.file_name
+    if file_name is None:
+        file_name = os.path.basename(file_path)
+
+    return messages.CreateAttachmentMessage(
+        file_path=file_path,
+        file_name=file_name,
+        mime_type=mimetype,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        project_name=project_name,
+        encoded_url_override=base_url_path,
+        delete_after_upload=delete_after_upload,
+    )
+
+
+def guess_attachment_type(attachment_data: attachment.Attachment) -> Optional[str]:
+    if attachment_data.content_type is not None:
+        return attachment_data.content_type
+
+    mimetype = None
+    if attachment_data.file_name is not None:
+        mimetype = mime_type.guess_mime_type(file=attachment_data.file_name)
+
+    if mimetype is None and isinstance(attachment_data.data, str):
+        mimetype = mime_type.guess_mime_type(file=attachment_data.data)
+
+    return mimetype

opik/api_objects/attachment/decoder.py

@@ -0,0 +1,18 @@
+import abc
+from typing import Any, Optional
+
+from . import attachment
+
+
+class AttachmentDecoder(abc.ABC):
+    """
+    Abstract base class for decoding file attachments.
+
+    This class serves as an interface for decoding raw attachment data into
+    an `Attachment` object. Implementing classes should define the specific
+    logic to handle various attachment decoding formats.
+    """
+
+    @abc.abstractmethod
+    def decode(self, raw_data: str, **kwargs: Any) -> Optional[attachment.Attachment]:
+        pass

opik/api_objects/attachment/decoder_base64.py

@@ -0,0 +1,83 @@
+import base64
+import binascii
+import logging
+import tempfile
+from typing import Any, Optional, Literal
+
+from . import attachment, decoder, decoder_helpers
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Base64AttachmentDecoder(decoder.AttachmentDecoder):
+    """Decodes base64 encoded attachment data.
+
+    This decoder decodes base64 strings, detects MIME types from content, and creates Attachment objects.
+    """
+
+    def decode(
+        self,
+        raw_data: str,
+        context: Literal["input", "output", "metadata"] = "input",
+        **kwargs: Any,
+    ) -> Optional[attachment.Attachment]:
+        """Decode base64 encoded data into an Attachment object.
+
+        Args:
+            raw_data: Base64 encoded string data
+            context: Context string for filename generation.
+
+        Returns:
+            Attachment object with decoded data, or None if decoding fails or type is not recognizable
+        """
+        if not isinstance(raw_data, str):
+            LOGGER.warning("Attachment data is not a string, skipping.")
+            return None
+
+        try:
+            # Decode base64 string to bytes
+            decoded_bytes = base64.b64decode(raw_data, validate=True)
+
+            # Detect MIME type from content
+            mime_type = decoder_helpers.detect_mime_type(decoded_bytes)
+
+            # Skip if not a recognizable file type
+            if not mime_type or mime_type in ("application/octet-stream", "text/plain"):
+                LOGGER.debug("Attachment type is not recognized, skipping.")
+                return None
+
+            # Get file extension from the MIME type
+            extension = decoder_helpers.get_file_extension(mime_type)
+
+            # Generate filename
+            file_name = decoder_helpers.create_attachment_filename(
+                context, extension=extension
+            )
+
+            # Save decoded bytes to a temporary file
+            temp_file = tempfile.NamedTemporaryFile(
+                mode="wb", delete=False, suffix=extension
+            )
+            temp_file.write(decoded_bytes)
+            temp_file.flush()
+            temp_file.close()
+
+            # Return Attachment object with a file path
+            return attachment.Attachment(
+                data=temp_file.name, file_name=file_name, content_type=mime_type
+            )
+
+        except (ValueError, binascii.Error) as e:
+            LOGGER.debug(
+                "Failed to decode attachment data, reason: invalid base64. Reason: %s",
+                e,
+                exc_info=True,
+            )
+            # Not valid base64, return None
+            return None
+        except Exception as ex:
+            LOGGER.warning(
+                "Failed to decode attachment data, reason: %s", ex, exc_info=True
+            )
+            # Unexpected error, return None to avoid crashing the pipeline
+            return None

opik/api_objects/attachment/decoder_helpers.py

@@ -0,0 +1,137 @@
+import mimetypes
+import random
+import time
+from typing import Optional
+
+
+# The attachment file name regex
+ATTACHMENT_FILE_NAME_REGEX = r"(?:input|output|metadata)-attachment-\d+-\d+-sdk\.\w+"
+ATTACHMENT_FILE_NAME_PLACEHOLDER_REGEX = (
+    r"\[((?:input|output|metadata)-attachment-\d+-\d+-sdk\.\w+)\]"
+)
+
+
+def get_file_extension(mime_type: str) -> str:
+    """Convert MIME type to file extension.
+
+    Mirrors the Java getFileExtension() method in AttachmentStripperService.
+
+    Args:
+        mime_type: The MIME type (e.g., "image/png", "application/pdf")
+
+    Returns:
+        File extension without a leading dot (e.g., "png", "pdf")
+    """
+    if not mime_type:
+        return "bin"
+
+    # Try to get extension from mimetypes module
+    extension = mimetypes.guess_extension(mime_type, strict=False)
+
+    if extension:
+        # Remove the leading dot
+        extension = extension.lstrip(".")
+        # Handle special cases where mimetypes returns less common extensions
+        if mime_type == "image/jpeg" and extension == "jpe":
+            return "jpg"
+        return extension
+
+    # Fallback: extract from the MIME type (e.g., "image/png" -> "png")
+    if "/" in mime_type:
+        subtype = mime_type.split("/")[1]
+        # Handle special cases like "svg+xml" -> "svg"
+        if "+" in subtype:
+            subtype = subtype.split("+")[0]
+        # Remove any parameters (e.g., "jpeg; charset=utf-8" -> "jpeg")
+        subtype = subtype.split(";")[0].strip()
+        return subtype
+
+    return "bin"
+
+
+def detect_mime_type(data: bytes) -> Optional[str]:
+    """Detect MIME type from byte content using magic bytes.
+
+    This provides basic MIME type detection similar to Apache Tika in the Java implementation.
+    It checks common file format magic bytes.
+
+    Args:
+        data: The byte data to analyze
+
+    Returns:
+        Detected MIME type string, or "application/octet-stream" if unknown
+    """
+    if len(data) < 4:
+        return "application/octet-stream"
+
+    # Check common file format magic bytes
+    # PNG
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+
+    # JPEG
+    if data[:2] == b"\xff\xd8" and data[-2:] == b"\xff\xd9":
+        return "image/jpeg"
+
+    # GIF
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+
+    # PDF
+    if data[:4] == b"%PDF":
+        return "application/pdf"
+
+    # WebP
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+
+    # SVG (XML-based, check for SVG tag)
+    try:
+        text = data[:1024].decode("utf-8", errors="ignore")
+        if "<svg" in text.lower():
+            return "image/svg+xml"
+    except Exception:
+        pass
+
+    # MP4
+    if len(data) >= 12 and data[4:8] == b"ftyp":
+        return "video/mp4"
+
+    # JSON
+    try:
+        text = data[:100].decode("utf-8", errors="strict").strip()
+        if text.startswith("{") or text.startswith("["):
+            return "application/json"
+    except Exception:
+        pass
+
+    # Default to octet-stream for unknown types
+    return "application/octet-stream"
+
+
+def create_attachment_filename(context: str, extension: str) -> str:
+    """
+    Generates a unique attachment filename based on the provided context and file extension.
+
+    This function creates a filename by combining the given context, a randomly generated
+    prefix to ensure uniqueness, the current timestamp in milliseconds, and the provided
+    file extension. The generated filename aligns with the backend convention for naming
+    attachments, which includes specific formatting and structure.
+
+    Args:
+        context: The context to use as the base for the filename (e.g., "input",
+            "output", or "metadata").
+        extension: The file extension to use for the filename (e.g., "png",
+            "jpg", "txt").
+
+    Returns:
+        A generated filename string in the format
+            "{context}-attachment-{random_prefix}-{timestamp}.{extension}".
+    """
+    # The backend has the following naming convention: r"\\[((?:input|output|metadata)-attachment-\\d+-\\d+\\.\\w+)\\]"
+    # Example: [input-attachment-1-1704067200000.png]
+
+    timestamp = int(round(time.time() * 1000))
+    # we need to generate a large enough random prefix to avoid collisions
+    random_prefix = random.randint(1, 99999999)
+    return f"{context}-attachment-{random_prefix}-{timestamp}-sdk.{extension}"

opik/api_objects/conversation/conversation_factory.py

@@ -0,0 +1,43 @@
+from typing import List, Callable
+
+from opik.rest_api import TracePublic, JsonListStringPublic
+from . import conversation_thread
+
+
+def create_conversation_from_traces(
+    traces: List[TracePublic],
+    input_transform: Callable[[JsonListStringPublic], str],
+    output_transform: Callable[[JsonListStringPublic], str],
+) -> conversation_thread.ConversationThread:
+    """
+    Creates a conversation object from given traces, transforming inputs and outputs using
+    provided transformation functions. The method processes each trace to compose a complete
+    conversation by consecutively adding user messages and assistant messages.
+
+    Args:
+        traces: A list of TracePublic objects representing trace data for user
+            and assistant interaction flows.
+        input_transform: A callable function that transforms the input data
+            from a JsonListStringPublic format to a string.
+        output_transform: A callable function that transforms the output data
+            from a JsonListStringPublic format to a string.
+
+    Returns:
+        A Conversation object that contains user and assistant message
+        sequences derived from the provided traces.
+    """
+    # Sort traces by start time to ensure they are processed in the correct order -
+    # the first user message should be first recorded
+    traces.sort(key=lambda trace_: trace_.start_time)
+
+    discussion = conversation_thread.ConversationThread()
+    for trace in traces:
+        trace_input = input_transform(trace.input)
+        if trace_input is not None:
+            discussion.add_user_message(trace_input)
+
+        trace_output = output_transform(trace.output)
+        if trace_output is not None:
+            discussion.add_assistant_message(trace_output)
+
+    return discussion

opik/api_objects/conversation/conversation_thread.py

@@ -0,0 +1,49 @@
+from typing import Dict, List
+
+import pydantic
+
+
+class ConversationThreadItem(pydantic.BaseModel):
+    """
+    Represents a single message within a conversation thread.
+
+    Each ConversationItem contains the role of the sender (e.g., 'user', 'assistant', 'system')
+    and the content of the message. This structured format allows for consistent representation
+    of messages across different conversation interfaces and evaluation systems.
+    """
+
+    role: str
+    content: str
+
+
+class ConversationThread(pydantic.BaseModel):
+    """
+    Represents a conversation thread composed of multiple conversation items.
+
+    This class is built using Pydantic's BaseModel to ensure type validation and data
+    integrity. It maintains a list of conversation items, where each item is an
+    instance of the `ConversationThreadItem` class. The conversation thread allows
+    adding messages from various roles, such as assistant, user, and system, and
+    provides the ability to export the conversation data as a JSON-serializable list.
+
+    Attributes:
+        discussion (List[ConversationThreadItem]): A list of conversation items
+            representing the dialogue between the roles.
+    """
+
+    discussion: List[ConversationThreadItem] = pydantic.Field(default_factory=list)
+
+    def add_item(self, item: ConversationThreadItem) -> None:
+        self.discussion.append(item)
+
+    def add_assistant_message(self, message: str) -> None:
+        self.add_item(ConversationThreadItem(role="assistant", content=message))
+
+    def add_user_message(self, message: str) -> None:
+        self.add_item(ConversationThreadItem(role="user", content=message))
+
+    def add_system_message(self, message: str) -> None:
+        self.add_item(ConversationThreadItem(role="system", content=message))
+
+    def as_json_list(self) -> List[Dict[str, str]]:
+        return [item.model_dump() for item in self.discussion]

opik/api_objects/data_helpers.py

@@ -0,0 +1,79 @@
+from typing import Optional, Any, Dict, List, Union
+
+import pydantic
+
+from opik import dict_utils
+
+
+def merge_tags(
+    existing_tags: Optional[List[str]], new_tags: Optional[List[str]]
+) -> Optional[List[str]]:
+    """Merge tag lists, preserving existing tags and adding new ones.
+
+    If both existing_tags and new_tags are None or empty, return None."""
+    if existing_tags is None and new_tags is None:
+        return None
+
+    result = list(existing_tags or [])
+    if new_tags:
+        for tag in new_tags:
+            if tag not in result:
+                result.append(tag)
+
+    return result if result else None
+
+
+def merge_metadata(
+    existing_metadata: Optional[Dict[str, Any]],
+    new_metadata: Optional[Union[Dict[str, Any], pydantic.BaseModel]],
+    prompts: Optional[List[Dict[str, Any]]] = None,
+) -> Optional[Dict[str, Any]]:
+    """Merge the existing metadata dictionary with new data, with new values taking precedence.
+
+    If both existing_metadata and new_metadata are None or empty, return None.
+    """
+    if prompts is not None:
+        new_metadata = new_metadata or {}
+        new_metadata["opik_prompts"] = prompts
+
+    return _merge_dictionary_with_data(existing_metadata, new_data=new_metadata)
+
+
+def merge_inputs(
+    existing_inputs: Optional[Dict[str, Any]],
+    new_inputs: Optional[Union[Dict[str, Any], pydantic.BaseModel]],
+) -> Optional[Dict[str, Any]]:
+    """Merge the existing input dictionary with new data, with new values taking precedence.
+
+    If both existing_inputs and new_inputs are None or empty, return None."""
+    return _merge_dictionary_with_data(existing_inputs, new_data=new_inputs)
+
+
+def merge_outputs(
+    existing_outputs: Optional[Dict[str, Any]],
+    new_outputs: Optional[Union[Dict[str, Any], pydantic.BaseModel]],
+) -> Optional[Dict[str, Any]]:
+    """Merge the existing output dictionary with new data, with new values taking precedence.
+
+    If both existing_outputs and new_outputs are None or empty, return None."""
+    return _merge_dictionary_with_data(existing_outputs, new_data=new_outputs)
+
+
+def _merge_dictionary_with_data(
+    existing_dict: Optional[Dict[str, Any]],
+    new_data: Optional[Union[Dict[str, Any], pydantic.BaseModel]],
+) -> Optional[Dict[str, Any]]:
+    """Merge the dictionary with new data, with new values taking precedence.
+
+    If both existing_dict and new_data are None or empty, return None."""
+    if existing_dict is None and new_data is None:
+        return None
+
+    if isinstance(new_data, pydantic.BaseModel):
+        new_data = new_data.model_dump()
+
+    result = dict(existing_dict or {})
+    if new_data:
+        result = dict_utils.deepmerge(result, new_data)
+
+    return result if result else None