claudetracing 0.1.0__tar.gz

claudetracing-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# macOS
+.DS_Store
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+
+# Databricks
+.databrickscfg
+
+# MLflow
+mlruns/
+mlflow.db
+
+# Claude Code
+.claude/
+
+# Caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

claudetracing-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

claudetracing-0.1.0/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.

claudetracing-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "claudetracing"
+version = "0.1.0"
+description = "MLflow tracing for Claude Code sessions with Databricks integration"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Casper" }]
+keywords = ["claude", "mlflow", "tracing", "databricks", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mlflow[databricks]>=3.4",
+    "pydantic>=2.0",
+    "ty>=0.0.8",
+    "typer>=0.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/CauchyIO/claudetracing"
+Repository = "https://github.com/CauchyIO/claudetracing"
+Issues = "https://github.com/CauchyIO/claudetracing/issues"
+
+[project.scripts]
+traces = "claudetracing.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claudetracing"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore:The distutils package is deprecated:DeprecationWarning",
+]

claudetracing-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)