Metadata-Version: 2.4
Name: mldoct
Version: 0.2.0
Summary: Automated static AST linter, auto-fixer & training curve diagnostic suite for PyTorch.
Author: Shravan Gupta
Project-URL: Homepage, https://shravangupta.dev
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: rich

# 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

```bash
pip install mldoct
```

---

## Usage Guide

### 1. Static Linting & Auto-Fixing
```bash
# Scan a script for loop bugs
mldoctor check train.py

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

### 2. Live Training Watchdog
```bash
# Monitor active training execution
mldoctor watch train.py --epochs 20
```

### 3. Metric Trajectory Diagnosis
```bash
# 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
```bash
mldoctor info
```

---

## Author & Maintainer

- **Author**: Shravan Gupta
- **Website**: [shravangupta.dev](https://shravangupta.dev)
