automl-sandbox 0.1.0
Automated ML Training Sandbox - Fast, explainable, reproducible AutoML
License: MIT
Requires Python: >=3.9
Keywords: machine-learning, automl, scikit-learn, xgboost, lightgbm, cli

# AutoML Sandbox

**Fast, explainable, reproducible AutoML for tabular data.**

AutoML Sandbox is a production-ready automated machine learning tool that takes a CSV dataset and automatically:
- Profiles your data
- Infers the ML task type (binary/multiclass classification or regression)
- Preprocesses data (imputation, scaling, encoding)
- Trains multiple models (Logistic Regression, Random Forest, XGBoost, LightGBM)
- Selects the best performer using cross-validation
- Exports trained models and detailed reports

## Installation

### From PyPI (once published)
```bash
pip install automl-sandbox
```

### From Source
```bash
git clone https://github.com/sekpeyherbert/automl-sandbox.git
cd automl-sandbox
pip install -e .
```

### With XGBoost and LightGBM (recommended)
```bash
pip install -e ".[all]"
```

## Quick Start

### Command Line
```bash
# Interactive mode - select file from menu
automl run

# Direct file path
automl run data.csv

# Specify target column
automl run data.csv --target label

# Custom output directory
automl run data.csv -o results -n my_experiment

# Make predictions with trained model
automl predict outputs/models/model.pkl new_data.csv -o predictions.csv

# Profile data without training
automl profile data.csv

# View training report
automl show outputs/reports/report.json
```

### Python API
```python
from automl import AutoMLPipeline

# Initialize pipeline
pipeline = AutoMLPipeline(
    output_dir="outputs",
    cv_folds=3,
    use_xgboost=True,
    use_lightgbm=True
)

# Run training
results = pipeline.run(
    data_path="data.csv",
    target_column="target",
    run_name="my_experiment"
)

# Access results
print(f"Best model: {results['best_model_name']}")
print(f"Best score: {results['best_score']:.4f}")

# Make predictions
predictions = pipeline.predict(new_data)
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `automl run [FILE]` | Train models on a CSV dataset |
| `automl predict MODEL DATA` | Make predictions using a trained model |
| `automl profile [FILE]` | Profile a dataset without training |
| `automl show [REPORT]` | Display a training report |
| `automl analyze [REPORT]` | Analyze model in different business contexts |
| `automl list-contexts` | List available business contexts |

### Run Options

| Option | Description |
|--------|-------------|
| `-t, --target` | Target column name (auto-detected if not provided) |
| `-o, --output` | Output directory (default: outputs) |
| `-n, --name` | Name for training run |
| `--cv-folds` | Number of cross-validation folds (default: 3) |
| `--no-xgboost` | Disable XGBoost models |
| `--no-lightgbm` | Disable LightGBM models |
| `--no-balance` | Disable class balancing for imbalanced datasets |
| `--balance-strategy` | Strategy for balancing: auto, smote, adasyn, random_over, random_under, smote_tomek, smote_enn, none (default: auto) |
| `-q, --quiet` | Suppress verbose output |
| `--seed` | Random seed for reproducibility (default: 42) |
| `-i, --interactive` | Force interactive mode |

## Features

### Data Profiling
- Automatic type detection (numerical/categorical)
- Missing value analysis
- Cardinality analysis
- Class imbalance detection
- Target column inference

### Task Inference
- Binary classification
- Multiclass classification
- Regression
- Automatic detection based on target characteristics

### Class Balancing (Imbalanced-Learn)
Automatic handling of imbalanced datasets using:
- **SMOTE**: Synthetic Minority Over-sampling Technique (default)
- **ADASYN**: Adaptive Synthetic Sampling
- **Random Oversampling**: Simple duplication of minority samples
- **Random Undersampling**: Removal of majority samples
- **SMOTE-Tomek**: SMOTE + Tomek links for cleaner boundaries
- **SMOTE-ENN**: SMOTE + Edited Nearest Neighbors

Balancing is automatically applied when:
- Dataset is detected as imbalanced (minority/majority ratio < 0.2)
- Task is classification (not regression)
- Balancing is not disabled via `--no-balance`

### Business Context Analysis
Analyze your model's performance in different business contexts to understand the real-world implications of your confusion matrix:

```bash
# Analyze as churn prediction
automl analyze report.json -c churn_prediction

# Analyze as fraud detection with cost analysis
automl analyze report.json -c fraud_detection --fp-cost 10 --fn-cost 500

# List all available contexts
automl list-contexts
```

**Available Contexts:**
| Context | FN Cost | FP Cost | Priority Metric |
|---------|---------|---------|-----------------|
| `fraud_detection` | Critical | Medium | Recall |
| `churn_prediction` | High | Low | Recall |
| `medical_diagnosis` | Critical | Medium | Recall |
| `spam_detection` | Low | Critical | Precision |
| `loan_approval` | High | Medium | F1 |
| `marketing_campaign` | Medium | Low | Precision |
| `quality_control` | Critical | Medium | Recall |

### Preprocessing
- Numerical: Mean/median imputation, StandardScaler
- Categorical: Most frequent imputation, OneHotEncoding
- Combined via scikit-learn ColumnTransformer

### Model Candidates

**Classification:**
- Logistic Regression
- Random Forest Classifier
- Gradient Boosting Classifier
- XGBoost Classifier (optional)
- LightGBM Classifier (optional)

**Regression:**
- Linear Regression
- Ridge / Lasso Regression
- Random Forest Regressor
- Gradient Boosting Regressor
- XGBoost Regressor (optional)
- LightGBM Regressor (optional)

### Evaluation Metrics

| Task | Primary Metric |
|------|----------------|
| Binary Classification | ROC-AUC |
| Multiclass Classification | F1-macro |
| Regression | RMSE / R² |

### Outputs

| File | Description |
|------|-------------|
| `model.pkl` | Trained model + preprocessor bundle |
| `report.json` | Full training report (JSON) |
| `report.html` | Interactive HTML report |
| `confusion_matrix.png` | Confusion matrix plot (classification) |
| `feature_importance.png` | Feature importance plot |

## Project Structure

```
automl-sandbox/
├── automl/
│   ├── __init__.py       # Package initialization
│   ├── __main__.py       # Module entry point
│   ├── cli.py            # CLI interface
│   ├── pipeline.py       # Main orchestrator
│   ├── profiler.py       # Data profiling
│   ├── task_inference.py # Task type detection
│   ├── preprocessing.py  # Data preprocessing
│   ├── balancer.py       # Class balancing (SMOTE, etc.)
│   ├── models.py         # Model candidates
│   ├── trainer.py        # Training strategy
│   ├── evaluator.py      # Model evaluation
│   └── exporter.py       # Model/report export
├── pyproject.toml        # Package configuration
├── requirements.txt      # Dependencies
├── README.md             # Documentation
└── LICENSE               # MIT License
```

## Requirements

- Python >= 3.9
- pandas >= 2.0.0
- numpy >= 1.24.0
- scikit-learn >= 1.3.0
- imbalanced-learn >= 0.11.0
- matplotlib >= 3.7.0
- seaborn >= 0.12.0
- click >= 8.1.0
- jinja2 >= 3.1.0
- joblib >= 1.3.0

**Optional:**
- xgboost >= 2.0.0
- lightgbm >= 4.0.0

## License

MIT License - see [LICENSE](LICENSE) file.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.