Full demo with audio (4K): bnnr.dev
BNNR (Bulletproof Neural Network Recipe)
Train → Explain → Improve → Prove
BNNR automatically improves your PyTorch vision models using XAI — find what your model gets wrong, fix it with intelligent augmentation, and prove the result with structured reports and a live dashboard.
Supported tasks (v0.7.3): single-label classification, multi-label classification, and object detection (COCO-mini / YOLO). See Documentation.
Sample analyze report (no install): live HTML preview
Quickstart
pip install "bnnr[dashboard]"
# Zero flags — CIFAR-10 demo CNN, ICD preset, live dashboard (~1 min)
python3 -m bnnr demo
python3 -m bnnr quickstart
python3 -m bnnr train --dataset cifar10 --preset light --with-dashboard
Open http://127.0.0.1:8080/ for the live dashboard.
Already have a checkpoint? python3 -m bnnr analyze --model checkpoints/best.pt --data cifar10 --output ./analysis_out — docs.
XAI-driven augmentations (ICD & AICD)
BNNR uses saliency maps to guide augmentation — not random flips and crops.
ICD — masks the regions the model already focuses on (highest saliency), forcing it to learn from context instead of shortcuts.
AICD — masks low-saliency background and irrelevant textures, sharpening focus on discriminative features.
Benchmarks
| Dataset | Without BNNR | BNNR branch search | RandAugment |
|---|---|---|---|
| CIFAR-10 | 75.3% | 81.4% | 72.5% |
Median val accuracy, 3 seeds, demo CNN (methodology).
Live dashboard
Real metrics from a BNNR training run — branch tree, charts, XAI previews, and dataset insights.
| Overview | Branch Tree | Metrics |
|---|---|---|
 |
 |
 |
| Samples & XAI | Analysis | Dataset Insight |
|---|---|---|
 |
 |
 |
What makes BNNR different
- XAI-driven augmentation (ICD / AICD) — augmentations guided by saliency maps; no other PyTorch toolkit combines explainability and data augmentation this way.
- Auto-augmentation search — iterative branching keeps only augmentations that measurably improve your validation metric.
- Auditable reports — structured JSON reports with metrics, XAI heatmaps, and branch decisions for stakeholders or compliance review.
Links
| Resource | URL |
|---|---|
| Website | bnnr.dev |
| BNNR on LinkedIn | |
| Documentation | docs/README.md |
| Examples | docs/examples.md |
| Roadmap (Q2–Q3 2026) | docs/roadmap.md |
| Colab (classification) | Open in Colab |
| API reference | docs/api_reference.md |
Model analysis (bnnr analyze) |
docs/analyze.md |
| Integrations (Grad-CAM, Ultralytics YOLO) | docs/integrations.md |
| Sample analyze report (live HTML) | raw.githack.com preview |
| GitHub Discussions | Q&A and showcase |
Python API
import bnnr
result = bnnr.quick_run(model, train_loader, val_loader)
print(result.best_metrics)
Advanced: Golden path and API reference.
Documentation
Install from source, CLI reference, full doc index
Install from source
git clone https://github.com/bnnr-team/bnnr.git
cd bnnr
(cd dashboard_web && npm ci && npm run build)
pip install -e ".[dev,dashboard]"
The PyPI wheel ships the bnnr package only. Runnable scripts (examples/), notebooks, and the documentation tree (docs/) live in this repository.
Main CLI commands
python3 -m bnnr --help
python3 -m bnnr train --help
python3 -m bnnr analyze --help
python3 -m bnnr report --help
python3 -m bnnr list-datasets
python3 -m bnnr list-augmentations -v
python3 -m bnnr list-presets
python3 -m bnnr dashboard serve --run-dir reports --port 8080
python3 -m bnnr dashboard export --run-dir reports/run_YYYYMMDD_HHMMSS --output exported_dashboard
Doc index
- Getting started
- Configuration
- CLI
- Dashboard
- Augmentations
- Detection
- Analyze (standalone diagnostics)
- Examples
- Notebooks
- Artifacts
- Troubleshooting
Requirements
- Python
>=3.10 - Core:
torch,torchvision,numpy,typer,pydantic,pyyaml,grad-cam - Dashboard extra:
fastapi,uvicorn,websockets,qrcode
Citation
- BNNR software: software entry — DOI 10.5281/zenodo.20581372
- ICD or AICD: method paper — DOI 10.5281/zenodo.20581077
Full BibTeX: docs/citation.md. GitHub: Cite this repository via CITATION.cff.
License
MIT License — use BNNR freely in research, production, and commercial projects.
1 maintainer
Release files for bnnr 0.7.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bnnr-0.7.3.tar.gz | 14.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bnnr-0.7.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.1 MB
Release files / bnnr-0.7.3.tar.gz
| Download URL | bnnr-0.7.3.tar.gz |
|---|---|
| Size | 14.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e24c2d254451e592c168dd870cc0f2dcbdf5fd404aa055506b8fe725b5dcdc35
|
|
BLAKE2b-256 checksum How to use checksums |
73f62d275a8f904ef8fd53e667bea9101797eeb36e73032d79adaa3ae9c96b51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / bnnr-0.7.3-py3-none-any.whl
| Download URL | bnnr-0.7.3-py3-none-any.whl |
|---|---|
| Size | 1.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
186d4e9a8dedae1c0ad5a57010a102038daab7da1d9ec7f04e853286525dc570
|
|
BLAKE2b-256 checksum How to use checksums |
6f1ae979bf8e1389efcb4b772b44a41d16b56f93ab87f28c432c134f914a7230
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency log
