bnnr 0.4.0

BNNR — Train → Explain → Improve → Prove

Full demo with audio (4K): bnnr.dev

BNNR (Bulletproof Neural Network Recipe)

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.

Already have a trained model? Run bnnr analyze for a full diagnostic report (metrics, XAI, failure patterns, recommendations) — no retraining. See Model analysis docs.

Supported tasks (v0.4.0): single-label classification, multi-label classification, and object detection (COCO-mini / YOLO). See Detection docs.

python3 -m bnnr analyze --model checkpoints/best.pt --data cifar10 --output ./analysis_out

---

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	Baseline	+ BNNR	Gain
Coming soon	—	—	—

Reproducible benchmark results on CIFAR-10, STL-10, and Fashion-MNIST will be published here. Track progress in GitHub Issues.

---

Quickstart

pip install "bnnr[dashboard]"

python3 -m bnnr train --dataset cifar10 --preset light --with-dashboard

Interactive wizard (same built-in defaults, sample limits 128/64):

python3 -m bnnr quickstart

Open http://127.0.0.1:8080/ for the live dashboard (QR code in terminal for mobile on the same Wi-Fi).

Advanced: pass --config path.yaml to override defaults.

---

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
Documentation	docs/README.md
Examples	docs/examples.md
Colab (classification)	Open in Colab
API reference	docs/api_reference.md
Model analysis (bnnr analyze)	docs/analyze.md

---

Python API

from bnnr import quick_run, BNNRConfig

result = quick_run(
    model,
    train_loader,
    val_loader,
    config=BNNRConfig(m_epochs=5, max_iterations=3, device="auto"),
)
print(result.best_metrics)

See Golden path and API reference for custom adapters and detection.

---

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 --out 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

---

License

MIT License — use BNNR freely in research, production, and commercial projects.