Metadata-Version: 2.4
Name: bnnr
Version: 0.4.2
Summary: BNNR — Train → Explain → Improve → Prove
Project-URL: Homepage, https://github.com/bnnr-team/bnnr
Project-URL: Repository, https://github.com/bnnr-team/bnnr
Project-URL: Issues, https://github.com/bnnr-team/bnnr/issues
Project-URL: Documentation, https://github.com/bnnr-team/bnnr/tree/main/docs
Project-URL: Changelog, https://github.com/bnnr-team/bnnr/blob/main/CHANGELOG.md
Author: Mateusz Walo, Diana Morzhak, Dominika Zydorczyk, Zuzanna Saczuk
License: MIT
License-File: LICENSE
Keywords: augmentation,automated-ml,computer-vision,deep-learning,explainability,grad-cam,model-quality,opticam,pytorch,saliency-maps,training,xai
Classifier: Development Status :: 4 - Beta
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: grad-cam<2.0,>=1.5.4
Requires-Dist: numpy<3.0,>=1.24.0
Requires-Dist: opencv-python<5.0,>=4.8.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: pyyaml<7.0,>=6.0.0
Requires-Dist: scikit-learn<2.0,>=1.3.0
Requires-Dist: torch<3.0,>=2.0.0
Requires-Dist: torchvision<1.0,>=0.15.0
Requires-Dist: tqdm<5.0,>=4.65.0
Requires-Dist: typer<1.0,>=0.9.0
Provides-Extra: albumentations
Requires-Dist: albumentations<2.0,>=1.3.0; extra == 'albumentations'
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115.0; extra == 'dashboard'
Requires-Dist: qrcode>=7.0; extra == 'dashboard'
Requires-Dist: uvicorn>=0.30.0; extra == 'dashboard'
Requires-Dist: websockets>=12.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: playwright>=1.40.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Requires-Dist: ultralytics<9.0,>=8.3.0; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: kornia<1.0,>=0.7.0; extra == 'gpu'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/logo.png" alt="BNNR Logo" width="180">
</p>

<p align="center">
  <a href="https://pypi.org/project/bnnr/"><img src="https://img.shields.io/pypi/v/bnnr?style=flat-square" alt="PyPI"></a>
  <a href="https://pypi.org/project/bnnr/"><img src="https://img.shields.io/pypi/pyversions/bnnr?style=flat-square" alt="Python"></a>
  <a href="https://github.com/bnnr-team/bnnr/stargazers"><img src="https://img.shields.io/github/stars/bnnr-team/bnnr?style=flat-square&logo=github" alt="GitHub stars"></a>
  <a href="https://pepy.tech/projects/bnnr"><img src="https://static.pepy.tech/personalized-badge/bnnr?period=total&amp;units=INTERNATIONAL_SYSTEM&amp;left_color=BLACK&amp;right_color=GREEN&amp;left_text=downloads" alt="PyPI downloads"></a>
  <a href="https://github.com/bnnr-team/bnnr/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bnnr-team/bnnr?style=flat-square" alt="License"></a>
  <a href="https://github.com/bnnr-team/bnnr/actions/workflows/ci.yml"><img src="https://github.com/bnnr-team/bnnr/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
</p>

<p align="center">
  <a href="https://www.bnnr.dev">
    <img src="https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/hero-promo-poster.jpg" alt="Watch BNNR demo with audio on bnnr.dev" width="720">
  </a>
</p>
<p align="center"><em>Full demo with audio (4K): <a href="https://www.bnnr.dev">bnnr.dev</a></em></p>

# 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](https://github.com/bnnr-team/bnnr/blob/main/docs/analyze.md).

