claudetracing 0.1.0__py3-none-any.whl

claudetracing/__init__.py

@@ -0,0 +1,30 @@
+"""Claude Code Tracing - MLflow tracing for Claude Code sessions."""
+
+from .client import TracingClient
+from .formatters import (
+    format_for_context,
+    format_tool_usage,
+    format_traces_json,
+    format_traces_summary,
+    to_json,
+    to_summary,
+)
+from .models import SpanInfo, TraceData, TraceInfo, TraceSummary
+from .setup import load_settings
+
+__all__ = [
+    "TracingClient",
+    "load_settings",
+    "TraceData",
+    "TraceInfo",
+    "TraceSummary",
+    "SpanInfo",
+    "to_summary",
+    "to_json",
+    "format_traces_summary",
+    "format_traces_json",
+    "format_for_context",
+    "format_tool_usage",
+]
+
+__version__ = "0.1.0"

claudetracing/cli.py

@@ -0,0 +1,93 @@
+"""CLI entry point for trace retrieval."""
+
+from datetime import datetime
+from typing import Optional
+
+import typer
+
+from .client import TracingClient
+from .formatters import (
+    format_for_context,
+    format_tool_usage,
+    format_traces_json,
+    format_traces_summary,
+)
+from .setup import load_settings
+
+app = typer.Typer(help="Claude Code MLflow tracing CLI")
+
+
+@app.command()
+def init():
+    """Initialize Claude Code tracing in the current project."""
+    from .setup import run_setup
+
+    raise SystemExit(run_setup())
+
+
+@app.command()
+def search(
+    experiment: Optional[str] = typer.Option(
+        None, "-e", "--experiment", help="Experiment name"
+    ),
+    limit: int = typer.Option(10, "-l", "--limit", help="Max traces to return"),
+    hours: Optional[int] = typer.Option(None, help="Search last N hours"),
+    since: Optional[str] = typer.Option(
+        None, help="Search since datetime (ISO format)"
+    ),
+    format: str = typer.Option(
+        "summary", "-f", "--format", help="Output: summary|json|context|tools"
+    ),
+    trace_id: Optional[str] = typer.Option(
+        None, "--trace-id", help="Get specific trace by ID"
+    ),
+):
+    """Search and retrieve traces."""
+    load_settings()  # Load .claude/settings.json env vars
+    client = TracingClient()
+
+    if trace_id:
+        trace = client.get_trace(trace_id)
+        if not trace:
+            typer.echo(f"Trace not found: {trace_id}", err=True)
+            raise typer.Exit(1)
+        traces = [trace]
+    elif hours or since:
+        since_dt = datetime.fromisoformat(since) if since else None
+        traces = client.search_traces_by_time(
+            experiment_name=experiment, hours=hours, since=since_dt, max_results=limit
+        )
+    else:
+        traces = client.search_traces(experiment_name=experiment, max_results=limit)
+
+    output = {
+        "json": format_traces_json,
+        "context": format_for_context,
+        "tools": format_tool_usage,
+    }.get(format, format_traces_summary)(traces)
+
+    typer.echo(output)
+
+
+@app.command("list")
+def list_experiments():
+    """List available experiments."""
+    load_settings()  # Load .claude/settings.json env vars
+    client = TracingClient()
+    experiments = client.list_experiments()
+
+    if not experiments:
+        typer.echo("No experiments found.")
+        return
+
+    typer.echo("Available experiments:")
+    for exp in experiments:
+        typer.echo(f"  [{exp['id']}] {exp['name']}")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

claudetracing/client.py

