Metadata-Version: 2.4
Name: bnnr
Version: 0.2.6
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 :: 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.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.0.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="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?v=1" alt="PyPI"></a>
  <a href="https://pypi.org/project/bnnr/"><img src="https://img.shields.io/pypi/pyversions/bnnr?v=1" alt="Python"></a>
  <a href="https://github.com/bnnr-team/bnnr/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bnnr-team/bnnr?v=1" 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>

# BNNR (Bulletproof Neural Network Recipe)

BNNR is a PyTorch toolkit that makes vision models production-ready through a closed loop: train a model, explain its decisions with XAI, improve it with intelligent augmentation, and prove the result with structured reports and a live dashboard.

Supported tasks (**v0.2.6**):
- Single-label classification (`task: classification`)
- Multi-label classification (`task: multilabel`)
- Object detection (`task: detection`) — COCO-mini / YOLO pipelines; see `examples/detection/`

## Quickstart

### 1) Install

```bash
pip install bnnr
```

With optional extras:

```bash
pip install "bnnr[dashboard]"       # live dashboard (React + FastAPI)
pip install "bnnr[gpu]"             # GPU-accelerated augmentations (Kornia)
pip install "bnnr[albumentations]"  # Albumentations integration
```

For development from source:

```bash
git clone https://github.com/bnnr-team/bnnr.git
cd bnnr
# Dashboard UI must exist before editable install (hatch force-include).
(cd dashboard_web && npm ci && npm run build)
pip install -e ".[dev,dashboard]"
```

### Examples, notebooks, and markdown docs

The PyPI **wheel** ships the `bnnr` package only. **Runnable scripts** (`examples/`), **notebooks**, and the **documentation tree** (`docs/`) live in the [GitHub repository](https://github.com/bnnr-team/bnnr). After cloning, follow [docs/examples.md](docs/examples.md) (for example `PYTHONPATH=src python3 examples/...` from the repo root).

### 2) Create a minimal config

```bash
cat > /tmp/bnnr_quickstart.yaml <<'YAML'
m_epochs: 1
max_iterations: 1
metrics: [accuracy, f1_macro, loss]
selection_metric: accuracy
selection_mode: max
checkpoint_dir: checkpoints_quickstart
report_dir: reports_quickstart
xai_enabled: false
device: auto
seed: 42
candidate_pruning_enabled: false
YAML
```

### 3) Run a short training with live dashboard

```bash
python3 -m bnnr train \
  --config /tmp/bnnr_quickstart.yaml \
  --dataset cifar10 \
  --max-train-samples 128 \
  --max-val-samples 64 \
  --preset light \
  --with-dashboard \
  --dashboard-port 8080
```

Expected terminal markers:
- `BNNR PIPELINE SUMMARY`
- `BASELINE TRAINING`
- `TRAINING COMPLETE`
- `Report JSON    : reports_quickstart/run_.../report.json`
- `Dashboard      : http://127.0.0.1:8080/`

After training, keep the process running and open dashboard:

- desktop: `http://127.0.0.1:8080/`
- mobile: scan QR code printed in terminal (same Wi-Fi)

Stop dashboard with `Ctrl+C` when done.

### 4) Inspect the report

```bash
RUN_DIR=$(ls -1dt reports_quickstart/run_* | head -n 1)
python3 -m bnnr report "$RUN_DIR/report.json" --format summary
```

If you prefer one-shot (no live dashboard), run the same command with `--without-dashboard`.

## Main CLI commands

```bash
python3 -m bnnr --help
python3 -m bnnr train --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
```

## Python API entry points

For custom models and dataloaders:
- `BNNRConfig`
- `BNNRTrainer`
- `SimpleTorchAdapter`
- `quick_run()`

See `docs/api_reference.md` and `docs/golden_path.md`.

## Repository docs

- `docs/README.md` (documentation index and source of truth)
- `docs/getting_started.md`
- `docs/dashboard.md`
- `docs/configuration.md`
- `docs/cli.md`
- `docs/api_reference.md`
- `docs/golden_path.md`
- `docs/detection.md`
- `docs/augmentations.md`
- `docs/examples.md`
- `docs/notebooks.md`
- `docs/artifacts.md`
- `docs/troubleshooting.md`

## Requirements

From `pyproject.toml`:
- Python `>=3.10`
- Core dependencies include `torch`, `torchvision`, `numpy`, `typer`, `pydantic`, `pyyaml`
- Dashboard extra adds `fastapi`, `uvicorn`, `websockets`, `qrcode`

## License

MIT — free and open source, forever. BNNR is an academic and community-driven project built for learning, research, and fun. No paid tiers, no commercial offerings — just open-source tools for the CV community.
