preflight-ml 0.1.0__tar.gz

preflight_ml-0.1.0/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto
+*.py text eol=lf
+*.toml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.md text eol=lf

preflight_ml-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Something is broken
+labels: ["bug"]
+body:
+  - type: input
+    id: preflight-version
+    attributes:
+      label: preflight version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: pytorch-version
+    attributes:
+      label: PyTorch version
+      placeholder: "2.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options: [Windows, macOS, Linux]
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Smallest code that reproduces the issue
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual output
+    validations:
+      required: true

preflight_ml-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest a new check or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What silent failure would this catch?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed check or feature
+    validations:
+      required: true
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Suggested severity
+      options: [FATAL, WARN, INFO]

preflight_ml-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy preflight/ --ignore-missing-imports --no-site-packages
+
+      - name: Test
+        run: pytest

preflight_ml-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Build
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

preflight_ml-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Testing
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Env
+.env
+.venv
+env/
+venv/
+
+# VS Code
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+dist/

preflight_ml-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml

preflight_ml-0.1.0/.preflight.toml

@@ -0,0 +1,23 @@
+[checks]
+# set false to disable any check
+nan_inf_detection = true
+normalisation_sanity = true
+channel_ordering = true
+label_leakage = true
+split_sizes = true
+vram_estimation = true
+class_imbalance = true
+shape_mismatch = true
+gradient_check = true
+
+[thresholds]
+nan_sample_batches = 10
+norm_sample_batches = 5
+leakage_sample_batches = 20
+imbalance_sample_batches = 10
+imbalance_threshold = 0.1
+
+[ignore]
+# example: ignore a specific check with a reason
+# check = "class_imbalance"
+# reason = "intentional: rare event dataset"

preflight_ml-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to preflight will be documented here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-15
+
+### Added
+- 10 core pre-flight checks: NaN/Inf detection, normalisation sanity,
+  channel ordering, label leakage, split sizes, VRAM estimation,
+  class imbalance, shape mismatch, gradient check
+- `.preflight.toml` config file support
+- Rich terminal output with severity tiers (FATAL / WARN / INFO)
+- JSON output mode (`--format json`) for CI integration
+- `preflight run` and `preflight checks` CLI commands
+- Fix hints for all failing checks

