mlflow-python

Log experiment metrics, parameters, and artifacts using MLflow Python API. Query and analyze runs with DataFrame operations. Use when user mentions "log backtest", "MLflow metrics", "experiment tracking", "log parameters", "search runs", "MLflow query", or needs to record strategy performance.

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive interface for MLflow, allowing users to log, query, and analyze experiment metrics, parameters, and artifacts via the Python API. It features specialized integration with QuantStats for advanced trading performance analysis, enabling data-driven decision-making through automated experiment tracking, SQL-like run filtering, and DataFrame-based reporting.

Use Cases

  • Log comprehensive trading backtest results including 70+ financial metrics like Sharpe ratio, Max Drawdown, and Win Rate using QuantStats integration.
  • Track and compare machine learning model parameters and performance metrics across multiple experimental runs to identify the best-performing configurations.
  • Query and filter historical experiment data using SQL-like syntax to generate performance reports and dataframes for deep-dive analysis.
  • Automate the management of experiment metadata, including creating new experiments and retrieving time-series metric history for trend visualization.
namemlflow-python
description>
allowed-toolsRead, Bash, Grep, Glob

MLflow Python Skill

Unified read/write MLflow operations via Python API with QuantStats integration for comprehensive trading metrics.

ADR: 2025-12-12-mlflow-python-skill

When to Use This Skill

CAN Do:

  • Log backtest metrics (Sharpe, max_drawdown, total_return, etc.)
  • Log experiment parameters (strategy config, timeframes)
  • Create and manage experiments
  • Query runs with SQL-like filtering
  • Calculate 70+ trading metrics via QuantStats
  • Retrieve metric history (time-series data)

CANNOT Do:

  • Direct database access to MLflow backend
  • Artifact storage management (S3/GCS configuration)
  • MLflow server administration

Prerequisites

Authentication Setup

MLflow uses separate environment variables for credentials (NOT embedded in URI):

# Option 1: mise + .env.local (recommended)
# Create .env.local in skill directory with:
MLFLOW_TRACKING_URI=http://mlflow.eonlabs.com:5000
MLFLOW_TRACKING_USERNAME=eonlabs
MLFLOW_TRACKING_PASSWORD=<password>

# Option 2: Direct environment variables
export MLFLOW_TRACKING_URI="http://mlflow.eonlabs.com:5000"
export MLFLOW_TRACKING_USERNAME="eonlabs"
export MLFLOW_TRACKING_PASSWORD="<password>"

Verify Connection

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/mlflow-python
uv run scripts/query_experiments.py experiments
SKILL_SCRIPT_EOF

Quick Start Workflows

A. Log Backtest Results (Primary Use Case)

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
cd ${CLAUDE_PLUGIN_ROOT}/skills/mlflow-python
uv run scripts/log_backtest.py \
  --experiment "crypto-backtests" \
  --run-name "btc_momentum_v2" \
  --returns path/to/returns.csv \
  --params '{"strategy": "momentum", "timeframe": "1h"}'
SKILL_SCRIPT_EOF_2

B. Search Experiments

uv run scripts/query_experiments.py experiments

C. Query Runs with Filter

uv run scripts/query_experiments.py runs \
  --experiment "crypto-backtests" \
  --filter "metrics.sharpe_ratio > 1.5" \
  --order-by "metrics.sharpe_ratio DESC"

D. Create New Experiment

uv run scripts/create_experiment.py \
  --name "crypto-backtests-2025" \
  --description "Q1 2025 cryptocurrency trading strategy backtests"

E. Get Metric History

uv run scripts/get_metric_history.py \
  --run-id abc123 \
  --metrics sharpe_ratio,cumulative_return

QuantStats Metrics Available

The log_backtest.py script calculates 70+ metrics via QuantStats, including:

Category Metrics
Ratios sharpe, sortino, calmar, omega, treynor
Returns cagr, total_return, avg_return, best, worst
Drawdown max_drawdown, avg_drawdown, drawdown_days
Trade win_rate, profit_factor, payoff_ratio, consecutive_wins/losses
Risk volatility, var, cvar, ulcer_index, serenity_index
Advanced kelly_criterion, recovery_factor, risk_of_ruin, information_ratio

See quantstats-metrics.md for full list.

Bundled Scripts

Script Purpose
log_backtest.py Log backtest returns with QuantStats metrics
query_experiments.py Search experiments and runs (replaces CLI)
create_experiment.py Create new experiment with metadata
get_metric_history.py Retrieve metric time-series data

Configuration

The skill uses mise [env] pattern for configuration. See .mise.toml for defaults.

Create .env.local (gitignored) for credentials:

MLFLOW_TRACKING_URI=http://mlflow.eonlabs.com:5000
MLFLOW_TRACKING_USERNAME=eonlabs
MLFLOW_TRACKING_PASSWORD=<password>

Reference Documentation

Migration from mlflow-query

This skill replaces the CLI-based mlflow-query skill. Key differences:

Feature mlflow-query (old) mlflow-python (new)
Log metrics Not supported mlflow.log_metrics()
Log params Not supported mlflow.log_params()
Query runs CLI text parsing DataFrame output
Metric history Workaround only Native support
Auth pattern Embedded in URI Separate env vars

See migration-from-cli.md for detailed mapping.