@@ -0,0 +1,184 @@
+"""MLFlow tracing client wrapper."""
+
+from datetime import datetime, timedelta
+
+import mlflow
+from mlflow import MlflowClient
+from mlflow.entities import Trace
+
+from .models import SpanInfo, TraceData, TraceInfo
+
+
+class TracingClient:
+    """Client for retrieving MLFlow traces from Claude Code sessions."""
+
+    def __init__(self, tracking_uri: str | None = None):
+        """Initialize the tracing client.
+
+        Args:
+            tracking_uri: MLFlow tracking URI. If None, uses MLFLOW_TRACKING_URI env var.
+        """
+        if tracking_uri:
+            mlflow.set_tracking_uri(tracking_uri)
+        self._client = MlflowClient()
+
+    def list_experiments(self) -> list[dict]:
+        """List all available experiments.
+
+        Returns:
+            List of experiment info dicts with id, name, and artifact_location.
+        """
+        experiments = self._client.search_experiments()
+        return [
+            {
+                "id": exp.experiment_id,
+                "name": exp.name,
+                "artifact_location": exp.artifact_location,
+            }
+            for exp in experiments
+        ]
+
+    def get_experiment_id(self, experiment_name: str) -> str | None:
+        """Get experiment ID by name.
+
+        Args:
+            experiment_name: Name of the experiment.
+
+        Returns:
+            Experiment ID or None if not found.
+        """
+        exp = self._client.get_experiment_by_name(experiment_name)
+        return exp.experiment_id if exp else None
+
+    def search_traces(
+        self,
+        experiment_name: str | None = None,
+        experiment_id: str | None = None,
+        filter_string: str | None = None,
+        max_results: int = 100,
+        order_by: list[str] | None = None,
+    ) -> list[TraceData]:
+        """Search for traces in an experiment.
+
+        Args:
+            experiment_name: Name of the experiment to search.
+            experiment_id: ID of the experiment (alternative to name).
+            filter_string: MLFlow filter string for traces.
+            max_results: Maximum number of traces to return.
+            order_by: List of fields to order by (e.g., ["timestamp DESC"]).
+
+        Returns:
+            List of TraceData objects.
+        """
+        if experiment_name and not experiment_id:
+            experiment_id = self.get_experiment_id(experiment_name)
+            if not experiment_id:
+                return []
+
+        locations = [experiment_id] if experiment_id else None
+
+        traces = mlflow.search_traces(
+            locations=locations,
+            filter_string=filter_string,
+            max_results=max_results,
+            order_by=order_by or ["timestamp DESC"],
+            return_type="list",
+        )
+
+        return [self._convert_trace(t) for t in traces]
+
+    def search_traces_by_time(
+        self,
+        experiment_name: str | None = None,
+        hours: int | None = None,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        max_results: int = 100,
+    ) -> list[TraceData]:
+        """Search for traces within a time range.
+
+        Args:
+            experiment_name: Name of the experiment.
+            hours: Number of hours back from now to search.
+            since: Start datetime for the search range.
+            until: End datetime for the search range.
+            max_results: Maximum number of traces to return.
+
+        Returns:
+            List of TraceData objects within the time range.
+        """
+        if hours:
+            since = datetime.now() - timedelta(hours=hours)
+
+        filter_parts = []
+        if since:
+            # MLFlow uses milliseconds for timestamp filters
+            since_ms = int(since.timestamp() * 1000)
+            filter_parts.append(f"timestamp >= {since_ms}")
+        if until:
+            until_ms = int(until.timestamp() * 1000)
+            filter_parts.append(f"timestamp <= {until_ms}")
+
+        filter_string = " AND ".join(filter_parts) if filter_parts else None
+
+        return self.search_traces(
+            experiment_name=experiment_name,
+            filter_string=filter_string,
+            max_results=max_results,
+        )
+
+    def get_trace(self, trace_id: str) -> TraceData | None:
+        """Get a single trace by ID.
+
+        Args:
+            trace_id: The trace ID to retrieve.
+
+        Returns:
+            TraceData object or None if not found.
+        """
+        trace = self._client.get_trace(trace_id)
+        return self._convert_trace(trace) if trace else None
+
+    def _convert_trace(self, trace: Trace) -> TraceData:
+        """Convert MLFlow Trace to TraceData model.
+
+        Args:
+            trace: MLFlow Trace entity.
+
+        Returns:
+            TraceData model instance.
+        """
+        info = TraceInfo(
+            trace_id=trace.info.request_id,
+            request_id=trace.info.request_id,
+            experiment_id=trace.info.experiment_id,
+            timestamp=datetime.fromtimestamp(trace.info.timestamp_ms / 1000)
+            if trace.info.timestamp_ms
+            else None,
+            execution_time_ms=trace.info.execution_time_ms,
+            status=str(trace.info.status) if trace.info.status else None,
+            tags=dict(trace.info.tags) if trace.info.tags else {},
+        )
+
+        spans = []
+        if trace.data and trace.data.spans:
+            for span in trace.data.spans:
+                spans.append(
+                    SpanInfo(
+                        span_id=span.span_id,
+                        name=span.name,
+                        parent_id=span.parent_id,
+                        start_time=datetime.fromtimestamp(span.start_time_ns / 1e9)
+                        if span.start_time_ns
+                        else None,
+                        end_time=datetime.fromtimestamp(span.end_time_ns / 1e9)
+                        if span.end_time_ns
+                        else None,
+                        status=str(span.status) if span.status else None,
+                        inputs=dict(span.inputs) if span.inputs else {},
+                        outputs=dict(span.outputs) if span.outputs else {},
+                        attributes=dict(span.attributes) if span.attributes else {},
+                    )
+                )
+
+        return TraceData(info=info, spans=spans)