preflight_ml-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to preflight
+
+## Setup
+```bash
+git clone https://github.com/Rusheel86/preflight.git
+cd preflight
+conda create -n preflight-dev python=3.11 -y
+conda activate preflight-dev
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Running tests
+```bash
+pytest
+```
+
+## Adding a new check
+
+1. Add a function to the appropriate file in `preflight/checks/`
+2. Decorate it with `@register`
+3. Return a `CheckResult` with the correct severity
+4. Write two tests: one that passes, one that fails
+5. Add an entry to `CHANGELOG.md`
+
+Every check function must accept `(dataloader, model, loss_fn, config)` as keyword arguments even if it only uses some of them.
+
+## Commit style
+
+`fix: correct NaN detection in multi-output dataloaders`
+`feat: add duplicate sample detection check`
+`docs: add example for custom config`
+
+Sign all commits: `git commit -s -m "your message"`

preflight_ml-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rusheel Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

preflight_ml-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: preflight-ml
+Version: 0.1.0
+Summary: Pre-flight checks for PyTorch pipelines. Catch silent failures before they waste your GPU.
+Project-URL: Homepage, https://github.com/Rusheel86/preflight
+Project-URL: Repository, https://github.com/Rusheel86/preflight
+Project-URL: Issues, https://github.com/Rusheel86/preflight/issues
+Author: Rusheel Sharma
+License: MIT License
+        
+        Copyright (c) 2026 Rusheel Sharma
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: data-validation,debugging,deep-learning,machine-learning,mlops,pytorch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: numpy>=1.20
+Requires-Dist: rich>=12.0
+Requires-Dist: torch>=1.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# preflight
+
+> Pre-flight checks for PyTorch pipelines. Catch silent failures before they waste your GPU.
+
+[![CI](https://github.com/Rusheel86/preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/Rusheel86/preflight/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/preflight-ml)](https://pypi.org/project/preflight-ml/)
+[![Python](https://img.shields.io/pypi/pyversions/preflight-ml)](https://pypi.org/project/preflight-ml/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+Most deep learning bugs don't crash your training loop — they silently produce a garbage model.
+NaNs in your data, labels leaking between train and val, wrong channel ordering, dead gradients.
+You won't know until hours later, after the GPU bill has landed.
+
+**preflight** is a pre-training validation tool you run in 30 seconds before starting any training job.
+It's not a linter. It's a pre-flight check — the kind pilots run before the expensive thing takes off.
+
+---
+
+## Install
+
+```bash
+pip install preflight-ml
+```
+
+## Quickstart
+
+Create a small Python file that exposes your dataloader:
+
+```python
+# my_dataloader.py
+import torch
+from torch.utils.data import DataLoader, TensorDataset
+
+x = torch.randn(200, 3, 224, 224)
+y = torch.randint(0, 10, (200,))
+dataloader = DataLoader(TensorDataset(x, y), batch_size=32)
+```
+
+Run preflight:
+
+```bash
+preflight run --dataloader my_dataloader.py
+```
+
+Output:
+
+```
+preflight — pre-training check report
+╭────────────────────────┬──────────┬────────┬──────────────────────────────────────────────────╮
+│ Check                  │ Severity │ Status │ Message                                          │
+├────────────────────────┼──────────┼────────┼──────────────────────────────────────────────────┤
+│ nan_inf_detection      │ FATAL    │ PASS   │ No NaN or Inf values found in 10 sampled batches │
+│ normalisation_sanity   │ WARN     │ PASS   │ Normalisation looks reasonable (mean=0.001)      │
+│ channel_ordering       │ WARN     │ PASS   │ Channel ordering looks correct (NCHW)            │
+│ label_leakage          │ FATAL    │ PASS   │ No val_dataloader provided — skipped             │
+│ split_sizes            │ INFO     │ PASS   │ train=200 samples                                │
+│ vram_estimation        │ WARN     │ INFO   │ No CUDA GPU detected — skipped                   │
+│ class_imbalance        │ WARN     │ PASS   │ Class distribution looks balanced                │
+│ shape_mismatch         │ FATAL    │ PASS   │ No model provided — skipped                      │
+│ gradient_check         │ FATAL    │ PASS   │ No model+loss provided — skipped                 │
+╰────────────────────────┴──────────┴────────┴──────────────────────────────────────────────────╯
+
+  0 fatal  0 warnings  9 passed
+
+Pre-flight passed. Safe to start training.
+```
+
+## Checks
+
+preflight runs 10 checks across three severity tiers. A **FATAL** failure exits with code 1 and blocks CI.
+
+| Check | Severity | What it catches |
+|---|---|---|
+| `nan_inf_detection` | FATAL | NaN or Inf values anywhere in sampled batches |
+| `label_leakage` | FATAL | Samples appearing in both train and val sets |
+| `shape_mismatch` | FATAL | Dataset output shape incompatible with model input |
+| `gradient_check` | FATAL | Zero gradients, dead layers, exploding gradients |
+| `normalisation_sanity` | WARN | Data that looks unnormalised (raw pixel values etc.) |
+| `channel_ordering` | WARN | NHWC tensors when PyTorch expects NCHW |
+| `vram_estimation` | WARN | Estimated peak VRAM exceeds 90% of GPU memory |
+| `class_imbalance` | WARN | Severe class imbalance beyond configurable threshold |
+| `split_sizes` | INFO | Empty or degenerate train/val splits |
+| `duplicate_samples` | INFO | Identical samples within a split |
+
+## With a model
+
+Pass a model file to enable shape, gradient, and VRAM checks:
+
+```python
+# my_model.py
+import torch.nn as nn
+model = nn.Sequential(nn.Flatten(), nn.Linear(3 * 224 * 224, 10))
+```
+
+```python
+# my_loss.py
+import torch.nn as nn
+loss_fn = nn.CrossEntropyLoss()
+```
+
+```bash
+preflight run \
+  --dataloader my_dataloader.py \
+  --model my_model.py \
+  --loss my_loss.py \
+  --val-dataloader my_val_dataloader.py
+```
+
+## Configuration
+
+Add a `.preflight.toml` to your repo root to configure thresholds and disable checks:
+
+```toml
+[thresholds]
+imbalance_threshold = 0.05
+nan_sample_batches = 20
+
+[checks]
+vram_estimation = false
+
+[ignore]
+# check = "class_imbalance"
+# reason = "intentional: rare event dataset"
+```
+
+## CI integration
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: Install preflight
+  run: pip install preflight-ml
+
+- name: Run pre-flight checks
+  run: preflight run --dataloader scripts/dataloader.py --format json
+```
+
+The `--format json` flag outputs machine-readable results. Exit code is `1` if any FATAL check fails, `0` otherwise.
+
+## List all checks
+
+```bash
+preflight checks
+```
+
+## What preflight does NOT do
+
+- It does not replace unit tests. Use pytest for code logic.
+- It does not guarantee a correct model. Passing preflight is a minimum safety bar, not a certification.
+- It does not run your full training loop. Use it as a gate before training starts.
+- It does not modify your code unless you pass `--fix`.
+
+## Roadmap
+
+- [ ] `--fix` flag — auto-patch common issues (channel ordering, normalisation)
+- [ ] Dataset snapshot + drift detection (`preflight diff baseline.json new_data.pt`)
+- [ ] Full dry-run mode (one batch through model + loss + backward)
+- [ ] Jupyter magic command (`%load_ext preflight`)
+- [ ] `preflight-monai` plugin for medical imaging checks
+- [ ] `preflight-sktime` plugin for time series checks
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). New checks are welcome — each one needs a passing test,
+a failing test, and a fix hint.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

