mlflow-python — Claude Code skill for MLflow experiments
mlflow-python is a Claude Code skill for logging backtest parameters and metrics in MLflow, searching experiment runs, and retrieving metric history via the Python API.
MIT 139 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill mlflow-python -a claude-codeWhat mlflow-python does
Use this skill to create MLflow experiments, log strategy parameters and backtest metrics, filter runs, and retrieve metric time series. Its log_backtest.py script uses QuantStats to calculate trading measures such as Sharpe ratio and maximum drawdown. MLflow operations go through the Python API.
The bundled scripts cover backtest logging, experiment and run queries, experiment creation, and metric history retrieval. Set MLFLOW_TRACKING_URI, MLFLOW_TRACKING_USERNAME, and MLFLOW_TRACKING_PASSWORD before running them; credentials are separate from the tracking URI. Pandas is required. A project’s Polars-preference hook automatically skips the mlflow-python path, so that setup affects whether this skill runs. It does not handle MLflow server administration or artifact storage configuration.
What it helps with
- log backtest metrics and parameters to MLflow
- create an experiment with metadata
- filter runs by metric values
- retrieve time-series data for selected metrics
- calculate trading measures with QuantStats
Example prompts for the agent
- Log the results in
returns.csvto thecrypto-backtestsexperiment with momentum strategy parameters. - Find runs in
crypto-backtestswheremetrics.sharpe_ratioexceeds 1.5, ordered by Sharpe ratio descending. - Create the
crypto-backtests-2025experiment and retrievesharpe_ratioandcumulative_returnhistory for runabc123.
How to install mlflow-python
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill mlflow-python -a claude-code2Manually: put the files in place
~/.claude/skills/mlflow-python/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mlflow-python/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill mlflow-python -a codex2Manually: put the files in place
.agents/skills/mlflow-python/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill mlflow-python -a cursor2Manually: put the files in place
.cursor/skills/mlflow-python/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/devops-tools/skills/mlflow-python2Manually: put the files in place
.github/skills/mlflow-python/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill mlflow-python -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/devops-tools/skills/mlflow-pythonManually: put the files in place
.devin/skills/mlflow-python/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill mlflow-python -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mlflow-python
How do I install mlflow-python in Claude Code?
Run npx skills add terrylica/cc-skills --skill mlflow-python -a claude-code. The installed skill file is at ~/.claude/skills/mlflow-python/SKILL.md.
What does mlflow-python do?
It uses the MLflow Python API to create experiments, log parameters and metrics, search runs, and fetch metric history. For backtests, it calculates trading measures with QuantStats.
What do I need to connect to an MLflow server?
Set MLFLOW_TRACKING_URI, MLFLOW_TRACKING_USERNAME, and MLFLOW_TRACKING_PASSWORD. You can store them in .env.local and run a script with uv run --env-file .env.local.
Source text
SKILL.md · MIT
---
name: mlflow-python
description: MLflow experiment tracking via Python API. TRIGGERS - MLflow metrics, log backtest, experiment tracking, search runs.
allowed-tools: Read, 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](/docs/adr/2025-12-12-mlflow-python-skill.md)
> **Note**: This skill uses Pandas (MLflow API requires it). The `mlflow-python` path is auto-skipped by the Polars preference hook.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## 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):
```bash
# Option 1: .env.local + uv --env-file (recommended)
# Create .env.local (gitignored) in the skill directory with the lines below,
# then run scripts as: uv run --env-file .env.local scripts/<script>.py
MLFLOW_TRACKING_URI=http://mlflow.example.com:5000
MLFLOW_TRACKING_USERNAME=<user>
MLFLOW_TRACKING_PASSWORD=<password>
# Option 2: Direct environment variables
export MLFLOW_TRACKING_URI="http://mlflow.example.com:5000"
export MLFLOW_TRACKING_USERNAME="<user>"
export MLFLOW_TRACKING_PASSWORD="<password>"
```
### Verify Connection
```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
ROOT="$(cc-plugin-root devops-tools)"
cd "$ROOT/skills/mlflow-python"
uv run scripts/query_experiments.py experiments
SKILL_SCRIPT_EOF
```
## Quick Start Workflows
### A. Log Backtest Results (Primary Use Case)
```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
ROOT="$(cc-plugin-root devops-tools)"
cd "$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
```bash
uv run scripts/query_experiments.py experiments
```
### C. Query Runs with Filter
```bash
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
```bash
uv run scripts/create_experiment.py \
--name "crypto-backtests-2025" \
--description "Q1 2025 cryptocurrency trading strategy backtests"
```
### E. Get Metric History
```bash
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](./references/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
Configuration comes from `MLFLOW_*` environment variables. Create `.env.local` (gitignored) for credentials and load it per command with `uv run --env-file .env.local scripts/<script>.py`:
```bash
MLFLOW_TRACKING_URI=http://mlflow.example.com:5000
MLFLOW_TRACKING_USERNAME=<user>
MLFLOW_TRACKING_PASSWORD=<password>
```
## Reference Documentation
- [Authentication Patterns](./references/authentication.md) - Idiomatic MLflow auth
- [QuantStats Metrics](./references/quantstats-metrics.md) - Full list of 70+ metrics
- [Query Patterns](./references/query-patterns.md) - DataFrame operations
- [Migration from CLI](./references/migration-from-cli.md) - CLI to Python API mapping
## 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](./references/migration-from-cli.md) for detailed mapping.
---
## Troubleshooting
| Issue | Cause | Solution |
| ----------------------- | ---------------------------- | --------------------------------------------------- |
| Connection refused | MLflow server not running | Verify MLFLOW_TRACKING_URI and server status |
| Authentication failed | Wrong credentials | Check MLFLOW_TRACKING_USERNAME and PASSWORD in .env |
| Experiment not found | Experiment name typo | Run `query_experiments.py experiments` to list all |
| QuantStats import error | Missing dependency | `uv add quantstats` in skill directory |
| Pandas import warning | Expected for this skill | Ignore - MLflow requires Pandas (hook-excluded) |
| Run creation fails | Experiment doesn't exist | Use `create_experiment.py` to create first |
| Metric history empty | Wrong run_id or metric name | Verify run_id with `query_experiments.py runs` |
| Returns CSV parse error | Wrong date format or columns | Check CSV has date index and returns column |
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills