Atomattias/BatterySwapAI2026-NoraAI

NoraAI — BatterySwapAI 2026

Participant-authored submission for the BatterySwapAI 2026 Challenge.

Hub model: Atomattias/BatterySwapAI2026-NoraAI

This repository contains everything needed to reproduce the stored models and run inference / plan generation used by the competition runner.

Approach (short)

1. Prognostics: sklearn HistGradientBoostingRegressor quantile models (P10 / P50 / P90) for remaining useful life (RUL).
2. Planning: greedy urgent-first work-order planner under travel / worker constraints (OR-Tools available for VRPTW experiments; competition default is greedy for runtime).
3. Digital twin (local research pipeline): open-loop + twin stress-testing of scheduling policies against operational cost (see src/simulation/). Twin code supports policy selection; the competition entry point is script.py → NoraPlanner.

Repository layout

Path	Role
script.py	Hugging Face / Docker entry point
src/features/	Health-indicator feature extraction
src/prognostics/	RUL labels, sklearn quantile training, predictor
src/scheduling/	Priority scoring + greedy / hybrid / VRPTW planners
src/submission/nora_planner.py	Official Planner implementation
src/simulation/	Evaluation, digital twin, official metric helpers
submission/nora_planner.pickle	Pickled planner stub loaded at runtime
data/processed/models/	Trained sklearn quantile model + config
scripts/train_sklearn_submission.py	Train + refresh stored model artifacts
Dockerfile	Competition container build
requirements.txt	Declared dependencies (runtime image may ignore extras)
LICENSE	MIT (participant-authored code)

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
# Optional local-only extras (training / dashboards / tests):
pip install -r requirements.dev.txt

Competition dataset (gated): follow organizer instructions for batteryswapaichallenge/BatterySwapAI-2026-Test-Train (or the public split mounted by the runner). Locally we expect data under data/real/{public,private,train} or /tmp/data in the competition image.

Preprocessing

1. Place / mount the official split folders (locations, metrics, EOL, scenarios).
2. For local retraining, build a processed feature table (parquet) used by scripts/train_sklearn_submission.py. The competition image does not ship features.parquet; at inference time NoraPlanner extracts last-window health indicators on the fly from truncated scenario metrics (src/features/health_indicators.py).

Typical local feature build (research pipeline):

# After ingesting raw/official data into data/raw and data/processed
python -m scripts.build_features   # if using the full local Makefile pipeline
# or follow Makefile targets: make ingest-real / make features (when available)

Training / stored-model generation

The submission model is sklearn-only (competition allowlist friendly).

# Requires local processed features + batteries.csv
python scripts/train_sklearn_submission.py

This writes:

• data/processed/models/sklearn_quantile.joblib
• data/processed/models/config.joblib (primary: sklearn)
• submission/nora_planner.pickle

Environment knobs used by the training script (defaults shown):

• SKLEARN_MAX_BATTERIES=200
• SKLEARN_SUBSAMPLE_EVERY_N=48
• SKLEARN_MAX_ROWS=30000

Inference (competition / Docker)

The runner executes:

python3 script.py

script.py loads NoraPlanner, calls batteryswap_public.utils.make_submissions, and writes submission.csv.

Environment variables:

Variable	Default	Meaning
BATTERYSWAP_DATASET_PATH	/tmp/data	Dataset root with split folders
BATTERYSWAP_SPLITS	public,private	Comma-separated splits
BATTERYSWAP_SUBMISSION_PATH	submission.csv	Output path
BATTERYSWAP_PLANNER_PATH	submission/nora_planner.pickle	Optional pickle path

Local Docker check:

docker build -t batteryswapai-noraai .
docker run --name batteryswapai -v ./data/real:/tmp/data:ro batteryswapai-noraai
docker cp batteryswapai:/app/submission.csv ./docker_submission.csv

Planner behavior (scoring window)

Official evaluation only executes plan days inside planning_window_days, but plans must still list every battery. NoraPlanner schedules a small set of lowest-RUL batteries inside the window and parks the rest on days after the window so the plan stays complete without paying early-swap cost on healthy batteries.

Digital twin (optional, local)

For policy stress-testing / reports (not required by script.py):

# Examples from the research Makefile / scripts
python scripts/run_twin_shootout.py
python scripts/run_twin_calibration.py
python scripts/select_submission_policy.py

See docs/DIGITAL_TWIN.md and docs/PRIORITY_B_SPRINT.md when present in a full checkout.

Dependencies, versions, and licenses

Participant code in this repository is MIT (LICENSE).

Competition / runtime stack

requirements.txt pins minimum versions. Versions observed in the local repro environment used to prepare artifacts:

Package	Version (local)	License (upstream)
batteryswap_public	0.3.4	Provided by organizers (competition package)
scikit-learn	1.9.0	BSD-3-Clause
numpy	2.5.2	BSD-3-Clause
scipy	1.18.1	BSD-3-Clause
pandas	2.3.3	BSD-3-Clause
joblib	1.5.3	BSD-3-Clause
pyarrow	25.0.1	Apache-2.0
fastparquet	2026.5.0	Apache-2.0
ortools	9.15.6755	Apache-2.0
lifelines	0.30.3	MIT
huggingface_hub	1.28.0	Apache-2.0
pydantic-settings	2.15.0	MIT
structlog	26.1.0	Apache-2.0 / MIT (upstream)
tqdm	4.70.0	MPL-2.0 / MIT (upstream)

Additional packages listed in requirements.txt (e.g. torch, plotly, polars, statsmodels) may be unused by the sklearn submission path; the competition Docker note states custom requirement changes may be ignored in favor of the organizer image allowlist.

Local-only extras (requirements.dev.txt): LightGBM, scikit-survival, Streamlit, matplotlib, pytest — not required for the HF script.py path.

Pretrained models

No external pretrained neural checkpoints. The only stored model is the sklearn quantile ensemble trained by scripts/train_sklearn_submission.py and shipped under data/processed/models/.

External datasets

• BatterySwapAI 2026 sensor / location / travel / EOL data from the organizers (Hugging Face dataset batteryswapaichallenge/BatterySwapAI-2026-Test-Train and competition mounts). Access and license terms are those of the challenge organizers; this repo does not redistribute the raw gated dataset.

Security

This repository must not contain passwords, API tokens, private keys, or .env secrets. If a token was ever exposed via a local git remote URL, revoke it on Hugging Face and rotate credentials.

Citation / contact

Team / HF user: Atomattias
Challenge: BatterySwapAI 2026 (NORA)