Supported tasks (**v0.4.2**): single-label classification, multi-label classification, and object detection (COCO-mini / YOLO). See [Detection docs](https://github.com/bnnr-team/bnnr/blob/main/docs/detection.md).

```bash
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.

<p align="center">
  <img src="https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/icd-panel.png" alt="ICD — mask what the model looks at" width="720">
</p>
<p align="center"><strong>ICD</strong> — masks the regions the model already focuses on (highest saliency), forcing it to learn from context instead of shortcuts.</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/aicd-panel.png" alt="AICD — mask what the model ignores" width="720">
</p>
<p align="center"><strong>AICD</strong> — masks low-saliency background and irrelevant textures, sharpening focus on discriminative features.</p>

---

## 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](https://github.com/bnnr-team/bnnr/issues).

---

## Quickstart

```bash
pip install "bnnr[dashboard]"

# Zero flags — CIFAR-10 demo CNN, ICD preset, live dashboard (~1 min)
python3 -m bnnr demo
```

Interactive wizard (prompts for dataset/preset; sample limits 128/64):

```bash
python3 -m bnnr quickstart
```

Full CLI training with built-in defaults:

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

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 |
|:---:|:---:|:---:|
| ![Dashboard Overview](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-overview.png) | ![Branch Tree](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-tree.png) | ![Metrics](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-metrics.png) |

| Samples & XAI | Analysis | Dataset Insight |
|:---:|:---:|:---:|
| ![Samples and XAI](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-samples.png) | ![Analysis](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-analysis.png) | ![Dataset Insight](https://raw.githubusercontent.com/bnnr-team/bnnr/main/docs/assets/dashboard-insight.png) |

---

## 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](https://bnnr.dev) |
| Documentation | [docs/README.md](https://github.com/bnnr-team/bnnr/blob/main/docs/README.md) |
| Examples | [docs/examples.md](https://github.com/bnnr-team/bnnr/blob/main/docs/examples.md) |
| Colab (classification) | [Open in Colab](https://colab.research.google.com/github/bnnr-team/bnnr/blob/main/examples/classification/bnnr_classification_demo.ipynb) |
| API reference | [docs/api_reference.md](https://github.com/bnnr-team/bnnr/blob/main/docs/api_reference.md) |
| Model analysis (`bnnr analyze`) | [docs/analyze.md](https://github.com/bnnr-team/bnnr/blob/main/docs/analyze.md) |

---

## Python API

```python
import bnnr

result = bnnr.quick_run(model, train_loader, val_loader)
print(result.best_metrics)
```

Advanced: [Golden path](https://github.com/bnnr-team/bnnr/blob/main/docs/golden_path.md) and [API reference](https://github.com/bnnr-team/bnnr/blob/main/docs/api_reference.md).

---

## Documentation

<details>
<summary><strong>Install from source, CLI reference, full doc index</strong></summary>

### Install from source

```bash
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

```bash
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](https://github.com/bnnr-team/bnnr/blob/main/docs/getting_started.md)
- [Configuration](https://github.com/bnnr-team/bnnr/blob/main/docs/configuration.md)
- [CLI](https://github.com/bnnr-team/bnnr/blob/main/docs/cli.md)
- [Dashboard](https://github.com/bnnr-team/bnnr/blob/main/docs/dashboard.md)
- [Augmentations](https://github.com/bnnr-team/bnnr/blob/main/docs/augmentations.md)
- [Detection](https://github.com/bnnr-team/bnnr/blob/main/docs/detection.md)
- [Analyze (standalone diagnostics)](https://github.com/bnnr-team/bnnr/blob/main/docs/analyze.md)
- [Examples](https://github.com/bnnr-team/bnnr/blob/main/docs/examples.md)
- [Notebooks](https://github.com/bnnr-team/bnnr/blob/main/docs/notebooks.md)
- [Artifacts](https://github.com/bnnr-team/bnnr/blob/main/docs/artifacts.md)
- [Troubleshooting](https://github.com/bnnr-team/bnnr/blob/main/docs/troubleshooting.md)

### Requirements

- Python `>=3.10`
- Core: `torch`, `torchvision`, `numpy`, `typer`, `pydantic`, `pyyaml`, `grad-cam`
- Dashboard extra: `fastapi`, `uvicorn`, `websockets`, `qrcode`

</details>

---

## License

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