Metadata-Version: 2.4
Name: protoml
Version: 1.0.0
Summary: Zero-code ML prototyping dashboard: tabular, vision, NLP, Bayesian optimisation, XAI, and Gemini AI assistant.
Project-URL: Bug Tracker, https://github.com/your-org/protoml-dashboard/issues
Author: ProtoML Contributors
License: MIT
License-File: LICENSE
Keywords: automl,dashboard,machine-learning,nlp,streamlit,xai
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: joblib>=1.3.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: scikit-optimize>=0.10.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: seaborn>=0.13.0
Requires-Dist: streamlit>=1.33.0
Requires-Dist: tabulate>=0.9.0
Provides-Extra: ai
Requires-Dist: google-genai>=0.4.0; extra == 'ai'
Provides-Extra: all
Requires-Dist: protoml-dashboard[ai]; extra == 'all'
Requires-Dist: protoml-dashboard[nlp]; extra == 'all'
Requires-Dist: protoml-dashboard[tabular-full]; extra == 'all'
Requires-Dist: protoml-dashboard[vision]; extra == 'all'
Requires-Dist: protoml-dashboard[xai]; extra == 'all'
Provides-Extra: nlp
Requires-Dist: nltk>=3.8.0; extra == 'nlp'
Requires-Dist: sentence-transformers>=2.6.0; extra == 'nlp'
Provides-Extra: tabular-full
Requires-Dist: catboost>=1.2.0; extra == 'tabular-full'
Requires-Dist: imbalanced-learn>=0.12.0; extra == 'tabular-full'
Requires-Dist: lightgbm>=4.0.0; extra == 'tabular-full'
Requires-Dist: xgboost>=2.0.0; extra == 'tabular-full'
Provides-Extra: vision
Requires-Dist: torch>=2.2.0; extra == 'vision'
Requires-Dist: torchvision>=0.17.0; extra == 'vision'
Provides-Extra: xai
Requires-Dist: lime>=0.2.0.1; extra == 'xai'
Requires-Dist: shap>=0.44.0; extra == 'xai'
Description-Content-Type: text/markdown

# ProtoML — Zero-Code ML Prototyping Dashboard

ProtoML is a Streamlit application that lets researchers and domain experts run complete machine-learning experiments — tabular, vision, and NLP — without writing a single line of model-training code.  Upload data, pick models, click **Run**, and get a publication-ready diagnostics panel, optimised model export, LIME/SHAP explanations, and an optional Gemini AI assistant.

---

## Table of Contents

