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

opik/cli/usage_report/pdf.py

@@ -0,0 +1,244 @@
+"""PDF report generation functions for usage report module."""
+
+import os
+import traceback
+from typing import Any, Dict
+
+from rich.console import Console
+
+from .charts import create_individual_chart
+from .statistics import calculate_statistics
+
+console = Console()
+
+
+def create_pdf_report(data: Dict[str, Any], output_dir: str = ".") -> str:
+    """
+    Create a PDF report with statistics page and individual chart pages.
+
+    Args:
+        data: The extracted data dictionary
+        output_dir: Directory to save PDF (default: current directory)
+
+    Returns:
+        Path to saved PDF file
+    """
+    try:
+        from reportlab.lib import colors
+        from reportlab.lib.pagesizes import letter
+        from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+        from reportlab.lib.units import inch
+        from reportlab.platypus import (
+            Image,
+            PageBreak,
+            Paragraph,
+            SimpleDocTemplate,
+            Spacer,
+            Table,
+            TableStyle,
+        )
+    except ImportError:
+        raise ImportError(
+            "reportlab is required for PDF report generation. "
+            "Please install it with: pip install reportlab"
+        )
+
+    # Calculate statistics
+    stats = calculate_statistics(data)
+
+    # Create PDF
+    pdf_filename = os.path.join(
+        output_dir, f"opik_usage_report_{data['workspace']}.pdf"
+    )
+    doc = SimpleDocTemplate(pdf_filename, pagesize=letter)
+    story = []
+
+    # Get styles
+    styles = getSampleStyleSheet()
+    title_style = ParagraphStyle(
+        "CustomTitle",
+        parent=styles["Heading1"],
+        fontSize=24,
+        textColor=colors.HexColor("#1a1a1a"),
+        spaceAfter=30,
+        alignment=1,  # Center alignment
+    )
+    heading_style = ParagraphStyle(
+        "CustomHeading",
+        parent=styles["Heading2"],
+        fontSize=16,
+        textColor=colors.HexColor("#2c3e50"),
+        spaceAfter=12,
+    )
+
+    # Title page / First page with statistics
+    story.append(Paragraph("Opik Usage Report", title_style))
+    story.append(Spacer(1, 0.3 * inch))
+
+    # Statistics section
+    story.append(Paragraph("Summary Statistics", heading_style))
+    story.append(Spacer(1, 0.1 * inch))
+
+    # Format dates for display
+    extraction_date_str = "N/A"
+    if stats["extraction_date"]:
+        try:
+            extraction_date_str = stats["extraction_date"][:10]
+        except (TypeError, IndexError):
+            extraction_date_str = (
+                str(stats["extraction_date"])[:10]
+                if stats["extraction_date"]
+                else "N/A"
+            )
+
+    start_date_str = "N/A"
+    end_date_str = "N/A"
+    if stats["date_range"].get("start"):
+        try:
+            start_date_str = stats["date_range"]["start"][:10]
+        except (TypeError, IndexError):
+            start_date_str = (
+                str(stats["date_range"]["start"])[:10]
+                if stats["date_range"]["start"]
+                else "N/A"
+            )
+    if stats["date_range"].get("end"):
+        try:
+            end_date_str = stats["date_range"]["end"][:10]
+        except (TypeError, IndexError):
+            end_date_str = (
+                str(stats["date_range"]["end"])[:10]
+                if stats["date_range"]["end"]
+                else "N/A"
+            )
+
+    # Create statistics table
+    stats_data = [
+        ["Workspace", stats["workspace"]],
+        ["Extraction Date", extraction_date_str],
+        ["Date Range", f"{start_date_str} to {end_date_str}"],
+        ["Aggregation Unit", stats["unit"].capitalize()],
+        ["", ""],  # Separator row
+        ["Total Projects", str(stats["total_projects"])],
+        ["Projects with Data", str(stats["projects_with_data"])],
+        ["Periods with Data", str(stats["periods_with_data"])],
+        ["", ""],  # Separator row
+        ["Total Experiments", f"{stats['total_experiments']:,}"],
+        ["Total Datasets", f"{stats['total_datasets']:,}"],
+        ["Total Traces", f"{stats['total_traces']:,.0f}"],
+        ["Total Spans", f"{stats['total_spans']:,.0f}"],
+        ["Total Tokens", f"{stats['total_tokens']:,.0f}"],
+        ["Total Cost", f"${stats['total_cost']:,.2f}"],
+    ]
+
+    stats_table = Table(stats_data, colWidths=[2.5 * inch, 4 * inch])
+    stats_table.setStyle(
+        TableStyle(
+            [
+                ("BACKGROUND", (0, 0), (0, -1), colors.HexColor("#ecf0f1")),
+                ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#2c3e50")),
+                ("ALIGN", (0, 0), (-1, -1), "LEFT"),
+                ("FONTNAME", (0, 0), (0, -1), "Helvetica-Bold"),
+                ("FONTNAME", (1, 0), (1, -1), "Helvetica"),
+                ("FONTSIZE", (0, 0), (-1, -1), 10),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+                ("TOPPADDING", (0, 0), (-1, -1), 8),
+                ("GRID", (0, 0), (-1, -1), 0.5, colors.HexColor("#bdc3c7")),
+            ]
+        )
+    )
+
+    story.append(stats_table)
+    story.append(PageBreak())
+
+    # Create individual charts and add to PDF
+    chart_types = [
+        ("trace_count", "Trace Count"),
+        ("span_count", "Span Count"),
+        ("token_count", "Token Count"),
+        ("cost", "Cost"),
+        ("experiment_count", "Experiment Count"),
+        ("dataset_count", "Dataset Count"),
+    ]
+
+    chart_files_to_cleanup = []  # Keep track of files to delete after PDF is built
+
+    for chart_type, chart_title in chart_types:
+        try:
+            chart_path = create_individual_chart(data, chart_type, output_dir)
+            if chart_path:
+                # Ensure path is absolute
+                chart_path = os.path.abspath(chart_path)
+                # Double-check file exists and is readable
+                if os.path.exists(chart_path) and os.access(chart_path, os.R_OK):
+                    # Add chart title
+                    story.append(Paragraph(chart_title, heading_style))
+                    story.append(Spacer(1, 0.1 * inch))
+
+                    # Add chart image (legend is already included in the chart image below the chart)
+                    try:
+                        # Use absolute path and verify file is readable
+                        if not os.path.exists(chart_path):
+                            console.print(
+                                f"[yellow]Warning: Chart file disappeared: {chart_path}[/yellow]"
+                            )
+                            continue
+
+                        # All charts are exactly 14x8 inches (4200x2400 pixels at 300 DPI)
+                        # Scale to fit page with margins
+                        # Aspect ratio: 14/8 = 1.75 (always wider than tall)
+                        max_width = 7.5 * inch  # Leave margin
+                        chart_aspect_ratio = 14.0 / 8.0  # 1.75
+
+                        # Charts are always wider than tall, so always scale by width
+                        display_width = max_width
+                        display_height = max_width / chart_aspect_ratio
+
+                        # All charts use the same dimensions, so use fixed scaling
+                        img = Image(
+                            chart_path, width=display_width, height=display_height
+                        )
+                        story.append(img)
+                        story.append(Spacer(1, 0.1 * inch))
+                        story.append(PageBreak())
+
+                        # Track file for cleanup after PDF is built
+                        chart_files_to_cleanup.append(chart_path)
+                    except Exception as img_error:
+                        console.print(
+                            f"[yellow]Warning: Could not add chart image {chart_title}: {img_error}[/yellow]"
+                        )
+                        # Try to clean up the file if we couldn't use it
+                        try:
+                            if os.path.exists(chart_path):
+                                os.remove(chart_path)
+                        except Exception:
+                            pass
+                else:
+                    console.print(
+                        f"[yellow]Warning: Chart file not found or not readable: {chart_path}[/yellow]"
+                    )
+            else:
+                console.print(
+                    f"[yellow]Warning: Could not create chart: {chart_title}[/yellow]"
+                )
+        except Exception as chart_error:
+            console.print(
+                f"[yellow]Warning: Error creating chart {chart_title}: {chart_error}[/yellow]"
+            )
+            traceback.print_exc()
+            continue  # Skip this chart and continue with others
+
+    # Build PDF (this is when reportlab actually reads the image files)
+    try:
+        doc.build(story)
+    finally:
+        # Clean up temporary chart files after PDF is built
+        for chart_path in chart_files_to_cleanup:
+            try:
+                if os.path.exists(chart_path):
+                    os.remove(chart_path)
+            except Exception:
+                pass  # Ignore cleanup errors
+
+    return pdf_filename