claudetracing/formatters.py

@@ -0,0 +1,167 @@
+"""Output formatters for trace data."""
+
+import json
+from typing import Any
+
+from .models import TraceData, TraceSummary
+
+
+def to_summary(trace: TraceData) -> str:
+    """Format a trace as a human-readable summary string.
+
+    Args:
+        trace: TraceData object to format.
+
+    Returns:
+        Formatted summary string.
+    """
+    summary = trace.to_summary()
+    lines = [
+        f"Trace: {summary.trace_id}",
+        f"  Time: {summary.timestamp.isoformat() if summary.timestamp else 'N/A'}",
+        f"  Status: {summary.status or 'N/A'}",
+        f"  Duration: {summary.duration_ms:.0f}ms"
+        if summary.duration_ms
+        else "  Duration: N/A",
+        f"  Spans: {summary.total_spans}",
+    ]
+
+    if summary.root_span_name:
+        lines.append(f"  Root: {summary.root_span_name}")
+
+    if summary.tool_calls:
+        lines.append(f"  Tools: {', '.join(summary.tool_calls)}")
+
+    if summary.error_message:
+        lines.append(f"  Error: {summary.error_message}")
+
+    return "\n".join(lines)
+
+
+def to_json(trace: TraceData) -> dict[str, Any]:
+    """Convert trace to full JSON-serializable dict.
+
+    Args:
+        trace: TraceData object to convert.
+
+    Returns:
+        Dictionary representation of the trace.
+    """
+    return trace.model_dump(mode="json")
+
+
+def format_traces_summary(traces: list[TraceData]) -> str:
+    """Format multiple traces as summaries.
+
+    Args:
+        traces: List of TraceData objects.
+
+    Returns:
+        Formatted string with all trace summaries.
+    """
+    if not traces:
+        return "No traces found."
+
+    parts = [f"Found {len(traces)} trace(s):\n"]
+    for i, trace in enumerate(traces, 1):
+        parts.append(f"\n--- Trace {i} ---")
+        parts.append(to_summary(trace))
+
+    return "\n".join(parts)
+
+
+def format_traces_json(traces: list[TraceData]) -> str:
+    """Format multiple traces as JSON.
+
+    Args:
+        traces: List of TraceData objects.
+
+    Returns:
+        JSON string of all traces.
+    """
+    return json.dumps([to_json(t) for t in traces], indent=2, default=str)
+
+
+def format_for_context(traces: list[TraceData], max_chars: int = 50000) -> str:
+    """Format traces optimized for Claude's context window.
+
+    Provides a condensed format that maximizes information density
+    while staying within token limits.
+
+    Args:
+        traces: List of TraceData objects.
+        max_chars: Maximum characters to output (rough token proxy).
+
+    Returns:
+        Formatted string optimized for LLM context.
+    """
+    if not traces:
+        return "No traces found."
+
+    output_parts = [f"# Previous Session Traces ({len(traces)} total)\n"]
+    current_length = len(output_parts[0])
+
+    for trace in traces:
+        summary = trace.to_summary()
+
+        # Build compact trace entry
+        entry_lines = [
+            f"\n## {summary.timestamp.strftime('%Y-%m-%d %H:%M') if summary.timestamp else 'Unknown time'}",
+            f"ID: {summary.trace_id[:12]}...",
+            f"Status: {summary.status or 'N/A'} | Duration: {summary.duration_ms:.0f}ms"
+            if summary.duration_ms
+            else f"Status: {summary.status or 'N/A'}",
+        ]
+
+        if summary.tool_calls:
+            entry_lines.append(f"Tools: {', '.join(summary.tool_calls[:10])}")
+            if len(summary.tool_calls) > 10:
+                entry_lines[-1] += f" (+{len(summary.tool_calls) - 10} more)"
+
+        # Add root span inputs/outputs if available
+        root = trace.get_root_span()
+        if root and root.inputs:
+            # Truncate inputs for context
+            inputs_str = str(root.inputs)[:500]
+            if len(str(root.inputs)) > 500:
+                inputs_str += "..."
+            entry_lines.append(f"Input: {inputs_str}")
+
+        entry = "\n".join(entry_lines)
+
+        # Check if we'd exceed max chars
+        if current_length + len(entry) > max_chars:
+            output_parts.append(
+                f"\n... ({len(traces) - len(output_parts) + 1} more traces truncated)"
+            )
+            break
+
+        output_parts.append(entry)
+        current_length += len(entry)
+
+    return "\n".join(output_parts)
+
+
+def format_tool_usage(traces: list[TraceData]) -> str:
+    """Format a summary of tool usage across traces.
+
+    Args:
+        traces: List of TraceData objects.
+
+    Returns:
+        Formatted string showing tool usage statistics.
+    """
+    tool_counts: dict[str, int] = {}
+
+    for trace in traces:
+        for tool in trace.get_tool_calls():
+            tool_counts[tool] = tool_counts.get(tool, 0) + 1
+
+    if not tool_counts:
+        return "No tool usage found in traces."
+
+    lines = ["Tool Usage Summary:", "-" * 30]
+    for tool, count in sorted(tool_counts.items(), key=lambda x: -x[1]):
+        lines.append(f"  {tool}: {count}")
+
+    return "\n".join(lines)

