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

opik/cli/imports/utils.py

@@ -0,0 +1,280 @@
+"""Common utilities for import functionality."""
+
+from typing import Any, Dict, List, Optional
+
+import opik
+from opik.types import FeedbackScoreDict
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def debug_print(message: str, debug: bool) -> None:
+    """Print debug message only if debug is enabled."""
+    if debug:
+        console.print(f"[blue]{message}[/blue]")
+
+
+def matches_name_pattern(name: str, pattern: Optional[str]) -> bool:
+    """Check if a name matches the given pattern using case-insensitive substring matching."""
+    if pattern is None:
+        return True
+    # Simple string matching - check if pattern is contained in name (case-insensitive)
+    return pattern.lower() in name.lower()
+
+
+def translate_trace_id(
+    original_trace_id: str, trace_id_map: Dict[str, str]
+) -> Optional[str]:
+    """Translate an original trace id from export to the newly created id.
+
+    Args:
+        original_trace_id: The original trace ID from the export
+        trace_id_map: Mapping from original trace IDs to new trace IDs (required, can be empty)
+
+    Returns:
+        The new trace ID if found in the map, None otherwise.
+    """
+    return trace_id_map.get(original_trace_id)
+
+
+def find_dataset_item_by_content(
+    dataset: opik.Dataset, expected_content: Dict[str, Any]
+) -> Optional[str]:
+    """Find a dataset item by matching its content.
+
+    Compares all fields in expected_content (excluding 'id') with dataset items.
+    """
+    try:
+        items = dataset.get_items()
+        # Remove 'id' from expected_content for comparison
+        expected_without_id = {k: v for k, v in expected_content.items() if k != "id"}
+
+        for item in items:
+            # Compare all fields (excluding 'id')
+            item_without_id = {k: v for k, v in item.items() if k != "id"}
+            if item_without_id == expected_without_id:
+                return item.get("id")
+    except Exception:
+        pass
+    return None
+
+
+def create_dataset_item(dataset: opik.Dataset, item_data: Dict[str, Any]) -> str:
+    """Create a dataset item and return its ID.
+
+    Uses all fields from item_data (except 'id') to support flexible dataset schemas.
+    """
+    # Use all fields from item_data except 'id' (which is handled separately)
+    new_item = {k: v for k, v in item_data.items() if k != "id" and v is not None}
+
+    # Ensure item is not empty (backend requires non-empty data)
+    if not new_item:
+        raise ValueError(
+            "Dataset item data is empty - at least one field must be provided"
+        )
+
+    dataset.insert([new_item])
+
+    # Find the newly created item by matching all fields
+    items = dataset.get_items()
+    for item in items:
+        # Compare all fields (excluding 'id')
+        item_without_id = {k: v for k, v in item.items() if k != "id"}
+        if item_without_id == new_item:
+            item_id = item.get("id")
+            if item_id is not None:
+                return item_id
+
+    dataset_name = getattr(dataset, "name", None)
+    dataset_info = f", Dataset: {dataset_name!r}" if dataset_name else ""
+    raise Exception(
+        f"Failed to create dataset item. " f"Content: {new_item!r}{dataset_info}"
+    )
+
+
+def handle_trace_reference(item_data: Dict[str, Any]) -> Optional[str]:
+    """Handle trace references from deduplicated exports."""
+    trace_reference = item_data.get("trace_reference")
+    if trace_reference:
+        trace_id = trace_reference.get("trace_id")
+        return trace_id
+
+    # Fall back to direct trace_id
+    return item_data.get("trace_id")
+
+
+def clean_feedback_scores(
+    feedback_scores: Optional[List[Dict[str, Any]]],
+) -> Optional[List[FeedbackScoreDict]]:
+    """Clean feedback scores by removing fields that are not allowed when creating them.
+
+    Exported feedback scores include read-only fields like 'source', 'created_at', etc.
+    that must be removed before importing.
+
+    Allowed fields: name, value, category_name, reason
+    """
+    if not feedback_scores:
+        return None
+
+    cleaned_scores: List[FeedbackScoreDict] = []
+    for score in feedback_scores:
+        if not isinstance(score, dict):
+            continue
+
+        # Only keep allowed fields
+        name = score.get("name")
+        value = score.get("value")
+
+        # Only add if name and value are present
+        if not name or value is None:
+            continue
+
+        # Construct FeedbackScoreDict with required fields
+        cleaned_score: FeedbackScoreDict = {
+            "name": name,
+            "value": value,
+        }
+
+        # Add optional fields if they exist
+        if "category_name" in score:
+            cleaned_score["category_name"] = score.get("category_name")
+        if "reason" in score:
+            cleaned_score["reason"] = score.get("reason")
+
+        cleaned_scores.append(cleaned_score)
+
+    return cleaned_scores if cleaned_scores else None
+
+
+def print_import_summary(stats: Dict[str, int]) -> None:
+    """Print a nice summary table of import statistics."""
+    table = Table(
+        title="📥 Import Summary", show_header=True, header_style="bold magenta"
+    )
+    table.add_column("Type", style="cyan", no_wrap=True)
+    table.add_column("Imported", justify="right", style="green")
+    table.add_column("Skipped", justify="right", style="yellow")
+    table.add_column("Errors", justify="right", style="red")
+
+    # Add rows for each type
+    if (
+        stats.get("experiments", 0) > 0
+        or stats.get("experiments_skipped", 0) > 0
+        or stats.get("experiments_errors", 0) > 0
+    ):
+        imported = stats.get("experiments", 0)
+        skipped = stats.get("experiments_skipped", 0)
+        errors = stats.get("experiments_errors", 0)
+        table.add_row(
+            "🧪 Experiments",
+            str(imported),
+            str(skipped) if skipped > 0 else "",
+            str(errors) if errors > 0 else "",
+        )
+
+    if (
+        stats.get("datasets", 0) > 0
+        or stats.get("datasets_skipped", 0) > 0
+        or stats.get("datasets_errors", 0) > 0
+    ):
+        imported = stats.get("datasets", 0)
+        skipped = stats.get("datasets_skipped", 0)
+        errors = stats.get("datasets_errors", 0)
+        table.add_row(
+            "📊 Datasets",
+            str(imported),
+            str(skipped) if skipped > 0 else "",
+            str(errors) if errors > 0 else "",
+        )
+
+    if (
+        stats.get("traces", 0) > 0
+        or stats.get("traces_skipped", 0) > 0
+        or stats.get("traces_errors", 0) > 0
+    ):
+        imported = stats.get("traces", 0)
+        skipped = stats.get("traces_skipped", 0)
+        errors = stats.get("traces_errors", 0)
+        table.add_row(
+            "🔍 Traces",
+            str(imported),
+            str(skipped) if skipped > 0 else "",
+            str(errors) if errors > 0 else "",
+        )
+
+    if (
+        stats.get("prompts", 0) > 0
+        or stats.get("prompts_skipped", 0) > 0
+        or stats.get("prompts_errors", 0) > 0
+    ):
+        imported = stats.get("prompts", 0)
+        skipped = stats.get("prompts_skipped", 0)
+        errors = stats.get("prompts_errors", 0)
+        table.add_row(
+            "💬 Prompts",
+            str(imported),
+            str(skipped) if skipped > 0 else "",
+            str(errors) if errors > 0 else "",
+        )
+
+    if (
+        stats.get("projects", 0) > 0
+        or stats.get("projects_skipped", 0) > 0
+        or stats.get("projects_errors", 0) > 0
+    ):
+        imported = stats.get("projects", 0)
+        skipped = stats.get("projects_skipped", 0)
+        errors = stats.get("projects_errors", 0)
+        table.add_row(
+            "📁 Projects",
+            str(imported),
+            str(skipped) if skipped > 0 else "",
+            str(errors) if errors > 0 else "",
+        )
+
+    # Calculate totals
+    total_imported = sum(
+        [
+            stats.get(key, 0)
+            for key in ["experiments", "datasets", "traces", "prompts", "projects"]
+        ]
+    )
+    total_skipped = sum(
+        [
+            stats.get(key, 0)
+            for key in [
+                "experiments_skipped",
+                "datasets_skipped",
+                "traces_skipped",
+                "prompts_skipped",
+                "projects_skipped",
+            ]
+        ]
+    )
+    total_errors = sum(
+        [
+            stats.get(key, 0)
+            for key in [
+                "experiments_errors",
+                "datasets_errors",
+                "traces_errors",
+                "prompts_errors",
+                "projects_errors",
+            ]
+        ]
+    )
+
+    table.add_row("", "", "", "", style="bold")
+    table.add_row(
+        "📦 Total",
+        str(total_imported),
+        str(total_skipped) if total_skipped > 0 else "",
+        str(total_errors) if total_errors > 0 else "",
+        style="bold green",
+    )
+
+    console.print()
+    console.print(table)
+    console.print()