opik/cli/usage_report/statistics.py

@@ -0,0 +1,78 @@
+"""Statistics calculation functions for usage report module."""
+
+from typing import Any, Dict
+
+
+def calculate_statistics(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Calculate summary statistics from the usage data.
+
+    Args:
+        data: The extracted data dictionary
+
+    Returns:
+        Dictionary containing calculated statistics
+    """
+    stats = {
+        "workspace": data.get("workspace", "Unknown"),
+        "extraction_date": data.get("extraction_date", ""),
+        "date_range": data.get("date_range", {}),
+        "unit": data.get("unit", "month"),
+        "total_projects": len(data.get("projects", [])),
+        "projects_with_data": 0,
+        "total_experiments": 0,
+        "total_datasets": data.get("total_datasets", 0),
+        "total_traces": 0.0,
+        "total_spans": 0.0,
+        "total_tokens": 0.0,
+        "total_cost": 0.0,
+        "periods_with_data": 0,
+    }
+
+    projects = data.get("projects", [])
+    all_periods_set = set()
+
+    for project in projects:
+        if "metrics_by_unit" in project and "error" not in project:
+            stats["projects_with_data"] += 1
+            all_periods_set.update(project["metrics_by_unit"].keys())
+
+            for period_metrics in project["metrics_by_unit"].values():
+                # Trace count
+                trace_count = period_metrics.get("trace_count", 0)
+                if isinstance(trace_count, dict):
+                    trace_count = sum(trace_count.values()) if trace_count else 0
+                stats["total_traces"] += float(trace_count) if trace_count else 0.0
+
+                # Span count
+                span_count = period_metrics.get("span_count", 0)
+                if isinstance(span_count, dict):
+                    span_count = sum(span_count.values()) if span_count else 0
+                stats["total_spans"] += float(span_count) if span_count else 0.0
+
+                # Token count
+                token_count = period_metrics.get("token_count", {})
+                if isinstance(token_count, dict):
+                    if "total_tokens" in token_count:
+                        stats["total_tokens"] += float(token_count["total_tokens"])
+                    else:
+                        stats["total_tokens"] += (
+                            sum(float(v) for v in token_count.values())
+                            if token_count
+                            else 0.0
+                        )
+                else:
+                    stats["total_tokens"] += float(token_count) if token_count else 0.0
+
+                # Cost
+                cost = period_metrics.get("cost", 0)
+                if isinstance(cost, dict):
+                    cost = sum(cost.values()) if cost else 0
+                stats["total_cost"] += float(cost) if cost else 0.0
+
+    # Experiment count
+    experiments_by_unit = data.get("experiments_by_unit", {})
+    stats["total_experiments"] = sum(experiments_by_unit.values())
+    stats["periods_with_data"] = len(all_periods_set)
+
+    return stats

opik/cli/usage_report/utils.py

@@ -0,0 +1,235 @@
+"""Utility functions for usage report module."""
+
+import datetime
+from collections import defaultdict
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+def aggregate_by_unit(metrics_response: Any, unit: str = "month") -> Dict[str, float]:
+    """
+    Aggregate metrics by specified time unit.
+
+    Args:
+        metrics_response: ProjectMetricResponsePublic object from get_project_metrics
+        unit: Time unit for aggregation - "month", "week", "day", or "hour"
+
+    Returns:
+        Dictionary mapping time period key to total value
+    """
+    unit_data: Dict[str, float] = defaultdict(float)
+
+    if metrics_response.results:
+        for result in metrics_response.results:
+            if result.data:
+                for data_point in result.data:
+                    if data_point.value is not None:
+                        # Generate key based on unit
+                        if unit == "month":
+                            key = data_point.time.strftime("%Y-%m")
+                        elif unit == "week":
+                            # ISO week format: YYYY-Www
+                            year, week, _ = data_point.time.isocalendar()
+                            key = f"{year}-W{week:02d}"
+                        elif unit == "day":
+                            key = data_point.time.strftime("%Y-%m-%d")
+                        elif unit == "hour":
+                            key = data_point.time.strftime("%Y-%m-%d-%H")
+                        else:
+                            raise ValueError(f"Unsupported unit: {unit}")
+                        unit_data[key] += data_point.value
+
+    return dict(unit_data)
+
+
+def format_datetime_key(dt: datetime.datetime, unit: str) -> str:
+    """
+    Format a datetime object to a key string based on the specified unit.
+
+    Args:
+        dt: Datetime object to format
+        unit: Time unit - "month", "week", "day", or "hour"
+
+    Returns:
+        Formatted key string
+    """
+    if unit == "month":
+        return dt.strftime("%Y-%m")
+    elif unit == "week":
+        year, week, _ = dt.isocalendar()
+        return f"{year}-W{week:02d}"
+    elif unit == "day":
+        return dt.strftime("%Y-%m-%d")
+    elif unit == "hour":
+        return dt.strftime("%Y-%m-%d-%H")
+    else:
+        raise ValueError(f"Unsupported unit: {unit}")
+
+
+def parse_and_normalize_datetime(
+    dt_str: Any, reference_tz: Optional[datetime.tzinfo]
+) -> Optional[datetime.datetime]:
+    """
+    Parse a datetime string and normalize it with respect to a reference timezone.
+
+    Args:
+        dt_str: Datetime string or datetime object to parse
+        reference_tz: Reference timezone to use for naive datetimes
+
+    Returns:
+        Parsed datetime object, or None if parsing fails
+    """
+    if not dt_str:
+        return None
+
+    try:
+        # If already a datetime object, return it
+        if isinstance(dt_str, datetime.datetime):
+            return dt_str
+
+        # Parse ISO format datetime string
+        if isinstance(dt_str, str):
+            # Handle with or without timezone
+            if "T" in dt_str:
+                if dt_str.endswith("Z"):
+                    dt = datetime.datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
+                elif "+" in dt_str or dt_str.count("-") > 2:
+                    dt = datetime.datetime.fromisoformat(dt_str)
+                else:
+                    # Naive datetime
+                    dt = datetime.datetime.fromisoformat(dt_str)
+                    if reference_tz is not None:
+                        # Make naive date timezone-aware
+                        dt = dt.replace(tzinfo=reference_tz)
+                return dt
+            else:
+                # Not a valid datetime string
+                return None
+        else:
+            return dt_str
+    except (ValueError, TypeError):
+        return None
+
+
+def normalize_timezone_for_comparison(
+    dt: datetime.datetime,
+    query_start_date: datetime.datetime,
+    query_end_date: datetime.datetime,
+) -> Tuple[datetime.datetime, datetime.datetime, datetime.datetime]:
+    """
+    Normalize timezones for date comparison.
+
+    Args:
+        dt: Datetime to normalize
+        query_start_date: Start date for comparison
+        query_end_date: End date for comparison
+
+    Returns:
+        Tuple of (normalized_dt, normalized_start_date, normalized_end_date)
+    """
+    # Handle timezone differences
+    if dt.tzinfo is None and query_start_date.tzinfo is not None:
+        dt = dt.replace(tzinfo=query_start_date.tzinfo)
+        start_date_aware = query_start_date
+        end_date_aware = query_end_date
+    elif dt.tzinfo is not None and query_start_date.tzinfo is None:
+        start_date_aware = query_start_date.replace(tzinfo=dt.tzinfo)
+        end_date_aware = query_end_date.replace(tzinfo=dt.tzinfo)
+    else:
+        start_date_aware = query_start_date
+        end_date_aware = query_end_date
+
+    return dt, start_date_aware, end_date_aware
+
+
+def extract_metric_data(
+    projects: List[Dict[str, Any]],
+    all_periods: List[str],
+    metric_key: str,
+    aggregation_fn: Optional[Callable[[Any], float]] = None,
+) -> List[List[float]]:
+    """
+    Extract metric data from projects for all periods.
+
+    Args:
+        projects: List of project dictionaries with metrics_by_unit
+        all_periods: List of period keys (e.g., "2024-01", "2024-02")
+        metric_key: Key to extract from period_metrics (e.g., "trace_count", "cost")
+        aggregation_fn: Optional function to aggregate metric values.
+                       If None, uses default: sum dict values or use scalar value.
+
+    Returns:
+        List of lists, where each inner list contains metric values for one period
+        across all projects
+    """
+    metric_data = []
+    for period in all_periods:
+        period_values = []
+        for project in projects:
+            period_metrics = project["metrics_by_unit"].get(period, {})
+            metric_value = period_metrics.get(metric_key, 0)
+
+            if aggregation_fn:
+                metric_value = aggregation_fn(metric_value)
+            elif isinstance(metric_value, dict):
+                # Default: sum all dict values
+                metric_value = sum(metric_value.values()) if metric_value else 0
+
+            period_values.append(float(metric_value) if metric_value else 0.0)
+        metric_data.append(period_values)
+
+    return metric_data
+
+
+def process_experiment_for_stats(
+    experiment_dict: Dict[str, Any],
+    experiment_by_unit: Dict[str, int],
+    all_dates: List[datetime.datetime],
+    query_start_date: datetime.datetime,
+    query_end_date: datetime.datetime,
+    unit: str,
+    start_date: Optional[datetime.datetime],
+) -> Tuple[int, int, int]:
+    """
+    Process a single experiment dictionary and update statistics.
+
+    Returns:
+        Tuple of (in_range_count, without_date_count, outside_range_count)
+    """
+    in_range = 0
+    without_date = 0
+    outside_range = 0
+
+    # Extract created_at from raw dict (handles missing fields gracefully)
+    created_at_str = experiment_dict.get("created_at")
+    if created_at_str:
+        # Parse datetime using helper function
+        reference_tz = start_date.tzinfo if start_date else None
+        exp_date = parse_and_normalize_datetime(created_at_str, reference_tz)
+
+        if exp_date is None:
+            without_date = 1
+        else:
+            # Normalize timezones for comparison
+            exp_date, start_date_aware, end_date_aware = (
+                normalize_timezone_for_comparison(
+                    exp_date, query_start_date, query_end_date
+                )
+            )
+
+            # Check if within date range
+            if exp_date.tzinfo is not None:
+                date_check = start_date_aware <= exp_date <= end_date_aware
+            else:
+                date_check = query_start_date <= exp_date <= query_end_date
+
+            if date_check:
+                in_range = 1
+                all_dates.append(exp_date)
+                unit_key = format_datetime_key(exp_date, unit)
+                experiment_by_unit[unit_key] += 1
+            else:
+                outside_range = 1
+    else:
+        without_date = 1
+
+    return (in_range, without_date, outside_range)

opik/config.py

@@ -7,7 +7,6 @@ import pathlib
 import urllib.parse
 from typing import Any, Dict, Final, List, Literal, Optional, Tuple, Type, Union
 
-import opik.decorator.tracing_runtime_config as tracing_runtime_config
 import pydantic
 import pydantic_settings
 from pydantic_settings import BaseSettings, InitSettingsSource
@@ -213,7 +212,7 @@ class OpikConfig(pydantic_settings.BaseSettings):
     Timeout for guardrail.validate calls in seconds. If response takes more than this, it will be considered failed and raises an Exception.
     """
 
-    maximal_queue_size: int = 100_000
+    maximal_queue_size: int = 1_000_000
     """
     Specifies the maximum number of messages that can be queued for delivery when a connection error occurs or rate limiting is in effect.
     """
@@ -228,6 +227,17 @@ class OpikConfig(pydantic_settings.BaseSettings):
     For shorter traces/spans, it is recommended to keep this setting disabled to minimize data logging overhead.
     """
 
+    min_base64_embedded_attachment_size: int = 256_000
+    """
+    Minimum size of the attachment string in bytes that will be kept embedded in the base64 string. (250KB)
+    Attachments larger than this size will be extracted from inputs/outputs of spans/traces and uploaded to the Opik backend.
+    """
+
+    is_attachment_extraction_active: bool = False
+    """
+    If set to True, attachments larger than `min_base64_embedded_attachment_size` will be extracted from spans/traces and uploaded to the Opik backend.
+    """
+
     @property
     def config_file_fullpath(self) -> pathlib.Path:
         config_file_path = os.getenv("OPIK_CONFIG_PATH", CONFIG_FILE_PATH_DEFAULT)
@@ -257,12 +267,8 @@ class OpikConfig(pydantic_settings.BaseSettings):
     def guardrails_backend_host(self) -> str:
         return url_helpers.get_base_url(self.url_override) + "guardrails/"
 
-    @property
-    def runtime(self) -> tracing_runtime_config.TracingRuntimeConfig:
-        return tracing_runtime_config.runtime_cfg
-
     @pydantic.model_validator(mode="after")
-    def _set_url_override_from_api_key(self) -> "OpikConfig":
+    def _set_url_override_from_api_key(self) -> OpikConfig:
         url_was_not_provided = (
             "url_override" not in self.model_fields_set or self.url_override is None
         )

opik/configurator/configure.py

@@ -103,6 +103,8 @@ class OpikConfigurator:
                 self.current_config.config_file_fullpath,
             )
 
+        self._log_project_configuration_message()
+
     def _configure_local(self) -> None:
         """
         Configure the local Opik instance by setting the local URL and workspace.
@@ -119,6 +121,7 @@ class OpikConfigurator:
         # Step 1: If the URL is provided and active, update the configuration
         if url_was_provided and opik_rest_helpers.is_instance_active(self.base_url):
             self._update_config(save_to_file=self.force)
+            self._log_project_configuration_message()
             return
 
         # Step 2: Check if the default local instance is active
@@ -130,6 +133,7 @@ class OpikConfigurator:
                 LOGGER.info(
                     f"Opik is already configured to local instance at {OPIK_BASE_URL_LOCAL}."
                 )
+                self._log_project_configuration_message()
                 return
 
             # Step 3: Ask user if they want to use the found local instance
@@ -149,6 +153,7 @@ class OpikConfigurator:
             if use_url:
                 self.base_url = OPIK_BASE_URL_LOCAL
                 self._update_config()
+                self._log_project_configuration_message()
                 return
 
         # Step 4: Ask user for URL if no valid local instance is found or approved
@@ -158,6 +163,7 @@ class OpikConfigurator:
             )
         self._ask_for_url()
         self._update_config()
