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

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:

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:

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)