ML Doctor (mldoct) 🩺

ML Doctor is an automated developer tool for PyTorch engineering workflows. It combines AST-based static code analysis with machine learning to identify training anti-patterns, repair missing loop declarations, and diagnose convergence trajectories.

Capabilities

• AST Static Code Linter (check): Analyzes PyTorch scripts for uncalled zero_grad(), omitted model.eval(), double softmax activations, and missing gradient clipping.
• Automated Fix Engine (--fix): Injects missing optimization steps (optimizer.zero_grad(), model.eval()) directly into the target file while retaining backups.
• OOM Sentinel: Detects un-detached loss tensor accumulation in loops (+= loss), preventing silent CUDA memory leaks.
• Live Process Watchdog (watch): Executes training scripts as a monitored process, intercepting NaN, Inf, and exploding loss spikes in real time.
• Curve Diagnostic Engine (diagnose): Evaluates training logs (train_loss, val_loss, grad_norm) using an embedded gradient boosted model.
• Directory Discovery: Diagnoses whole log directories automatically without requiring explicit file paths.
• Report Generation (--export-report): Writes diagnosis summaries directly to Markdown.

Installation

pip install mldoct

Usage Guide

1. Static Linting & Auto-Fixing

# Scan a script for loop bugs
mldoctor check train.py

# Scan and automatically patch omissions
mldoctor check train.py --fix

2. Live Training Watchdog

# Monitor active training execution
mldoctor watch train.py --epochs 20

3. Metric Trajectory Diagnosis

# Diagnose a specific CSV
mldoctor diagnose metrics.csv

# Auto-discover the latest CSV in a log folder and export a report
mldoctor diagnose ./logs/ --export-report

4. Package Information

mldoctor info

Author & Maintainer

• Author: Shravan Gupta
• Website: shravangupta.dev