+        self._log_project_configuration_message()
 
     def _set_api_key(self) -> bool:
         """
@@ -405,6 +411,17 @@ class OpikConfigurator:
             LOGGER.error(f"Failed to update config: {str(e)}")
             raise ConfigurationError("Failed to update configuration.")
 
+    def _log_project_configuration_message(self) -> None:
+        """
+        Log an informative message about project configuration after successful setup.
+        """
+        project_name = self.current_config.project_name
+
+        LOGGER.info(
+            f"Configuration completed successfully. Traces will be logged to '{project_name}' project. "
+            "To change the destination project, see: https://www.comet.com/docs/opik/tracing/log_traces#configuring-the-project-name"
+        )
+
     def _ask_for_url(self) -> None:
         """
         Prompt the user for an Opik instance URL and check if it is accessible.

opik/datetime_helpers.py

@@ -1,4 +1,5 @@
 import datetime
+from typing import Optional
 
 
 def local_timestamp() -> datetime.datetime:
@@ -8,3 +9,14 @@ def local_timestamp() -> datetime.datetime:
 
 def datetime_to_iso8601(value: datetime.datetime) -> str:
     return value.isoformat()
+
+
+def parse_iso_timestamp(timestamp_str: Optional[str]) -> Optional[datetime.datetime]:
+    """Parse an ISO 8601 timestamp string to datetime."""
+    if timestamp_str is None:
+        return None
+    try:
+        timestamp_str = timestamp_str.replace("Z", "+00:00")
+        return datetime.datetime.fromisoformat(timestamp_str)
+    except (ValueError, TypeError):
+        return None