opik/cli/main.py

@@ -0,0 +1,49 @@
+"""Main CLI entry point for Opik."""
+
+from importlib import metadata
+from typing import Optional
+
+import click
+
+from . import configure
+from . import exports
+from . import harbor
+from . import healthcheck
+from . import imports
+from . import proxy
+from . import usage_report
+
+__version__: str = "0.0.0+dev"
+try:
+    __version__ = metadata.version("opik")
+except metadata.PackageNotFoundError:
+    pass
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(invoke_without_command=True, context_settings=CONTEXT_SETTINGS)
+@click.version_option(__version__, *("--version", "-v"))
+@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 cli(ctx: click.Context, api_key: Optional[str]) -> None:
+    """
+    CLI tool for Opik.
+    """
+    # Store API key in context for subcommands to access
+    ctx.ensure_object(dict)
+    ctx.obj["api_key"] = api_key
+
+
+# Register all commands
+cli.add_command(configure.configure)
+cli.add_command(proxy.proxy)
+cli.add_command(healthcheck.healthcheck)
+cli.add_command(exports.export_group)
+cli.add_command(imports.import_group)
+cli.add_command(usage_report.usage_report)
+cli.add_command(harbor.harbor)

opik/cli/proxy.py

@@ -0,0 +1,93 @@
+"""Proxy command for Opik CLI."""
+
+import sys
+
+import click
+
+
+@click.command(context_settings={"ignore_unknown_options": True})
+@click.option(
+    "--ollama",
+    is_flag=True,
+    help="Run as a proxy server for Ollama",
+)
+@click.option(
+    "--ollama-host",
+    default="http://localhost:11434",
+    help="Ollama server URL when using --ollama-proxy",
+    show_default=True,
+)
+@click.option(
+    "--lm-studio",
+    is_flag=True,
+    help="Run as a proxy server for LM Studio",
+)
+@click.option(
+    "--lm-studio-host",
+    default="http://localhost:1234",
+    help="LM Studio server URL when using --lm-studio-proxy",
+    show_default=True,
+)
+@click.option(
+    "--host",
+    default="localhost",
+    help="Host to bind to",
+    show_default=True,
+)
+@click.option(
+    "--port",
+    default=7860,
+    help="Port to bind to",
+    show_default=True,
+)
+def proxy(
+    ollama: bool,
+    ollama_host: str,
+    lm_studio: bool,
+    lm_studio_host: str,
+    host: str,
+    port: int,
+) -> None:
+    """Start the Opik server."""
+    try:
+        import fastapi  # noqa
+        import uvicorn  # noqa
+        import httpx  # noqa
+        import rich  # noqa
+    except ImportError:
+        raise click.ClickException(
+            "Proxy server dependencies not found. Please install them with: pip install opik[proxy]"
+        )
+
+    if not ollama and not lm_studio:
+        click.echo(
+            "Error: Either --ollama or --lm-studio must be specified",
+            err=True,
+        )
+        sys.exit(1)
+
+    if ollama and lm_studio:
+        click.echo("Error: Cannot specify both --ollama and --lm-studio", err=True)
+        sys.exit(1)
+
+    if ollama:
+        llm_server_host = ollama_host
+        llm_server_type = "Ollama"
+    else:  # lm_studio_proxy
+        llm_server_host = lm_studio_host
+        llm_server_type = "LM Studio"
+
+    from opik.forwarding_server.app import create_app
+    from opik.forwarding_server.utils import print_server_startup_message
+    import uvicorn
+
+    app = create_app(llm_server_host)
+    print_server_startup_message(
+        host=host,
+        port=port,
+        llm_server_type=llm_server_type,
+        llm_server_host=llm_server_host,
+    )
+    uvicorn.run(
+        app, host=host, port=port, log_level="error"
+    )  # Reduce uvicorn logging to keep output clean

opik/cli/usage_report/__init__.py

@@ -0,0 +1,16 @@
+"""Usage report module for Opik CLI."""
+
+from .cli import usage_report
+from .extraction import extract_project_data
+from .charts import create_charts, create_individual_chart
+from .statistics import calculate_statistics
+from .pdf import create_pdf_report
+
+__all__ = [
+    "usage_report",
+    "extract_project_data",
+    "create_charts",
+    "create_individual_chart",
+    "calculate_statistics",
+    "create_pdf_report",
+]