BNNR

Examples Guide (Production Usage)

What you will find here

A practical guide for Python scripts under examples/ (for example examples/classification/, examples/multilabel/) with:

  • what each script demonstrates,
  • exact run commands,
  • which dashboard flow to use,
  • smoke commands for fast verification.

These paths assume a cloned repository with installs from source (pip install -e ".[…]"). They are not shipped inside the PyPI wheel; see the root README.md.

1) Classification showcase

Script:

  • examples/classification/showcase_stl10.py

What it demonstrates:

  • iterative augmentation selection,
  • XAI-driven candidates (ICD/AICD),
  • full live dashboard flow.

Full showcase

PYTHONPATH=src python3 examples/classification/showcase_stl10.py --with-dashboard

Fast smoke (CI/dev machine)

PYTHONPATH=src python3 examples/classification/showcase_stl10.py \
  --without-dashboard --no-dashboard-auto-open \
  --max-train-samples 32 --max-val-samples 16 --batch-size 16 \
  --m-epochs 1 --decisions 1

First run: STL-10 is downloaded automatically (needs network). For a shorter interactive run, the script supports --quick; see the module docstring for timings and GPU/CPU notes.

1b) Torchvision ResNet-18 → analyze (CIFAR-10)

Script:

  • examples/classification/torchvision_analyze_cifar10.py

What it demonstrates:

  • torchvision resnet18 + SimpleTorchAdapter + analyze_model (HTML report without BNNRTrainer),
  • optional short training on a CIFAR-10 subset or --checkpoint for existing weights.

Quick run (downloads CIFAR-10 once)

PYTHONPATH=src python3 examples/classification/torchvision_analyze_cifar10.py --quick

Fast smoke (CI / no download)

PYTHONPATH=src python3 examples/classification/torchvision_analyze_cifar10.py \
  --output-dir /tmp/torchvision_analyze_out --synthetic --no-xai --device cpu

See Model Analysis for the torchvision checkpoint workflow.

2) Multi-label showcase

Script:

  • examples/multilabel/multilabel_demo.py

What it demonstrates:

  • multi-label pipeline (task="multilabel"),
  • F1-samples oriented selection,
  • dashboard-compatible events and artifacts.

Full demo

PYTHONPATH=src python3 examples/multilabel/multilabel_demo.py --with-dashboard

Fast smoke

PYTHONPATH=src python3 examples/multilabel/multilabel_demo.py \
  --without-dashboard --no-dashboard-auto-open \
  --n-train 64 --n-val 32 --batch-size 16 --m-epochs 1 --decisions 1

3) Classification: full pipeline demo (synthetic)

Script:

  • examples/classification/demo_full_pipeline.py

What it demonstrates:

  • all built-in BNNR augmentations and optional torchvision / Kornia / Albumentations wrappers (when those extras are installed),
  • ICD/AICD, XAI cache, OptiCAM, and a short branch-selection loop on a tiny synthetic dataset (no dataset download).

Run from repository root (no live dashboard; typically well under a minute on CPU):

PYTHONPATH=src python3 examples/classification/demo_full_pipeline.py

Optional: install albumentations and/or kornia extras (pip install -e ".[albumentations]", pip install -e ".[gpu]") so the corresponding wrapper branches execute.

4) Lightning / Accelerate adapters (reference module)

File:

  • examples/classification/lightning_adapter.py

This file is reference code, not a main entrypoint: it defines LightningAdapter and AccelerateAdapter for use with BNNRTrainer. PyTorch Lightning and Hugging Face Accelerate are optional dependencies:

pip install pytorch-lightning accelerate

See the module docstring and inline comments for wiring; also API Reference.

5) Detection showcases

5a) Ultralytics YOLO (SDK)

Scripts:

  • examples/integrations/ultralytics_yolo_quickstart.py — copy-paste CLI for maintainers
  • examples/detection/bnnr_detection_demo.ipynb — interactive COCO128 + YOLOv8n

What they demonstrate:

  • UltralyticsDetectionAdapter (not yolo train CLI),
  • COCO128 auto-download via bnnr.example_data.ensure_coco128_yolo,
  • bbox-aware augmentations + DetectionICD/AICD,
  • mAP metrics and optional dashboard.
pip install "bnnr[ultralytics]"
PYTHONPATH=src python examples/integrations/ultralytics_yolo_quickstart.py --quick

See also Integrations.

5b) YOLO-format data + torchvision detector

Script:

  • examples/detection/showcase_yolo_coco128.py

What it demonstrates:

  • YOLO dataset layout (COCO128 data.yaml) with build_pipeline("yolo") → torchvision Faster R-CNN (not Ultralytics SDK),
  • detection-specific bbox augmentations + DetectionICD/AICD,
  • mAP tracking and dashboard.
PYTHONPATH=src python3 examples/detection/showcase_yolo_coco128.py --with-dashboard

Fast smoke:

PYTHONPATH=src python3 examples/detection/showcase_yolo_coco128.py --quick --without-dashboard

Pascal VOC 2007

Script:

  • examples/detection/showcase_voc.py

What it demonstrates:

  • torchvision-style detector with DetectionAdapter,
  • full augmentation suite (all 9 augmentation families),
  • XAI saliency generation,
  • long training runs with dashboard.
PYTHONPATH=src python3 examples/detection/showcase_voc.py --with-dashboard

Detection notebook

  • examples/detection/bnnr_detection_demo.ipynb — interactive Jupyter notebook covering adapter setup, augmentations, training, and XAI visualization.

6) Dashboard workflow for examples

For any example with --with-dashboard:

  1. Start script.
  2. Open Local URL on desktop.
  3. Scan QR for mobile view.
  4. Validate branch tree, KPI cards, samples/XAI sections.
  5. Stop server with Ctrl+C after checks.

For offline sharing:

python3 -m bnnr dashboard export --run-dir <run_dir> --out exported_dashboard

7) Example artifacts you should always verify

After each example run, verify:

  • report.json exists,
  • events.jsonl exists,
  • metrics are present for task type,
  • dashboard replay works (bnnr dashboard serve --run-dir ...).
  • dashboard.md
  • artifacts.md
  • troubleshooting.md
  • notebooks.md
  • detection.md