bnnr 0.5.0

BNNR: XAI-driven augmentation & diagnostics for PyTorch vision - find model failures, fix with saliency-guided augmentation (ICD/AICD), prove with auditable reports.

Website · LinkedIn

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.5.0): 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
LinkedIn	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.