1. [Quick Install](#quick-install)
2. [Launching the App](#launching-the-app)
3. [Features at a Glance](#features-at-a-glance)
4. [Tab-by-Tab Guide](#tab-by-tab-guide)
5. [Supported Models](#supported-models)
6. [Scientific Insights Panel](#scientific-insights-panel)
7. [Export and Reproducibility](#export-and-reproducibility)
8. [Project Structure](#project-structure)
9. [Running the Test Suite](#running-the-test-suite)
10. [Publishing to PyPI (GitHub Actions)](#publishing-to-pypi-github-actions)
11. [Benchmark Datasets](#benchmark-datasets)
12. [Requirements](#requirements)
13. [License](#license)

---

## Quick Install

```bash
# Recommended — everything enabled
pip install "protoml-dashboard[all]"
```

Install only what you need:

| Extra | What it adds |
|---|---|
| *(no extra)* | Core tabular ML (scikit-learn + scikit-optimize only) |
| `[tabular-full]` | XGBoost, LightGBM, CatBoost |
| `[vision]` | PyTorch + TorchVision for Vision DL tab |
| `[xai]` | SHAP, LIME explainability |
| `[nlp]` | NLTK, Sentence Transformers for NLP tab |
| `[ai]` | Google Gemini AI assistant |
| `[all]` | All of the above |

```bash
# Mix and match
pip install "protoml-dashboard[tabular-full,xai]"
pip install "protoml-dashboard[vision,nlp]"
```

> **GPU/CUDA note:** For a CUDA-enabled PyTorch build, install the matching torch wheels from [pytorch.org](https://pytorch.org) *before* installing `protoml-dashboard[vision]`.

---

## Launching the App

```bash
protoml
```

Or via Python module:

```bash
python -m protoml
```

The dashboard opens automatically in your browser at `http://localhost:8501`.

---

## Features at a Glance

| Tab | Engine | Key capabilities |
|---|---|---|
| **Tabular ML** | scikit-learn, XGBoost, LightGBM, CatBoost | Classification, regression, multi-label; Bayesian BO; SHAP/LIME/PDP; EDA |
| **Vision DL** | PyTorch, torchvision | Transfer learning on 9 architectures; GradCAM; live epoch progress |
| **Ablation Study** | scikit-learn | Per-component sensitivity (scaler, SMOTE, split, folds) |
| **Predict** | joblib / PyTorch | Batch tabular & vision inference; confidence histograms |
| **NLP** | TF-IDF / Sentence Transformers | ML + DL tracks; BayesSearchCV; LIME text; top-feature charts |
| **AI Assistant** | Google Gemini | Context-aware ML advisor aware of your leaderboard results |

---

## Tab-by-Tab Guide

### Tab 1 — Tabular ML

**Workflow**

1. Upload a `.csv` or `.xlsx/.xls` file, paste a URL, or enter a local path.
2. Select one **or more** Target Y columns (multiple = multi-label mode).
3. Select Feature X columns (numeric and/or categorical; auto-encoded).
4. Pick models from the grouped model picker.
5. Configure imbalance handling, scaler, test split, CV folds, and BO iterations.
6. Click **Run Tabular Pipeline**.

**Highlights**

- **Task auto-detection** — continuous targets → regression; multi-Y → `MultiOutputClassifier`
- **Imbalance handling** — SMOTE or random oversampling (skipped for regression and multi-label)
- **Feature scaling** — auto-select, RobustScaler, StandardScaler, or MinMaxScaler
- **Live leaderboard** — updates after each model's cross-validation completes
- **Bayesian optimisation** — `BayesSearchCV` from scikit-optimize; winner selected by holdout test score
- **EDA panel** — summary stats, histograms, box plots, correlation heatmap, missing-value heatmap, data quality report
- **All models exported** — download `.joblib` + JSON metadata sidecar for any run model, not just the winner

---

### Tab 2 — Vision DL

**Workflow**

1. Provide an image dataset as a folder path (sub-folders = class names) or a `.zip` archive.
2. Select one or more architectures and configure training settings.
3. Click **Run Vision Pipeline**.

**Highlights**

- **Architectures** — ResNet18/50, EfficientNet-B0/B3, MobileNetV3-S/L, DenseNet121, ViT-B/16, Swin-T
- **Fine-tuning strategy** — frozen backbone (fast prototyping) or full fine-tune
- **Live training curves** — epoch-by-epoch training and validation loss/accuracy
- **Post-run diagnostics** — confusion matrix, class distribution chart, sample image grid
- **GradCAM** — gradient-weighted class activation maps for incorrect predictions
- **Device-agnostic** — routes to CUDA GPU when available, falls back to CPU

---

### Tab 3 — Ablation Study

**Workflow**

1. Upload or load a dataset (same file formats as Tab 1).
2. Choose a single model and a baseline configuration.
3. Check which pipeline components to ablate.
4. Click **Run Ablation Study**.

**Highlights**

- Vary one component at a time: SMOTE, scaler, test split, CV folds
- Delta (%) shows each component's contribution relative to the baseline
- Ranked bar chart with colour-coded positive/negative impact
- SMOTE option is automatically hidden for regression tasks

---

### Tab 4 — Predict / Inference

**Tabular inference**

1. Upload a saved `.joblib` tabular model.
2. Supply new data — paste rows directly, upload CSV/Excel, or provide a URL.
3. Download a prediction CSV with confidence scores per class.

**Vision inference**

1. Upload a `.pt` vision model and its `_metadata.json` sidecar.
2. Upload image files or specify a folder path.
3. Download a batch prediction CSV.

**Highlights**

- Confidence histogram with zone shading (red < 70 %, amber 70–90 %, green ≥ 90 %)
- Uncertain prediction flagging with expandable low-confidence rows
- Missing input columns filled with 0 and flagged with a warning

---

### Tab 5 — NLP

**Workflow**

1. Upload a CSV/Excel file with a **text column** and a **label column**.
2. Select a track:
   - **ML track** — TF-IDF preprocessing → sklearn classifiers → BayesSearchCV
   - **DL track** — Sentence Transformer embeddings → sklearn classifiers (no fine-tuning)
3. Pick models (grouped by family) and configure preprocessing / embedding settings.
4. Click **Run NLP Pipeline**.

**ML Track details**

- **TF-IDF preprocessing** — configurable stopword removal (NLTK), Porter stemming, n-gram range (1–3), and `max_features`
- **Classifiers** — Logistic Regression, Linear SVC, SGD, Multinomial NB, Complement NB, Random Forest, XGBoost
- **Bayesian optimisation** — BayesSearchCV over regularisation and tree hyperparameters; winner selected by inner CV score
- **LIME text explanations** — per-sample word-level attribution for the winning model
- **Top TF-IDF feature chart** — top positive/negative coefficient words per class for linear models

**DL Track details**

- **Sentence Transformer models** — `all-MiniLM-L6-v2`, `all-mpnet-base-v2`, `paraphrase-MiniLM-L6-v2`
- Embeds the entire corpus once; classifiers are trained on the fixed embeddings (fast, no GPU fine-tuning loop)
- Device-agnostic — routes to CUDA when available via `torch.cuda.is_available()`

---

### Tab 6 — AI Assistant

Enter a **Google Gemini API key** in the sidebar to activate a context-aware ML assistant.

The assistant is automatically briefed on:
- The current leaderboard (model names, accuracy scores)
- The best hyperparameters found by Bayesian optimisation
- The active tab and task type

Useful for: interpreting results, suggesting next steps, explaining model behaviour, and generating code snippets.

---

## Supported Models

### Tabular Classification
Random Forest, XGBoost, Gradient Boosting, Extra Trees, Hist Gradient Boosting, SVM, Logistic Regression, Ridge Classifier, MLP, Decision Tree, KNN, Bernoulli NB, Gaussian NB, LDA, QDA, AdaBoost, SGD, Linear SVC, Passive Aggressive, LightGBM *(optional)*, CatBoost *(optional)*

### Tabular Regression
Random Forest, XGBoost, Gradient Boosting, Extra Trees, Hist Gradient Boosting, SVR, Linear Regression, Ridge, MLP, Decision Tree, KNN, AdaBoost, SGD, Linear SVR, Passive Aggressive, LightGBM *(optional)*, CatBoost *(optional)*

### Vision Architectures
ResNet18, ResNet50, EfficientNet-B0, EfficientNet-B3, MobileNetV3-Small, MobileNetV3-Large, DenseNet121, ViT-B/16, Swin-T

### NLP Classifiers (both tracks)
Logistic Regression, Linear SVC, SGD Classifier, Multinomial NB, Complement NB, Random Forest, XGBoost

---

## Scientific Insights Panel

Shown after every completed run:

| Section | Contents |
|---|---|
| **Leaderboard** | Accuracy, Macro F1, Weighted F1 per model; timing; CSV export |
| **Classification Report** | Per-class precision / recall / F1 / support |
| **Confusion Matrix** | Standard (single-label) or per-label 2×2 grid (multi-label) |
| **ROC Curves** | Per-class AUC curves (classification only) |
| **Feature Importance** | Top-15 features by importance or coefficient magnitude |
| **SHAP Global** | Mean \|SHAP\| per feature (multi-class: class-average) |
| **SHAP Waterfall** | Single-sample SHAP breakdown |
| **PDP** | Partial dependence plots for top numeric features |
| **LIME** | Single-sample LIME tabular or text explanation |
| **Calibration** | Reliability diagram + Brier score (classification only) |
| **Convergence** | Bayesian optimisation score history |
| **Learning Curve** | Train-set size vs CV score (on-demand) |
| **Feature Ablation** | Drop-one feature impact table and chart (on-demand) |
| **Regression Report** | Residuals vs Fitted, Q-Q, histogram + Normal PDF, Scale-Location; Shapiro-Wilk and KS tests |
| **Training Curve** | Epoch-level training / validation curves (Vision DL) |
| **NLP LIME** | Word-level attribution bar chart for winning NLP model |
| **Top TF-IDF Features** | Per-class positive/negative coefficient words (linear NLP models) |

---

## Export and Reproducibility

- Per-model `.joblib` download buttons for every trained tabular model
- JSON metadata sidecar alongside each export (feature list, hyperparameters, metric)
- Leaderboard CSV download
- Full self-contained HTML experiment report
- LaTeX `booktabs` table for direct inclusion in papers
- Experiment archive saved under `~/ProtoML/experiments/`

---

## Project Structure

```text
Proto-ML/
├── pyproject.toml               # pip packaging config and entry point
├── requirements.txt             # plain dependency list (alternative to pip extras)
├── README.md
│
├── protoml/                     # installed Python package
│   ├── __init__.py              # exposes __version__ = "1.0.0"
│   ├── __main__.py              # CLI entry point — runs `streamlit run app.py`
│   ├── app.py                   # Streamlit UI: 6-tab layout, session state, result rendering
│   ├── tabular_engine.py        # Baseline CV, Bayesian BO, SHAP/LIME/PDP, multi-label
│   ├── vision_engine.py         # Vision training loop, GradCAM, dataset summary
│   ├── nlp_engine.py            # TF-IDF + ST pipelines, BayesOpt, LIME text, device detection
│   ├── inference_engine.py      # Tabular and vision model loading and batch inference
│   ├── reporting.py             # Every chart, table, and export function
│   ├── file_utils.py            # CSV / Excel reading helpers (Streamlit-free, fully testable)
│   ├── tracker.py               # Experiment saving and HTML report generation
│   └── utils.py                 # Page styling and session-state helpers
│
├── tests/
│   ├── test_tabular_engine.py   # 40+ tests: baseline, BO, multi-label, PDP, SHAP, LIME
│   ├── test_nlp_engine.py       # 136 tests: every model, every config flag, DL track, LIME
│   ├── test_reporting.py        # 70+ tests: every render function including NLP renderers
│   ├── test_inference_engine.py # 12 tests: tabular and vision inference
│   ├── test_vision_analysis.py  # 14 tests: dataset summary, device detection, model loading
│   └── test_file_reading.py     # 20+ tests: CSV/Excel reading, sheet selection
│
└── .github/
    └── workflows/
        └── publish.yml          # CI: test → build → publish to PyPI on version tag
```

---

## Running the Test Suite

```bash
# Install with test extras
pip install -e ".[tabular-full,vision,xai,nlp]"
pip install pytest

# Run all 277 tests
python -m pytest tests/ -v

# Run only fast tests (skip vision and DL-track tests)
python -m pytest tests/ -v --ignore=tests/test_vision_analysis.py -k "not DlTrack"
```

Test coverage at a glance:

| File | Tests | Notes |
|---|---|---|
| `test_nlp_engine.py` | 136 (125 pass, 11 skip) | LIME tests skip when `lime` not installed |
| `test_reporting.py` | 70+ | All render functions including NLP renderers |
| `test_tabular_engine.py` | 40+ | Baseline, BO, multi-label, PDP, SHAP, LIME |
| `test_inference_engine.py` | 12 | Tabular and vision inference |
| `test_vision_analysis.py` | 14 | Dataset summary, device detection |
| `test_file_reading.py` | 20+ | CSV/Excel formats, sheet selection |

---

## Publishing to PyPI (GitHub Actions)

The included workflow at [.github/workflows/publish.yml](.github/workflows/publish.yml) handles testing, building, and publishing automatically.

### How it works

| Trigger | What runs |
|---|---|
| Push to `main` or any PR | `test` job — runs suite on Python 3.9, 3.11, 3.12 |
| Push of a version tag `v*.*.*` | `test` → `build` → `publish` to PyPI |

### One-time PyPI setup (Trusted Publisher — no token needed)

1. Log in to [pypi.org](https://pypi.org) → **Your projects** → select or create `protoml-dashboard`.
2. Go to **Settings → Publishing → Add a new publisher** → choose **GitHub Actions**.
3. Fill in:
   - Owner: `<your-github-username>`
   - Repository: `<your-repo-name>`
   - Workflow filename: `publish.yml`
   - Environment name: `pypi`
4. Save.

### How to release a new version

```bash
# 1. Bump version in pyproject.toml and protoml/__init__.py
# 2. Commit and push
git add pyproject.toml protoml/__init__.py
git commit -m "chore: bump version to v1.1.0"
git push origin main

# 3. Tag and push the tag — this triggers the publish job
git tag v1.1.0
git push origin v1.1.0
```

The workflow will run tests, build `dist/protoml_dashboard-1.1.0-py3-none-any.whl` and the sdist, then upload both to PyPI. The new version is live within seconds.

> **Alternative: API token** — If you prefer a token over Trusted Publisher, create one at pypi.org → Account settings → API tokens, store it as a GitHub Actions secret named `PYPI_API_TOKEN`, and follow the token-based instructions in the comments inside `publish.yml`.

---

## Benchmark Datasets

| Task | Dataset | Rows | Source |
|---|---|---|---|
| Binary classification | Breast Cancer Wisconsin | 569 | `sklearn.datasets.load_breast_cancer()` → CSV |
| Regression | Diabetes | 442 | `sklearn.datasets.load_diabetes()` → CSV |
| Multi-label classification | Emotions | ~1,000 | Kaggle; 6 binary label columns |
| Image classification | Rock Paper Scissors | 2,520 | Kaggle; 3 balanced classes; folder-per-class |
| Text classification | 20 Newsgroups | 18,846 | `sklearn.datasets.fetch_20newsgroups()` → CSV |
| Sentiment analysis | IMDB Reviews | 50,000 | Kaggle; binary positive/negative labels |

---

## Requirements

- Python 3.9 or newer
- CPU is sufficient for all tabular and NLP experiments
- CUDA GPU is recommended (but not required) for Vision DL and NLP DL tracks

Core dependencies installed automatically:

```
streamlit, pandas, numpy, matplotlib, seaborn, scipy, scikit-learn, scikit-optimize, joblib
```

Optional dependencies installed via extras (see [Quick Install](#quick-install)).

---

## Notes

- **URL ingestion** requires network access (`requests`).
- **ZIP extraction** includes a path-traversal safety check before unpacking.
- **Multi-label mode** wraps every classifier in `MultiOutputClassifier`; SMOTE, SHAP, LIME, and PDP are skipped automatically.
- **SHAP waterfall** values are averaged across classes for multi-class models.
- **Missing inference columns** are filled with 0 and flagged with a warning.
- **skopt tuple bug** — scikit-optimize 0.10.x crashes when a `Categorical` space contains tuple values; the NLP engine works around this by excluding `ngram_range` from BayesSearchCV and controlling it at pipeline build time instead.

---

## License

MIT License. See `LICENSE` for details.