claudetracing/models.py

@@ -0,0 +1,87 @@
+"""Pydantic models for MLFlow trace data."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SpanInfo(BaseModel):
+    """Information about a single span within a trace."""
+
+    span_id: str
+    name: str
+    parent_id: str | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+    status: str | None = None
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    outputs: dict[str, Any] = Field(default_factory=dict)
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def duration_ms(self) -> float | None:
+        """Calculate span duration in milliseconds."""
+        if self.start_time and self.end_time:
+            return (self.end_time - self.start_time).total_seconds() * 1000
+        return None
+
+
+class TraceInfo(BaseModel):
+    """Metadata about a trace."""
+
+    trace_id: str
+    request_id: str | None = None
+    experiment_id: str | None = None
+    timestamp: datetime | None = None
+    execution_time_ms: float | None = None
+    status: str | None = None
+    tags: dict[str, str] = Field(default_factory=dict)
+
+
+class TraceSummary(BaseModel):
+    """Condensed summary of a trace for quick overview."""
+
+    trace_id: str
+    timestamp: datetime | None = None
+    status: str | None = None
+    total_spans: int = 0
+    duration_ms: float | None = None
+    root_span_name: str | None = None
+    tool_calls: list[str] = Field(default_factory=list)
+    error_message: str | None = None
+
+
+class TraceData(BaseModel):
+    """Complete trace data including info and spans."""
+
+    info: TraceInfo
+    spans: list[SpanInfo] = Field(default_factory=list)
+
+    def get_root_span(self) -> SpanInfo | None:
+        """Get the root span (span with no parent)."""
+        for span in self.spans:
+            if span.parent_id is None:
+                return span
+        return None
+
+    def get_tool_calls(self) -> list[str]:
+        """Extract names of tool call spans."""
+        return [
+            span.name
+            for span in self.spans
+            if "tool" in span.name.lower() or span.attributes.get("span_type") == "tool"
+        ]
+
+    def to_summary(self) -> TraceSummary:
+        """Convert to a condensed summary."""
+        root = self.get_root_span()
+        return TraceSummary(
+            trace_id=self.info.trace_id,
+            timestamp=self.info.timestamp,
+            status=self.info.status,
+            total_spans=len(self.spans),
+            duration_ms=self.info.execution_time_ms,
+            root_span_name=root.name if root else None,
+            tool_calls=self.get_tool_calls(),
+        )

claudetracing/setup.py

@@ -0,0 +1,339 @@
+"""Interactive setup for Claude Code tracing."""
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+
+def load_settings() -> dict | None:
+    """Load settings from .claude/settings.json and set environment variables.
+
+    Returns:
+        The settings dict, or None if not found.
+    """
+    settings_path = Path.cwd() / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return None
+
+    settings = json.loads(settings_path.read_text())
+
+    # Set environment variables from settings
+    if "environment" in settings:
+        for key, value in settings["environment"].items():
+            os.environ[key] = value
+
+    return settings
+
+
+def prompt(message: str, default: str | None = None) -> str:
+    """Prompt user for input with optional default."""
+    suffix = f" [{default}]: " if default else ": "
+    result = input(f"{message}{suffix}").strip()
+    return result if result else (default or prompt(message, default))
+
+
+def prompt_choice(message: str, choices: list[str], default: int = 0) -> int:
+    """Prompt user to choose from a list. Returns index."""
+    print(message)
+    for i, choice in enumerate(choices):
+        marker = "*" if i == default else " "
+        print(f"  {marker} [{i + 1}] {choice}")
+
+    result = input(f"Choice [1-{len(choices)}] (default: {default + 1}): ").strip()
+    if not result:
+        return default
+    try:
+        idx = int(result) - 1
+        return idx if 0 <= idx < len(choices) else default
+    except ValueError:
+        return default
+
+
+def get_databricks_profiles() -> list[dict]:
+    """Get list of configured Databricks profiles from ~/.databrickscfg."""
+    config_path = Path.home() / ".databrickscfg"
+    if not config_path.exists():
+        return []
+
+    profiles = []
+    current_profile = None
+    current_host = None
+
+    for line in config_path.read_text().splitlines():
+        line = line.strip()
+        if line.startswith("[") and line.endswith("]"):
+            if current_profile:
+                profiles.append({"name": current_profile, "host": current_host})
+            current_profile = line[1:-1]
+            current_host = None
+        elif line.startswith("host"):
+            current_host = line.split("=", 1)[1].strip()
+
+    if current_profile:
+        profiles.append({"name": current_profile, "host": current_host})
+
+    return profiles
+
+
+def get_databricks_user(profile: str) -> str | None:
+    """Get current user's email from Databricks."""
+    try:
+        result = subprocess.run(
+            ["databricks", "current-user", "me", "--profile", profile, "-o", "json"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        data = json.loads(result.stdout)
+        return data.get("userName") or data.get("user_name")
+    except Exception:
+        return None
+
+
+def create_settings_file(
+    profile: str | None, experiment_path: str, project_root: Path
+) -> Path:
+    """Create or update .claude/settings.json file.
+
+    Merges tracing config into existing settings, preserving other hooks and env vars.
+
+    Args:
+        profile: Databricks profile name, or None for local storage
+        experiment_path: MLflow experiment path/name
+        project_root: Project root directory
+
+    Returns:
+        Path to the settings file
+    """
+    claude_dir = project_root / ".claude"
+    claude_dir.mkdir(exist_ok=True)
+    settings_path = claude_dir / "settings.json"
+
+    # Tracing-specific config
+    tracing_hook = {
+        "type": "command",
+        "command": 'uv run python -c "from mlflow.claude_code.hooks import stop_hook_handler; stop_hook_handler()"',
+    }
+
+    # Environment config depends on local vs Databricks
+    if profile:
+        tracing_env = {
+            "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
+            "MLFLOW_TRACKING_URI": f"databricks://{profile}",
+            "MLFLOW_EXPERIMENT_NAME": experiment_path,
+            "DATABRICKS_CONFIG_PROFILE": profile,
+        }
+    else:
+        tracing_env = {
+            "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
+            "MLFLOW_EXPERIMENT_NAME": experiment_path,
+        }
+
+    # Load existing settings or start fresh
+    if settings_path.exists():
+        existing = json.loads(settings_path.read_text())
+        print(f"Found existing settings.json, merging tracing config...")
+    else:
+        existing = {}
+
+    # Merge environment variables (tracing vars override existing)
+    if "environment" not in existing:
+        existing["environment"] = {}
+    existing["environment"].update(tracing_env)
+
+    # Merge Stop hooks (append tracing hook to existing hooks)
+    if "hooks" not in existing:
+        existing["hooks"] = {}
+    if "Stop" not in existing["hooks"]:
+        existing["hooks"]["Stop"] = []
+
+    # Check if tracing hook already exists anywhere in Stop hooks
+    hook_command = tracing_hook["command"]
+    hook_exists = any(
+        hook.get("command") == hook_command
+        or any(h.get("command") == hook_command for h in hook.get("hooks", []))
+        for hook in existing["hooks"]["Stop"]
+    )
+
+    if not hook_exists:
+        # Append to existing Stop block, or create new one if empty
+        if existing["hooks"]["Stop"] and "hooks" in existing["hooks"]["Stop"][0]:
+            existing["hooks"]["Stop"][0]["hooks"].append(tracing_hook)
+        else:
+            existing["hooks"]["Stop"] = [{"hooks": [tracing_hook]}]
+
+    settings_path.write_text(json.dumps(existing, indent=2))
+    return settings_path
+
+
+def update_gitignore(project_root: Path) -> None:
+    """Add Claude Code entries to .gitignore.
+
+    Args:
+        project_root: Project root directory
+    """
+    gitignore = project_root / ".gitignore"
+    entries = [".claude/settings.local.json", ".claude/mlflow/", "mlruns/"]
+    existing = gitignore.read_text() if gitignore.exists() else ""
+
+    to_add = [e for e in entries if e not in existing]
+    if to_add:
+        with open(gitignore, "a") as f:
+            f.write("\n# Claude Code Tracing\n" + "\n".join(to_add) + "\n")
+
+
+def verify_connection(profile: str, experiment_path: str) -> bool:
+    """Verify MLflow connection to Databricks.
+
+    Args:
+        profile: Databricks profile name
+        experiment_path: MLflow experiment path
+
+    Returns:
+        True if connection succeeded
+    """
+    try:
+        import mlflow
+
+        os.environ["DATABRICKS_CONFIG_PROFILE"] = profile
+        mlflow.set_tracking_uri(f"databricks://{profile}")
+        mlflow.get_experiment_by_name(experiment_path)  # type: ignore[possibly-missing-attribute]
+        return True
+    except Exception:
+        return False
+
+
+def run_setup() -> int:
+    """Run the interactive setup process."""
+    print("\n=== Claude Code Tracing Setup ===\n")
+
+    # Choose storage backend
+    storage_type = prompt_choice(
+        "Where should traces be stored?",
+        [
+            "Local (mlruns/ folder - no setup required)",
+            "Databricks (requires workspace access)",
+        ],
+    )
+
+    if storage_type == 0:
+        return setup_local()
+    return setup_databricks()
+
+
+def setup_local() -> int:
+    """Setup local MLflow storage."""
+    project_root = Path.cwd()
+    project_name = project_root.name
+
+    exp_name = prompt("Experiment name", default=project_name)
+
+    settings_path = create_settings_file(
+        profile=None,
+        experiment_path=exp_name,
+        project_root=project_root,
+    )
+    print(f"Created {settings_path.relative_to(project_root)}")
+
+    update_gitignore(project_root)
+    print("Updated .gitignore")
+
+    print(f"\nSetup complete! Restart Claude Code to enable tracing.")
+    print(f"Traces will be stored locally in: mlruns/")
+    return 0
+
+
+def setup_databricks() -> int:
+    """Setup Databricks MLflow storage."""
+    # Check databricks CLI
+    try:
+        subprocess.run(["databricks", "--version"], capture_output=True, check=True)
+    except Exception:
+        print("Error: Databricks CLI not found. Install with: brew install databricks")
+        return 1
+
+    # Get or create profile
+    profiles = get_databricks_profiles()
+
+    if profiles:
+        choices = [f"{p['name']} ({p['host']})" for p in profiles] + [
+            "Add new workspace"
+        ]
+        idx = prompt_choice("Select Databricks profile:", choices)
+
+        if idx < len(profiles):
+            profile = profiles[idx]["name"]
+            user = get_databricks_user(profile)
+        else:
+            workspace = prompt(
+                "Databricks workspace URL (e.g., https://dbc-xxx.cloud.databricks.com)"
+            )
+            if not workspace.startswith("https://"):
+                workspace = f"https://{workspace}"
+            subprocess.run(
+                ["databricks", "auth", "login", "--host", workspace], check=True
+            )
+            profile = workspace.replace("https://", "").split(".")[0]
+            user = get_databricks_user(profile)
+    else:
+        workspace = prompt(
+            "Databricks workspace URL (e.g., https://dbc-xxx.cloud.databricks.com)"
+        )
+        if not workspace.startswith("https://"):
+            workspace = f"https://{workspace}"
+        subprocess.run(["databricks", "auth", "login", "--host", workspace], check=True)
+        profile = workspace.replace("https://", "").split(".")[0]
+        user = get_databricks_user(profile)
+
+    if user:
+        print(f"Authenticated as: {user}")
+
+    # Configure experiment location
+    print("\nMLflow experiments are stored in Databricks Workspace folders.")
+    exp_type = prompt_choice(
+        "Experiment location:",
+        [
+            "Shared folder - visible to all workspace users (recommended)",
+            f"Personal folder - only visible to you ({user or 'your account'})",
+        ],
+    )
+    project_name = Path.cwd().name
+    exp_name = prompt("Experiment name", default=project_name)
+
+    if exp_type == 0:
+        experiment_path = f"/Workspace/Shared/{exp_name}"
+    else:
+        if not user:
+            user = prompt("Databricks email (for personal folder path)")
+        experiment_path = f"/Workspace/Users/{user}/{exp_name}"
+
+    # Verify connection BEFORE creating config
+    print(f"\nVerifying connection to Databricks...")
+    if not verify_connection(profile, experiment_path):
+        print("\n" + "=" * 50)
+        print("ERROR: Could not connect to Databricks!")
+        print("=" * 50)
+        print(f"\nProfile '{profile}' failed to authenticate.")
+        print("This usually means:")
+        print("  - Your token/OAuth session has expired")
+        print("  - The profile doesn't have valid credentials")
+        print("\nTo fix, re-authenticate with:")
+        print(f"  databricks auth login --profile {profile}")
+        print("\nThen run 'traces init' again.")
+        return 1
+
+    print("Connection verified!")
+
+    # Create settings.json
+    project_root = Path.cwd()
+    settings_path = create_settings_file(profile, experiment_path, project_root)
+    print(f"Created {settings_path.relative_to(project_root)}")
+
+    # Update .gitignore
+    update_gitignore(project_root)
+    print("Updated .gitignore")
+
+    print(f"\nSetup complete! Restart Claude Code to enable tracing.")
+    print(f"Traces will be sent to: {experiment_path}")
+    return 0

claudetracing-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: claudetracing
+Version: 0.1.0
+Summary: MLflow tracing for Claude Code sessions with Databricks integration
+Project-URL: Homepage, https://github.com/CauchyIO/claudetracing
+Project-URL: Repository, https://github.com/CauchyIO/claudetracing
+Project-URL: Issues, https://github.com/CauchyIO/claudetracing/issues
+Author: Casper
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,databricks,llm,mlflow,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mlflow[databricks]>=3.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ty>=0.0.8
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# Claude Code MLflow Tracing
+
+[![PyPI version](https://img.shields.io/pypi/v/claudetracing.svg)](https://pypi.org/project/claudetracing/)
+[![Python versions](https://img.shields.io/pypi/pyversions/claudetracing.svg)](https://pypi.org/project/claudetracing/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MLflow tracing for Claude Code sessions with Databricks integration. Automatically captures conversations, tool usage, and session metadata.
+
+## Why Trace Claude Code Sessions?
+
+When Claude Code becomes part of your development workflow, visibility into how it's being used becomes valuable:
+
+- **Review past sessions** - What did Claude do while you were away? Search and replay any session to understand decisions made.
+- **Team insights** - See how your team uses Claude Code across projects. Identify patterns, common tasks, and areas for improvement.
+- **Debug failures** - When something goes wrong, trace data shows exactly which tools were called, in what order, and what inputs/outputs were involved.
+- **Cost awareness** - Track token usage and session duration to understand resource consumption.
+- **Compliance & audit** - Maintain records of AI-assisted code changes for regulated environments.
+
+## Prerequisites
+
+- Python 3.10+
+- [Databricks CLI](https://docs.databricks.com/dev-tools/cli/index.html) installed
+- Access to a Databricks workspace
+
+## Installation
+
+```bash
+uv add claudetracing
+```
+
+Or with pip:
+```bash
+pip install claudetracing
+```
+
+## Quick Start
+
+Run the interactive setup in your project directory:
+
+```bash
+traces init
+```
+
+This will:
+1. Authenticate with Databricks (or use existing credentials)
+2. Configure your experiment path (shared or personal)
+3. Create `.claude/settings.json` with the proper hooks
+4. Update `.gitignore`
+
+Restart Claude Code after setup. Traces are automatically sent to Databricks when sessions end.
+
+## CLI Commands
+
+```bash
+traces init                      # Interactive setup
+traces list                      # List available experiments
+traces search                    # Search recent traces
+traces search -e <experiment>    # Filter by experiment name
+traces search --hours 24         # Last 24 hours
+traces search --trace-id <id>    # Get specific trace
+traces search -f json            # Output as JSON
+traces search -f context         # LLM-optimized format
+```
+
+## Python API
+
+```python
+from claudetracing import TracingClient
+
+client = TracingClient()
+
+# List experiments
+experiments = client.list_experiments()
+
+# Search traces
+traces = client.search_traces(experiment_name="my-experiment", max_results=10)
+
+# Search by time
+traces = client.search_traces_by_time(hours=24)
+
+# Get specific trace
+trace = client.get_trace("trace-id")
+
+# Access trace data
+for trace in traces:
+    print(f"Session: {trace.info.trace_id}")
+    print(f"Tools used: {trace.get_tool_calls()}")
+    for span in trace.spans:
+        print(f"  {span.name}: {span.execution_time_ms}ms")
+```
+
+## What Gets Traced
+
+- User prompts and Claude responses
+- Tool usage (Read, Write, Edit, Bash, etc.)
+- Execution timing per operation
+- Session metadata (user, working directory, git branch)
+
+## How It Works
+
+1. The `traces init` command creates a `.claude/settings.json` file
+2. This configures a Stop hook that runs when Claude Code sessions end
+3. The hook calls MLflow's built-in Claude Code tracing to capture the session
+4. Traces are uploaded to your Databricks MLflow experiment
+
+## License
+
+MIT
+
+---
+
+Built with [Claude Opus 4.5](https://www.anthropic.com/claude)

claudetracing-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+claudetracing/__init__.py,sha256=CjBmo0uEWLq4I2JX7ZoYRFjErCO38d080EFmhmskRf0,646
+claudetracing/cli.py,sha256=10ssYckGb9l_eY1rRKkMFjvM9-5j5jqh_Ftfbp5uKd4,2514
+claudetracing/client.py,sha256=YAmJEs6uMSwXZ9ian_Ncy0rZ0ZzBqfM8kCX55TeLGFE,6267
+claudetracing/formatters.py,sha256=T1xaa3Kpk6wGEMQPILwxmDDdPADPll6dgrNgjv9OjwQ,4795
+claudetracing/models.py,sha256=ZmFAo9P1qlHqkkhxyvmfT4TrEa6BZU_bBmaocPgGj0g,2651
+claudetracing/setup.py,sha256=v6V3iZaTLDCuIhkNKH2vhfF69ZFyYs0vQ1_oduTpYRU,11200
+claudetracing-0.1.0.dist-info/METADATA,sha256=Wpqq3WRIS38MuSCbinZWiMqe8e-rvZellen16JxkZ3Q,4655
+claudetracing-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claudetracing-0.1.0.dist-info/entry_points.txt,sha256=doR_f5hpH5xHkaJgTL9VUGiWJqd3THgcEvTkbt1hI88,50
+claudetracing-0.1.0.dist-info/licenses/LICENSE,sha256=lUNADonA-UdPir60egcN2kl_kSm_ZHHPHwciDgetHEc,1063
+claudetracing-0.1.0.dist-info/RECORD,,

claudetracing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

claudetracing-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+traces = claudetracing.cli:main

claudetracing-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Casper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.