preflight_ml-0.1.0/README.md

@@ -0,0 +1,171 @@
+# preflight
+
+> Pre-flight checks for PyTorch pipelines. Catch silent failures before they waste your GPU.
+
+[![CI](https://github.com/Rusheel86/preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/Rusheel86/preflight/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/preflight-ml)](https://pypi.org/project/preflight-ml/)
+[![Python](https://img.shields.io/pypi/pyversions/preflight-ml)](https://pypi.org/project/preflight-ml/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+Most deep learning bugs don't crash your training loop — they silently produce a garbage model.
+NaNs in your data, labels leaking between train and val, wrong channel ordering, dead gradients.
+You won't know until hours later, after the GPU bill has landed.
+
+**preflight** is a pre-training validation tool you run in 30 seconds before starting any training job.
+It's not a linter. It's a pre-flight check — the kind pilots run before the expensive thing takes off.
+
+---
+
+## Install
+
+```bash
+pip install preflight-ml
+```
+
+## Quickstart
+
+Create a small Python file that exposes your dataloader:
+
+```python
+# my_dataloader.py
+import torch
+from torch.utils.data import DataLoader, TensorDataset
+
+x = torch.randn(200, 3, 224, 224)
+y = torch.randint(0, 10, (200,))
+dataloader = DataLoader(TensorDataset(x, y), batch_size=32)
+```
+
+Run preflight:
+
+```bash
+preflight run --dataloader my_dataloader.py
+```
+
+Output:
+
+```
+preflight — pre-training check report
+╭────────────────────────┬──────────┬────────┬──────────────────────────────────────────────────╮
+│ Check                  │ Severity │ Status │ Message                                          │
+├────────────────────────┼──────────┼────────┼──────────────────────────────────────────────────┤
+│ nan_inf_detection      │ FATAL    │ PASS   │ No NaN or Inf values found in 10 sampled batches │
+│ normalisation_sanity   │ WARN     │ PASS   │ Normalisation looks reasonable (mean=0.001)      │
+│ channel_ordering       │ WARN     │ PASS   │ Channel ordering looks correct (NCHW)            │
+│ label_leakage          │ FATAL    │ PASS   │ No val_dataloader provided — skipped             │
+│ split_sizes            │ INFO     │ PASS   │ train=200 samples                                │
+│ vram_estimation        │ WARN     │ INFO   │ No CUDA GPU detected — skipped                   │
+│ class_imbalance        │ WARN     │ PASS   │ Class distribution looks balanced                │
+│ shape_mismatch         │ FATAL    │ PASS   │ No model provided — skipped                      │
+│ gradient_check         │ FATAL    │ PASS   │ No model+loss provided — skipped                 │
+╰────────────────────────┴──────────┴────────┴──────────────────────────────────────────────────╯
+
+  0 fatal  0 warnings  9 passed
+
+Pre-flight passed. Safe to start training.
+```
+
+## Checks
+
+preflight runs 10 checks across three severity tiers. A **FATAL** failure exits with code 1 and blocks CI.
+
+| Check | Severity | What it catches |
+|---|---|---|
+| `nan_inf_detection` | FATAL | NaN or Inf values anywhere in sampled batches |
+| `label_leakage` | FATAL | Samples appearing in both train and val sets |
+| `shape_mismatch` | FATAL | Dataset output shape incompatible with model input |
+| `gradient_check` | FATAL | Zero gradients, dead layers, exploding gradients |
+| `normalisation_sanity` | WARN | Data that looks unnormalised (raw pixel values etc.) |
+| `channel_ordering` | WARN | NHWC tensors when PyTorch expects NCHW |
+| `vram_estimation` | WARN | Estimated peak VRAM exceeds 90% of GPU memory |
+| `class_imbalance` | WARN | Severe class imbalance beyond configurable threshold |
+| `split_sizes` | INFO | Empty or degenerate train/val splits |
+| `duplicate_samples` | INFO | Identical samples within a split |
+
+## With a model
+
+Pass a model file to enable shape, gradient, and VRAM checks:
+
+```python
+# my_model.py
+import torch.nn as nn
+model = nn.Sequential(nn.Flatten(), nn.Linear(3 * 224 * 224, 10))
+```
+
+```python
+# my_loss.py
+import torch.nn as nn
+loss_fn = nn.CrossEntropyLoss()
+```
+
+```bash
+preflight run \
+  --dataloader my_dataloader.py \
+  --model my_model.py \
+  --loss my_loss.py \
+  --val-dataloader my_val_dataloader.py
+```
+
+## Configuration
+
+Add a `.preflight.toml` to your repo root to configure thresholds and disable checks:
+
+```toml
+[thresholds]
+imbalance_threshold = 0.05
+nan_sample_batches = 20
+
+[checks]
+vram_estimation = false
+
+[ignore]
+# check = "class_imbalance"
+# reason = "intentional: rare event dataset"
+```
+
+## CI integration
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: Install preflight
+  run: pip install preflight-ml
+
+- name: Run pre-flight checks
+  run: preflight run --dataloader scripts/dataloader.py --format json
+```
+
+The `--format json` flag outputs machine-readable results. Exit code is `1` if any FATAL check fails, `0` otherwise.
+
+## List all checks
+
+```bash
+preflight checks
+```
+
+## What preflight does NOT do
+
+- It does not replace unit tests. Use pytest for code logic.
+- It does not guarantee a correct model. Passing preflight is a minimum safety bar, not a certification.
+- It does not run your full training loop. Use it as a gate before training starts.
+- It does not modify your code unless you pass `--fix`.
+
+## Roadmap
+
+- [ ] `--fix` flag — auto-patch common issues (channel ordering, normalisation)
+- [ ] Dataset snapshot + drift detection (`preflight diff baseline.json new_data.pt`)
+- [ ] Full dry-run mode (one batch through model + loss + backward)
+- [ ] Jupyter magic command (`%load_ext preflight`)
+- [ ] `preflight-monai` plugin for medical imaging checks
+- [ ] `preflight-sktime` plugin for time series checks
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). New checks are welcome — each one needs a passing test,
+a failing test, and a fix hint.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

preflight_ml-0.1.0/preflight/__init__.py

@@ -0,0 +1,7 @@
+"""preflight — pre-flight checks for PyTorch pipelines."""
+
+from preflight.registry import CheckResult, Registry, Severity
+from preflight.runner import run_checks
+
+__version__ = "0.1.0"
+__all__ = ["Registry", "CheckResult", "Severity", "run_checks"]