BatterySwapAI submission 001

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+.env
+
+data/
+artifacts/
+submission.csv
+*.log
+
+*.joblib
+!submission_artifacts/planner.joblib

Dockerfile

@@ -0,0 +1,16 @@
+FROM huggingface/competitions:latest
+
+ENV BATTERYSWAP_SPLITS=train
+ENV BATTERYSWAP_SUBMISSION_PATH=submission.csv
+ENV PYTHONPATH=/app/src
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY src/ ./src/
+COPY submission_artifacts/ ./submission_artifacts/
+COPY script.py ./
+
+CMD python3 script.py

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CarlAlbertCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,49 @@
 ---
 license: mit
 ---
+
+# BatterySwapAI 2026
+
+MnesisLab submission repository for the BatterySwapAI 2026 Challenge.
+
+## Runtime
+
+The evaluator runs:
+
+```bash
+python3 script.py
+```
+
+The trained planner is stored at:
+
+```text
+submission_artifacts/planner.joblib
+```
+
+The program reads competition data from `/tmp/data` and writes `submission.csv`.
+
+No network access is required during evaluation.
+
+## Model
+
+The solution uses past battery voltage and temperature observations to estimate near-term failure risk and remaining useful life.
+
+The planner then schedules replacement work using the published timing, travel, worker-capacity, and replacement costs.
+
+## Verification
+
+The stored artifact produced this train-split sanity score with the competition Docker environment:
+
+```text
+462.11682986111094
+```
+
+The device-held-out local validation cost is:
+
+```text
+1325.70
+```
+
+The second value is a local validation result. It is not a competition leaderboard score.
+
+See `REPRODUCIBILITY.md` for the training and validation procedure.

REPRODUCIBILITY.md

@@ -0,0 +1,137 @@
+# Reproduction
+
+## Data
+
+Training uses only the public BatterySwapAI 2026 dataset:
+
+```text
+batteryswapaichallenge/BatterySwapAI-2026-Public
+```
+
+Dataset revision:
+
+```text
+7f423ac4cb6ab146f7ea7a37872eb4dfc3c9705c
+```
+
+The competition dataset is not stored in this repository.
+
+Download the public dataset with:
+
+```bash
+hf download batteryswapaichallenge/BatterySwapAI-2026-Public \
+  --repo-type dataset \
+  --revision 7f423ac4cb6ab146f7ea7a37872eb4dfc3c9705c \
+  --local-dir data/raw
+```
+
+The training split must be available at:
+
+```text
+data/raw/train
+```
+
+## Environment
+
+Use Python 3.10 or later.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e . -r requirements.dev.txt
+```
+
+## Training
+
+Run:
+
+```bash
+python scripts/train_submission.py
+```
+
+Training uses random seed `2026`.
+
+The command creates:
+
+```text
+submission_artifacts/planner.joblib
+submission_artifacts/planner.json
+```
+
+No pretrained model or external training dataset is used.
+
+## Validation
+
+Run:
+
+```bash
+python scripts/validate_submission.py
+```
+
+Validation groups complete battery IDs so one battery does not occur in both the training and validation side of an outer fold.
+
+The stored planner configuration includes:
+
+```text
+event_risk_threshold = 0.5
+prediction_offset_days = -5.0
+risk_calibration_scale = 1.5
+building_batch_window_days = 4
+capacity_lookahead_days = 21
+capacity_operational_cost_weight = 1.5
+```
+
+The current device-held-out validation cost is:
+
+```text
+1325.70
+```
+
+This is a local validation result, not a leaderboard score.
+
+## Stored artifact
+
+SHA-256:
+
+```text
+8d75f66c4cabf06c71eefc1714db726b86d02f6108829c51caabde89b0b794ff
+```
+
+Training rows:
+
+```text
+19890
+```
+
+Training devices:
+
+```text
+458
+```
+
+## Competition-format verification
+
+Build:
+
+```bash
+docker build -t batteryswapai-2026 .
+```
+
+Run the public train split:
+
+```bash
+docker run --rm \
+  -e BATTERYSWAP_SPLITS=train \
+  -e BATTERYSWAP_SUBMISSION_PATH=submission.csv \
+  -v "$(pwd)/data/raw:/tmp/data" \
+  batteryswapai-2026 \
+  conda run --no-capture-output -p /app/env /bin/bash -c \
+  "python3 script.py && python3 -m batteryswap_public.metric"
+```
+
+The verified train cost of the stored artifact is:
+
+```text
+462.11682986111094
+```

THIRD_PARTY_LICENSES.md

@@ -0,0 +1,18 @@
+# Third-party licenses
+
+This table lists the direct third-party packages used by the project. No third-party package source code or external dataset is copied into this repository.
+
+| Package | Declared / verified version | Source | License |
+|---|---:|---|---|
+| NumPy | >=2.2.0 / 2.5.2 training, 2.2.6 parity | https://numpy.org/ | BSD-3-Clause and bundled permissive licenses |
+| pandas | >=2.3.0 / 3.0.5 training, 2.3.3 parity | https://pandas.pydata.org/ | BSD-3-Clause |
+| scikit-learn | >=1.7.0 / 1.9.0 training, 1.7.2 parity | https://scikit-learn.org/ | BSD-3-Clause |
+| joblib | >=1.5.3 / 1.5.3 | https://joblib.readthedocs.io/ | BSD-3-Clause |
+| fastparquet | >=2026.5.0 / 2026.5.0 | https://github.com/dask/fastparquet | Apache-2.0 |
+| pydantic-settings | >=2.14.1 / 2.15.0 parity | https://github.com/pydantic/pydantic-settings | MIT |
+| structlog | >=25.5.0 / 26.1.0 parity | https://www.structlog.org/ | MIT or Apache-2.0 |
+| huggingface-hub | >=0.34 | https://github.com/huggingface/huggingface_hub | Apache-2.0 |
+| PyYAML | >=6.0 | https://pyyaml.org/ | MIT |
+| batteryswap_public | >=0.1.0 / 0.3.4 | https://pypi.org/project/batteryswap-public/ | Organizer package; PyPI metadata does not declare a license |
+
+`batteryswap_public` is required by the official example and evaluation interface. Its PyPI metadata does not state a license. Obtain written organizer confirmation before the competition deadline.

pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "batteryswapai-2026"
+version = "0.1.0"
+description = "BatterySwapAI 2026 submission"
+requires-python = ">=3.10"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-q"

requirements.dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+huggingface-hub>=0.34
+pyarrow==25.0.1
+pytest>=8.3
+pyyaml>=6.0

requirements.txt

@@ -0,0 +1,9 @@
+# Runtime packages used by the competition submission.
+batteryswap_public>=0.1.0
+fastparquet>=2026.5.0
+joblib>=1.5.3
+numpy>=2.2.0
+pandas>=2.3.0
+pydantic-settings>=2.14.1
+scikit-learn>=1.7.0
+structlog>=25.5.0

script.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import joblib
+import pandas as pd
+from batteryswap_public.utils import iterate_scenarios, load_dataset
+
+from batteryswapai.competition_features import build_daily_features, scenario_snapshot
+
+
+def main() -> None:
+    dataset_path = Path(os.environ.get("BATTERYSWAP_DATASET_PATH", "/tmp/data"))
+    artifact_path = Path(
+        os.environ.get("BATTERYSWAP_PLANNER_PATH", "submission_artifacts/planner.joblib")
+    )
+    splits = os.environ.get("BATTERYSWAP_SPLITS", "public,private").split(",")
+    output_path = Path(os.environ.get("BATTERYSWAP_SUBMISSION_PATH", "submission.csv"))
+    planner = joblib.load(artifact_path)
+
+    plans = []
+    for split in splits:
+        locations, timeseries, hidden_eol_times, scenarios = load_dataset(dataset_path / split)
+        daily = build_daily_features(timeseries)
+        for scenario, locs, _, _ in iterate_scenarios(
+            locations, timeseries, hidden_eol_times, scenarios
+        ):
+            snapshot = scenario_snapshot(daily, locs, scenario["name"], scenario["start_time"])
+            plan = planner.plan_snapshot(
+                snapshot,
+                locs,
+                scenario["travel_costs"],
+                scenario["settings"],
+                scenario["start_time"],
+            )
+            plan["split"] = split
+            plan["scenario"] = scenario["name"]
+            plans.append(plan)
+
+    submission = pd.concat(plans, ignore_index=True)
+    submission.to_csv(output_path, index=False)
+    if not output_path.exists():
+        raise RuntimeError(f"Submission was not created: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/train_submission.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.metadata
+import json
+from pathlib import Path
+
+import joblib
+import pandas as pd
+from batteryswap_public.evaluate import evaluate_plan
+from batteryswap_public.utils import iterate_scenarios, load_dataset
+
+from batteryswapai.competition_features import (
+    attach_training_targets,
+    build_daily_features,
+    scenario_snapshot,
+)
+from batteryswapai.competition_model import fit_event_time_model
+from batteryswapai.competition_planner import CompetitionPlanner, PlannerPolicy
+
+
+DATASET_REVISION = "7f423ac4cb6ab146f7ea7a37872eb4dfc3c9705c"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dataset-path", type=Path, default=Path("data/raw/train"))
+    parser.add_argument(
+        "--artifact", type=Path, default=Path("submission_artifacts/planner.joblib")
+    )
+    parser.add_argument("--quantile", type=float, default=0.05)
+    parser.add_argument("--event-risk-threshold", type=float, default=0.50)
+    parser.add_argument("--prediction-offset-days", type=float, default=-5.0)
+    parser.add_argument("--calibration-folds", type=int, default=5)
+    parser.add_argument("--skip-evaluation", action="store_true")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    locations, timeseries, eol_times, scenarios = load_dataset(args.dataset_path)
+    daily = build_daily_features(timeseries)
+
+    snapshots = []
+    for scenario, locs, _, _ in iterate_scenarios(locations, timeseries, eol_times, scenarios):
+        snapshot = scenario_snapshot(daily, locs, scenario["name"], scenario["start_time"])
+        snapshot = attach_training_targets(
+            snapshot,
+            eol_times,
+            unobserved_eol_days=float(scenario["settings"].unobserved_eol_days),
+        )
+        snapshots.append(snapshot)
+    training = pd.concat(snapshots, ignore_index=True)
+
+    model = fit_event_time_model(
+        training,
+        quantile=args.quantile,
+        dataset_revision=DATASET_REVISION,
+        calibration_folds=args.calibration_folds,
+    )
+    planner = CompetitionPlanner(
+        model,
+        PlannerPolicy(
+            event_risk_threshold=args.event_risk_threshold,
+            prediction_offset_days=args.prediction_offset_days,
+            use_expected_cost=True,
+            capacity_lookahead_days=21,
+        ),
+    )
+    args.artifact.parent.mkdir(parents=True, exist_ok=True)
+    joblib.dump(planner, args.artifact, compress=3)
+
+    report = {
+        "dataset_revision": DATASET_REVISION,
+        "artifact": args.artifact.as_posix(),
+        "quantile": args.quantile,
+        "event_risk_threshold": args.event_risk_threshold,
+        "prediction_offset_days": args.prediction_offset_days,
+        "calibration_folds": args.calibration_folds,
+        "planner_policy": {
+            "expected_cost": True,
+            "risk_calibration_scale": planner.policy.risk_calibration_scale,
+            "expected_service_cost_hours": planner.policy.expected_service_cost_hours,
+            "expected_gain_margin": planner.policy.expected_gain_margin,
+            "prediction_offset_days": planner.policy.prediction_offset_days,
+            "stale_risk_cutoff_days": planner.policy.stale_risk_cutoff_days,
+            "recent_gap_risk_factor": planner.policy.recent_gap_risk_factor,
+            "stale_risk_factor": planner.policy.stale_risk_factor,
+            "building_batch_window_days": planner.policy.building_batch_window_days,
+            "capacity_lookahead_days": planner.policy.capacity_lookahead_days,
+            "capacity_operational_cost_weight": planner.policy.capacity_operational_cost_weight,
+            "exact_route_capacity": True,
+        },
+        "training_rows": len(training),
+        "training_devices": int(training["battery"].nunique()),
+        "features": model.feature_columns,
+        "artifact_sha256": hashlib.sha256(args.artifact.read_bytes()).hexdigest(),
+        "runtime_versions": {
+            package: importlib.metadata.version(package)
+            for package in (
+                "batteryswap_public",
+                "fastparquet",
+                "joblib",
+                "numpy",
+                "pandas",
+                "scikit-learn",
+            )
+        },
+        "validation_report": "artifacts/submission_cv_final.json",
+    }
+
+    if not args.skip_evaluation:
+        scores = []
+        for scenario, locs, _, not_dead in iterate_scenarios(
+            locations, timeseries, eol_times, scenarios
+        ):
+            snapshot = scenario_snapshot(daily, locs, scenario["name"], scenario["start_time"])
+            plan = planner.plan_snapshot(
+                snapshot,
+                locs,
+                scenario["travel_costs"],
+                scenario["settings"],
+                scenario["start_time"],
+            )
+            _, _, score = evaluate_plan(
+                plan,
+                locs,
+                scenario["travel_costs"],
+                scenario["settings"],
+                eol_times=not_dead,
+                start_time=pd.Timestamp(scenario["start_time"]),
+                verbose=0,
+            )
+            scores.append(score)
+        report["optimistic_train_score"] = pd.concat(scores, axis=1).mean(axis=1).to_dict()
+
+    report_path = args.artifact.with_suffix(".json")
+    report_path.write_text(json.dumps(report, indent=2, default=float), encoding="utf-8")
+    print(json.dumps(report, indent=2, default=float))
+
+
+if __name__ == "__main__":
+    main()

scripts/validate_submission.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from batteryswap_public.evaluate import evaluate_plan
+from batteryswap_public.utils import iterate_scenarios, load_dataset
+from sklearn.metrics import average_precision_score, roc_auc_score
+from sklearn.model_selection import GroupKFold
+
+from batteryswapai.competition_features import (
+    attach_training_targets,
+    build_daily_features,
+    scenario_snapshot,
+)
+from batteryswapai.competition_model import fit_event_time_model
+from batteryswapai.competition_planner import CompetitionPlanner, PlannerPolicy
+from train_submission import DATASET_REVISION
+
+
+def _numbers(value: str) -> list[float]:
+    return [float(item.strip()) for item in value.split(",") if item.strip()]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dataset-path", type=Path, default=Path("data/raw/train"))
+    parser.add_argument("--folds", type=int, default=5)
+    parser.add_argument("--quantile", type=float, default=0.05)
+    parser.add_argument("--inner-calibration-folds", type=int, default=3)
+    parser.add_argument("--risk-scales", default="1.50")
+    parser.add_argument("--gain-margins", default="10")
+    parser.add_argument("--service-costs", default="2")
+    parser.add_argument("--offsets", default="-5")
+    parser.add_argument(
+        "--output", type=Path, default=Path("artifacts/submission_cv_final.json")
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    locations, timeseries, eol_times, scenarios = load_dataset(args.dataset_path)
+    daily = build_daily_features(timeseries)
+
+    snapshots = []
+    scenario_inputs = {}
+    for scenario, locs, _, not_dead in iterate_scenarios(
+        locations, timeseries, eol_times, scenarios
+    ):
+        snapshot = scenario_snapshot(daily, locs, scenario["name"], scenario["start_time"])
+        snapshot = attach_training_targets(
+            snapshot,
+            eol_times,
+            unobserved_eol_days=float(scenario["settings"].unobserved_eol_days),
+        )
+        snapshots.append(snapshot)
+        scenario_inputs[scenario["name"]] = (scenario, locs, not_dead)
+    training = pd.concat(snapshots, ignore_index=True)
+
+    oof_risk = np.full(len(training), np.nan)
+    oof_rul = np.full(len(training), np.nan)
+    splitter = GroupKFold(n_splits=args.folds)
+    groups = training["battery"].astype(str)
+    for fold_number, (train_index, valid_index) in enumerate(
+        splitter.split(training, groups=groups), start=1
+    ):
+        model = fit_event_time_model(
+            training.iloc[train_index],
+            quantile=args.quantile,
+            dataset_revision=DATASET_REVISION,
+            random_state=2026 + fold_number,
+            calibration_folds=args.inner_calibration_folds,
+        )
+        valid = training.iloc[valid_index]
+        oof_risk[valid_index] = model.predict_event_risk(valid)
+        oof_rul[valid_index] = model.predict_rul(valid)
+
+    due = (
+        training["event_observed"].astype(bool)
+        & training["target_rul_days"].between(0.0, 42.0)
+    ).astype(int)
+    classification = {
+        "positive_rows": int(due.sum()),
+        "total_rows": len(due),
+        "roc_auc": float(roc_auc_score(due, oof_risk)),
+        "average_precision": float(average_precision_score(due, oof_risk)),
+    }
+    adjusted_oof_risk = oof_risk.copy()
+    gaps = pd.to_numeric(training["data_gap_days"], errors="coerce").to_numpy(dtype=float)
+    recent_gap = (gaps > 0.0) & (gaps <= 7.0)
+    stale = (gaps > 7.0) | ~np.isfinite(gaps)
+    adjusted_oof_risk[recent_gap] *= 0.75
+    adjusted_oof_risk[stale] *= 0.10
+    classification["freshness_adjusted_roc_auc"] = float(
+        roc_auc_score(due, adjusted_oof_risk)
+    )
+    classification["freshness_adjusted_average_precision"] = float(
+        average_precision_score(due, adjusted_oof_risk)
+    )
+
+    observed = training["event_observed"].astype(bool)
+    observed_rul_error = np.abs(
+        oof_rul[observed] - training.loc[observed, "target_rul_days"].to_numpy()
+    )
+    due_mask = due.astype(bool).to_numpy()
+    due_rul_error = np.abs(
+        oof_rul[due_mask] - training.loc[due_mask, "target_rul_days"].to_numpy()
+    )
+    classification["all_observed_rul_mae_days"] = float(np.mean(observed_rul_error))
+    classification["due_within_horizon_rul_mae_days"] = float(np.mean(due_rul_error))
+
+    policy_results = []
+    placeholder_model = model
+    for risk_scale in _numbers(args.risk_scales):
+        for gain_margin in _numbers(args.gain_margins):
+            for service_cost in _numbers(args.service_costs):
+                for offset in _numbers(args.offsets):
+                    planner = CompetitionPlanner(
+                        placeholder_model,
+                        PlannerPolicy(
+                            event_risk_threshold=0.50,
+                            prediction_offset_days=offset,
+                            use_expected_cost=True,
+                            risk_calibration_scale=risk_scale,
+                            expected_service_cost_hours=service_cost,
+                            expected_gain_margin=gain_margin,
+                            capacity_lookahead_days=21,
+                        ),
+                    )
+                    scores = []
+                    scheduled_counts = []
+                    for scenario_name, (scenario, locs, not_dead) in scenario_inputs.items():
+                        mask = training["scenario"].eq(scenario_name).to_numpy()
+                        snapshot = training.loc[mask]
+                        risk = oof_risk[mask]
+                        rul = oof_rul[mask]
+                        plan = planner.plan_snapshot(
+                            snapshot,
+                            locs,
+                            scenario["travel_costs"],
+                            scenario["settings"],
+                            scenario["start_time"],
+                            predicted_rul=rul,
+                            predicted_risk=risk,
+                        )
+                        start = pd.Timestamp(scenario["start_time"])
+                        horizon_end = start + pd.Timedelta(
+                            days=scenario["settings"].planning_window_days
+                        )
+                        scheduled_counts.append(int(plan["day"].le(horizon_end).sum()))
+                        _, _, score = evaluate_plan(
+                            plan,
+                            locs,
+                            scenario["travel_costs"],
+                            scenario["settings"],
+                            eol_times=not_dead,
+                            start_time=start,
+                            verbose=0,
+                        )
+                        scores.append(score)
+                    mean_score = pd.concat(scores, axis=1).mean(axis=1)
+                    policy_results.append(
+                        {
+                            "risk_calibration_scale": risk_scale,
+                            "expected_gain_margin": gain_margin,
+                            "expected_service_cost_hours": service_cost,
+                            "prediction_offset_days": offset,
+                            "stale_risk_cutoff_days": planner.policy.stale_risk_cutoff_days,
+                            "recent_gap_risk_factor": planner.policy.recent_gap_risk_factor,
+                            "stale_risk_factor": planner.policy.stale_risk_factor,
+                            "building_batch_window_days": planner.policy.building_batch_window_days,
+                            "capacity_operational_cost_weight": planner.policy.capacity_operational_cost_weight,
+                            "mean_scheduled_batteries": float(np.mean(scheduled_counts)),
+                            **{key: float(value) for key, value in mean_score.items()},
+                        }
+                    )
+
+    policy_results.sort(key=lambda item: item["total_cost"])
+    report = {
+        "dataset_revision": DATASET_REVISION,
+        "folds": args.folds,
+        "inner_calibration_folds": args.inner_calibration_folds,
+        "quantile": args.quantile,
+        "classification": classification,
+        "policies": policy_results,
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(report, indent=2), encoding="utf-8")
+    predictions = training[["scenario", "battery", "target_rul_days", "event_observed"]].copy()
+    predictions["oof_event_risk"] = oof_risk
+    predictions["oof_rul_days"] = oof_rul
+    predictions.to_csv(args.output.with_suffix(".csv"), index=False)
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()

src/batteryswapai/__init__.py

@@ -0,0 +1,3 @@
+"""BatterySwapAI 2026 competition toolkit."""
+
+__version__ = "0.1.0"

src/batteryswapai/competition_features.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+import pandas as pd
+
+
+ROLLING_WINDOWS_DAYS = (3, 7, 14, 30, 60, 90, 180, 365)
+
+NON_FEATURE_COLUMNS = {
+    "scenario",
+    "scenario_time",
+    "device_id",
+    "battery",
+    "building",
+    "room",
+    "start_time",
+    "end_time",
+    "effective_eol",
+    "target_rul_days",
+    "event_observed",
+}
+
+
+def _as_columns(timeseries: pd.DataFrame) -> pd.DataFrame:
+    frame = timeseries
+    if "device_id" not in frame.columns or "end_time" not in frame.columns:
+        frame = frame.reset_index()
+    required = {"device_id", "end_time", "voltage", "temperature"}
+    missing = required - set(frame.columns)
+    if missing:
+        raise ValueError(f"Battery time series is missing columns: {sorted(missing)}")
+    return frame[["device_id", "end_time", "voltage", "temperature"]].copy()
+
+
+def build_daily_features(
+    timeseries: pd.DataFrame,
+    windows: Iterable[int] = ROLLING_WINDOWS_DAYS,
+) -> pd.DataFrame:
+    """Build past-only daily features for all scenarios."""
+
+    frame = _as_columns(timeseries)
+    frame["end_time"] = pd.to_datetime(frame["end_time"], errors="coerce")
+    frame["voltage"] = pd.to_numeric(frame["voltage"], errors="coerce")
+    frame["temperature"] = pd.to_numeric(frame["temperature"], errors="coerce")
+    frame = frame.dropna(subset=["device_id", "end_time", "voltage"])
+    frame["day"] = frame["end_time"].dt.floor("D")
+
+    daily = (
+        frame.groupby(["device_id", "day"], observed=True, sort=True)
+        .agg(
+            voltage_median=("voltage", "median"),
+            voltage_mean=("voltage", "mean"),
+            voltage_min=("voltage", "min"),
+            voltage_max=("voltage", "max"),
+            voltage_std=("voltage", "std"),
+            temperature_median=("temperature", "median"),
+            temperature_std=("temperature", "std"),
+            observations_day=("voltage", "size"),
+        )
+        .reset_index()
+        .sort_values(["device_id", "day"])
+        .reset_index(drop=True)
+    )
+
+    stable = frame[frame["temperature"].between(10.0, 30.0, inclusive="both")]
+    stable_daily = (
+        stable.groupby(["device_id", "day"], observed=True, sort=True)["voltage"]
+        .median()
+        .rename("stable_voltage_median")
+        .reset_index()
+    )
+    daily = daily.merge(stable_daily, on=["device_id", "day"], how="left")
+    daily["stable_voltage_median"] = daily["stable_voltage_median"].fillna(daily["voltage_median"])
+
+    grouped = daily.groupby("device_id", observed=True, sort=False)
+    first_day = grouped["day"].transform("min")
+    daily["history_days"] = (daily["day"] - first_day).dt.total_seconds() / 86400.0
+    daily["days_since_previous"] = grouped["day"].diff().dt.total_seconds() / 86400.0
+
+    for window in tuple(int(value) for value in windows):
+        min_periods = max(2, window // 4)
+        rolled = (
+            grouped["stable_voltage_median"]
+            .rolling(window, min_periods=min_periods)
+            .agg(["mean", "min", "max", "std"])
+            .reset_index(level=0, drop=True)
+            .reindex(daily.index)
+        )
+        for statistic in ("mean", "min", "max", "std"):
+            daily[f"voltage_{statistic}_{window}d"] = rolled[statistic]
+
+        daily[f"temperature_mean_{window}d"] = (
+            grouped["temperature_median"]
+            .rolling(window, min_periods=min_periods)
+            .mean()
+            .reset_index(level=0, drop=True)
+            .reindex(daily.index)
+        )
+        lag_voltage = grouped["stable_voltage_median"].shift(window - 1)
+        lag_day = grouped["day"].shift(window - 1)
+        span = (daily["day"] - lag_day).dt.total_seconds() / 86400.0
+        daily[f"voltage_slope_{window}d"] = (
+            daily["stable_voltage_median"] - lag_voltage
+        ) / span.replace(0.0, np.nan)
+        daily[f"span_{window}d"] = span
+
+    daily["voltage_recent_vs_30d"] = daily["voltage_mean_7d"] - daily["voltage_mean_30d"]
+    daily["voltage_recent_vs_90d"] = daily["voltage_mean_14d"] - daily["voltage_mean_90d"]
+    daily["voltage_range_day"] = daily["voltage_max"] - daily["voltage_min"]
+    return daily
+
+
+def scenario_snapshot(
+    daily_features: pd.DataFrame,
+    locations: pd.DataFrame,
+    scenario_name: str,
+    scenario_time: pd.Timestamp | str,
+) -> pd.DataFrame:
+    """Get the last feature row visible at the scenario time."""
+
+    start = pd.Timestamp(scenario_time).normalize()
+    alive = locations.copy()
+    if "battery" not in alive.columns:
+        raise ValueError("locations must contain a battery column")
+
+    available = daily_features[daily_features["day"] <= start]
+    latest = available.groupby("device_id", observed=True, sort=False).tail(1)
+    snapshot = alive.merge(latest, left_on="battery", right_on="device_id", how="left")
+    snapshot["scenario"] = scenario_name
+    snapshot["scenario_time"] = start
+
+    snapshot["location_age_days"] = (
+        start - pd.to_datetime(snapshot["start_time"], errors="coerce").dt.normalize()
+    ).dt.total_seconds() / 86400.0
+    snapshot["data_gap_days"] = (
+        start - pd.to_datetime(snapshot["day"], errors="coerce")
+    ).dt.total_seconds() / 86400.0
+    snapshot["censor_proxy_rul_days"] = (
+        pd.to_datetime(snapshot["end_time"], errors="coerce").dt.normalize()
+        + pd.Timedelta(days=30)
+        - start
+    ).dt.total_seconds() / 86400.0
+    snapshot["scenario_month_sin"] = np.sin(2.0 * np.pi * start.month / 12.0)
+    snapshot["scenario_month_cos"] = np.cos(2.0 * np.pi * start.month / 12.0)
+
+    snapshot["voltage_rank_global"] = snapshot["stable_voltage_median"].rank(pct=True)
+    snapshot["voltage_rank_building"] = snapshot.groupby("building", observed=True)[
+        "stable_voltage_median"
+    ].rank(pct=True)
+    snapshot["voltage_rank_room"] = snapshot.groupby("room", observed=True)[
+        "stable_voltage_median"
+    ].rank(pct=True)
+    snapshot["building_battery_count"] = snapshot.groupby("building", observed=True)[
+        "battery"
+    ].transform("size")
+    snapshot["room_battery_count"] = snapshot.groupby("room", observed=True)["battery"].transform(
+        "size"
+    )
+    return snapshot
+
+
+def attach_training_targets(
+    snapshot: pd.DataFrame,
+    eol_times: pd.Series,
+    unobserved_eol_days: float = 30.0,
+) -> pd.DataFrame:
+    """Attach public training targets."""
+
+    result = snapshot.copy()
+    observed = pd.to_datetime(result["battery"].map(eol_times), errors="coerce")
+    assumed = (
+        pd.to_datetime(result["end_time"], errors="coerce").dt.normalize()
+        + pd.to_timedelta(unobserved_eol_days, unit="D")
+    )
+    result["event_observed"] = observed.notna().astype("int8")
+    result["effective_eol"] = observed.fillna(assumed)
+    result["target_rul_days"] = (
+        result["effective_eol"] - pd.to_datetime(result["scenario_time"])
+    ).dt.total_seconds() / 86400.0
+    return result
+
+
+def numeric_feature_columns(snapshot: pd.DataFrame) -> list[str]:
+    return [
+        column
+        for column in snapshot.columns
+        if column not in NON_FEATURE_COLUMNS
+        and not column.lower().startswith("unnamed")
+        and pd.api.types.is_numeric_dtype(snapshot[column])
+    ]

src/batteryswapai/competition_model.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from sklearn.ensemble import (
+    HistGradientBoostingClassifier,
+    HistGradientBoostingRegressor,
+    RandomForestClassifier,
+)
+from sklearn.impute import SimpleImputer
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import GroupKFold
+
+from .competition_features import numeric_feature_columns
+
+
+def _logit(values: np.ndarray) -> np.ndarray:
+    clipped = np.clip(values, 1e-5, 1.0 - 1e-5)
+    return np.log(clipped / (1.0 - clipped))
+
+
+@dataclass
+class FrozenLogisticCalibrator:
+    """Minimal binary logistic inference independent of sklearn pickle internals."""
+
+    coefficients: np.ndarray
+    intercept: float
+
+    @classmethod
+    def from_estimator(cls, estimator: LogisticRegression) -> "FrozenLogisticCalibrator":
+        return cls(
+            coefficients=np.asarray(estimator.coef_[0], dtype=float).copy(),
+            intercept=float(estimator.intercept_[0]),
+        )
+
+    def predict_proba(self, values: np.ndarray) -> np.ndarray:
+        scores = np.asarray(values, dtype=float) @ self.coefficients + self.intercept
+        positive = np.empty_like(scores, dtype=float)
+        nonnegative = scores >= 0.0
+        positive[nonnegative] = 1.0 / (1.0 + np.exp(-scores[nonnegative]))
+        exp_scores = np.exp(scores[~nonnegative])
+        positive[~nonnegative] = exp_scores / (1.0 + exp_scores)
+        return np.column_stack([1.0 - positive, positive])
+
+
+def _clean(frame: pd.DataFrame, columns: list[str]) -> pd.DataFrame:
+    return frame.reindex(columns=columns).replace([np.inf, -np.inf], np.nan).astype(float)
+
+
+def _derived_features(base: pd.DataFrame, kind: str) -> pd.DataFrame:
+    derived: dict[str, pd.Series] = {}
+    if kind in {"physics", "all"}:
+        for level in ("voltage_mean_3d", "voltage_mean_7d", "voltage_max_3d"):
+            for window in (30, 60, 90, 180):
+                rate = np.maximum(-base[f"voltage_slope_{window}d"], 1e-5)
+                derived[f"knee_{level}_{window}"] = np.clip(
+                    (base[level] - 2.40) / rate,
+                    -100.0,
+                    1000.0,
+                )
+    if kind == "all":
+        for short, long in ((3, 14), (7, 30), (14, 60), (30, 90), (30, 180), (60, 365)):
+            derived[f"slope_accel_{short}_{long}"] = (
+                base[f"voltage_slope_{short}d"] - base[f"voltage_slope_{long}d"]
+            )
+            derived[f"mean_drop_{short}_{long}"] = (
+                base[f"voltage_mean_{short}d"] - base[f"voltage_mean_{long}d"]
+            )
+        for window in (3, 7, 14, 30, 60, 90):
+            derived[f"volt_temp_{window}"] = base[f"voltage_mean_{window}d"] / (
+                base[f"temperature_mean_{window}d"] + 273.15
+            )
+    return pd.concat([base, pd.DataFrame(derived, index=base.index)], axis=1)
+
+
+def _event_estimators(random_state: int) -> dict[str, object]:
+    common = dict(
+        loss="log_loss",
+        learning_rate=0.05,
+        max_iter=240,
+        early_stopping=True,
+        validation_fraction=0.12,
+        n_iter_no_change=25,
+        random_state=random_state,
+    )
+    return {
+        "weighted_hist": HistGradientBoostingClassifier(
+            max_leaf_nodes=15,
+            min_samples_leaf=35,
+            l2_regularization=4.0,
+            class_weight={0: 1.0, 1: 5.0},
+            **common,
+        ),
+        "forest": RandomForestClassifier(
+            n_estimators=350,
+            min_samples_leaf=5,
+            max_features=0.7,
+            class_weight="balanced_subsample",
+            n_jobs=-1,
+            random_state=random_state,
+        ),
+        "all_hist": HistGradientBoostingClassifier(
+            max_leaf_nodes=31,
+            min_samples_leaf=25,
+            l2_regularization=5.0,
+            **common,
+        ),
+        "physics_hist": HistGradientBoostingClassifier(
+            max_leaf_nodes=31,
+            min_samples_leaf=25,
+            l2_regularization=5.0,
+            **common,
+        ),
+    }
+
+
+def _fit_event_estimators(
+    estimators: dict[str, object],
+    base: pd.DataFrame,
+    all_features: pd.DataFrame,
+    physics_features: pd.DataFrame,
+    target: np.ndarray,
+) -> tuple[dict[str, object], SimpleImputer]:
+    imputer = SimpleImputer(strategy="median")
+    forest_features = imputer.fit_transform(base)
+    estimators["weighted_hist"].fit(base, target)
+    estimators["forest"].fit(forest_features, target)
+    estimators["all_hist"].fit(all_features, target)
+    estimators["physics_hist"].fit(physics_features, target)
+    return estimators, imputer
+
+
+def _event_components(
+    estimators: dict[str, object],
+    imputer: SimpleImputer,
+    base: pd.DataFrame,
+    all_features: pd.DataFrame,
+    physics_features: pd.DataFrame,
+) -> np.ndarray:
+    return np.column_stack(
+        [
+            estimators["weighted_hist"].predict_proba(base)[:, 1],
+            estimators["forest"].predict_proba(imputer.transform(base))[:, 1],
+            estimators["all_hist"].predict_proba(all_features)[:, 1],
+            estimators["physics_hist"].predict_proba(physics_features)[:, 1],
+        ]
+    )
+
+
+@dataclass
+class EventTimeModel:
+    event_estimators: dict[str, object]
+    event_imputer: SimpleImputer
+    event_calibrator: FrozenLogisticCalibrator
+    rul_estimator: HistGradientBoostingRegressor
+    feature_columns: list[str]
+    all_feature_columns: list[str]
+    physics_feature_columns: list[str]
+    quantile: float
+    horizon_days: int
+    dataset_revision: str
+
+    def _feature_sets(
+        self, snapshot: pd.DataFrame
+    ) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+        base = _clean(snapshot, self.feature_columns)
+        all_features = _clean(_derived_features(base, "all"), self.all_feature_columns)
+        physics_features = _clean(
+            _derived_features(base, "physics"), self.physics_feature_columns
+        )
+        return base, all_features, physics_features
+
+    def predict_event_risk(self, snapshot: pd.DataFrame) -> np.ndarray:
+        base, all_features, physics_features = self._feature_sets(snapshot)
+        components = _event_components(
+            self.event_estimators,
+            self.event_imputer,
+            base,
+            all_features,
+            physics_features,
+        )
+        stacked = _logit(components)
+        return np.asarray(self.event_calibrator.predict_proba(stacked)[:, 1])
+
+    def predict_rul(self, snapshot: pd.DataFrame) -> np.ndarray:
+        base = _clean(snapshot, self.feature_columns)
+        return np.asarray(self.rul_estimator.predict(base), dtype=float)
+
+
+def fit_event_time_model(
+    training_snapshots: pd.DataFrame,
+    *,
+    quantile: float = 0.05,
+    horizon_days: int = 42,
+    rul_training_max_days: float = 90.0,
+    dataset_revision: str = "unknown",
+    random_state: int = 2026,
+    calibration_folds: int = 5,
+    max_iter: int | None = None,
+) -> EventTimeModel:
+    del max_iter  # retained for compatibility with earlier validation commands
+    work = training_snapshots.dropna(subset=["target_rul_days"]).copy()
+    columns = numeric_feature_columns(work)
+    base = _clean(work, columns)
+    all_features = _derived_features(base, "all")
+    physics_features = _derived_features(base, "physics")
+    all_columns = list(all_features.columns)
+    physics_columns = list(physics_features.columns)
+    target_rul = pd.to_numeric(work["target_rul_days"], errors="coerce").astype(float)
+    event_target = (
+        work["event_observed"].astype(bool)
+        & target_rul.between(0.0, float(horizon_days))
+    ).astype("int8").to_numpy()
+
+    groups = work["battery"].astype(str).to_numpy()
+    folds = min(int(calibration_folds), len(np.unique(groups)))
+    if folds < 2:
+        raise ValueError("At least two device groups are required for event calibration")
+    oof_components = np.full((len(work), 4), np.nan)
+    splitter = GroupKFold(n_splits=folds)
+    for fold_number, (train_index, valid_index) in enumerate(
+        splitter.split(base, groups=groups), start=1
+    ):
+        fold_estimators = _event_estimators(random_state + fold_number)
+        fold_estimators, fold_imputer = _fit_event_estimators(
+            fold_estimators,
+            base.iloc[train_index],
+            all_features.iloc[train_index],
+            physics_features.iloc[train_index],
+            event_target[train_index],
+        )
+        oof_components[valid_index] = _event_components(
+            fold_estimators,
+            fold_imputer,
+            base.iloc[valid_index],
+            all_features.iloc[valid_index],
+            physics_features.iloc[valid_index],
+        )
+
+    fitted_calibrator = LogisticRegression(C=0.03, max_iter=1000)
+    fitted_calibrator.fit(_logit(oof_components), event_target)
+    calibrator = FrozenLogisticCalibrator.from_estimator(fitted_calibrator)
+
+    estimators = _event_estimators(random_state)
+    estimators, imputer = _fit_event_estimators(
+        estimators,
+        base,
+        all_features,
+        physics_features,
+        event_target,
+    )
+
+    observed_near_horizon = (
+        work["event_observed"].astype(bool)
+        & target_rul.gt(0.0)
+        & target_rul.le(float(rul_training_max_days))
+    )
+    rul_estimator = HistGradientBoostingRegressor(
+        loss="quantile",
+        quantile=quantile,
+        learning_rate=0.055,
+        max_iter=260,
+        max_leaf_nodes=19,
+        min_samples_leaf=30,
+        l2_regularization=3.0,
+        early_stopping=True,
+        validation_fraction=0.12,
+        n_iter_no_change=25,
+        random_state=random_state,
+    )
+    rul_estimator.fit(base.loc[observed_near_horizon], target_rul.loc[observed_near_horizon])
+    return EventTimeModel(
+        estimators,
+        imputer,
+        calibrator,
+        rul_estimator,
+        columns,
+        all_columns,
+        physics_columns,
+        quantile,
+        horizon_days,
+        dataset_revision,
+    )

src/batteryswapai/competition_planner.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from batteryswap_public.interfaces import Planner
+
+from .competition_features import build_daily_features, scenario_snapshot
+from .competition_model import EventTimeModel
+
+
+@dataclass(frozen=True)
+class PlannerPolicy:
+    event_risk_threshold: float = 0.10
+    prediction_offset_days: float = -25.0
+    building_batch_window_days: int = 4
+    unscheduled_margin_days: int = 1
+    capacity_lookback_days: int = 14
+    capacity_lookahead_days: int = 7
+    capacity_daily_limit_fraction: float = 1.0
+    capacity_weekly_limit_fraction: float = 1.0
+    capacity_limit_penalty_multiplier: float = 1.0
+    capacity_operational_cost_weight: float = 1.5
+    use_expected_cost: bool = False
+    risk_calibration_scale: float = 1.50
+    expected_event_day_shift: float = 0.0
+    expected_service_cost_hours: float = 2.0
+    expected_gain_margin: float = 10.0
+    expected_emergency_buffer_days: float = 6.0
+    stale_risk_cutoff_days: float = 7.0
+    recent_gap_risk_factor: float = 0.75
+    stale_risk_factor: float = 0.10
+
+
+class CompetitionPlanner(Planner):
+    def __init__(self, model: EventTimeModel, policy: PlannerPolicy | None = None):
+        self.model = model
+        self.policy = policy or PlannerPolicy()
+
+    def plan(self, battery_data, locations, travel_costs, settings):
+        flat = battery_data.reset_index()
+        start_time = pd.to_datetime(flat["end_time"], errors="coerce").max().normalize()
+        daily = build_daily_features(battery_data)
+        snapshot = scenario_snapshot(
+            daily,
+            locations,
+            scenario_name="direct",
+            scenario_time=start_time,
+        )
+        return self.plan_snapshot(snapshot, locations, travel_costs, settings, start_time)
+
+    def plan_snapshot(
+        self,
+        snapshot: pd.DataFrame,
+        locations: pd.DataFrame,
+        travel_costs: pd.DataFrame,
+        settings,
+        start_time: pd.Timestamp | str,
+        predicted_rul: np.ndarray | None = None,
+        predicted_risk: np.ndarray | None = None,
+    ) -> pd.DataFrame:
+        start = pd.Timestamp(start_time).normalize()
+        horizon = int(settings.planning_window_days)
+        predictions = (
+            self.model.predict_rul(snapshot) if predicted_rul is None else np.asarray(predicted_rul, dtype=float)
+        )
+        risks = (
+            self.model.predict_event_risk(snapshot)
+            if predicted_risk is None
+            else np.asarray(predicted_risk, dtype=float)
+        )
+        if "data_gap_days" in snapshot.columns:
+            gaps = pd.to_numeric(snapshot["data_gap_days"], errors="coerce").to_numpy(
+                dtype=float
+            )
+            freshness_factor = np.ones(len(snapshot), dtype=float)
+            recent_gap = (gaps > 0.0) & (gaps <= self.policy.stale_risk_cutoff_days)
+            stale = (gaps > self.policy.stale_risk_cutoff_days) | ~np.isfinite(gaps)
+            freshness_factor[recent_gap] = self.policy.recent_gap_risk_factor
+            freshness_factor[stale] = self.policy.stale_risk_factor
+            risks = risks * freshness_factor
+        raw_predictions = predictions.copy()
+        predictions = raw_predictions + self.policy.prediction_offset_days
+
+        work = snapshot[["battery", "building", "room"]].copy()
+        work["predicted_rul"] = predictions
+        work["predicted_risk"] = risks
+        work["target_day"] = np.floor(np.clip(predictions, 0.0, horizon + 1.0)).astype(int)
+        if self.policy.use_expected_cost:
+            if "censor_proxy_rul_days" in snapshot.columns:
+                proxy_rul = pd.to_numeric(
+                    snapshot["censor_proxy_rul_days"], errors="coerce"
+                ).to_numpy(dtype=float)
+            else:
+                proxy_rul = (
+                    pd.to_datetime(snapshot["end_time"], errors="coerce").dt.normalize()
+                    + pd.to_timedelta(float(settings.unobserved_eol_days), unit="D")
+                    - start
+                ).dt.total_seconds().to_numpy() / 86400.0
+            planned_day = np.clip(predictions, 0.0, float(horizon))
+            expected_event_day = np.clip(
+                raw_predictions + self.policy.expected_event_day_shift,
+                0.0,
+                float(horizon),
+            )
+            calibrated_risk = np.clip(
+                risks * self.policy.risk_calibration_scale,
+                0.0,
+                1.0,
+            )
+            scheduled_event_cost = (
+                float(settings.early_replacement_penalty_daily)
+                * np.maximum(expected_event_day - planned_day, 0.0)
+                + float(settings.late_replacement_penalty_daily)
+                * np.maximum(planned_day - expected_event_day, 0.0)
+            )
+            emergency_day = float(horizon) + self.policy.expected_emergency_buffer_days
+            no_schedule_event_cost = (
+                float(settings.late_replacement_penalty_daily)
+                * np.maximum(emergency_day - expected_event_day, 0.0)
+                + self.policy.expected_service_cost_hours
+            )
+            healthy_early_cost = float(settings.early_replacement_penalty_daily) * np.maximum(
+                proxy_rul - planned_day,
+                0.0,
+            )
+            expected_gain = (
+                calibrated_risk * (no_schedule_event_cost - scheduled_event_cost)
+                - (1.0 - calibrated_risk) * healthy_early_cost
+                - self.policy.expected_service_cost_hours
+            )
+            work["expected_gain"] = expected_gain
+            work["scheduled"] = (
+                (expected_gain > self.policy.expected_gain_margin)
+                & (predictions <= horizon)
+            )
+        else:
+            work["scheduled"] = (
+                (risks >= self.policy.event_risk_threshold) & (predictions <= horizon)
+            )
+
+        candidates = work[work["scheduled"]].copy()
+        candidates["assigned_day"] = candidates["target_day"]
+        if not candidates.empty:
+            candidates = self._batch_buildings(candidates)
+            candidates = self._balance_capacity(
+                candidates,
+                travel_costs,
+                settings,
+                horizon,
+            )
+
+        unscheduled_day = start + pd.Timedelta(
+            days=horizon + self.policy.unscheduled_margin_days
+        )
+        planned_rows: list[dict] = []
+        if not candidates.empty:
+            for assigned_day, day_frame in candidates.groupby("assigned_day", sort=True):
+                ordered = self._route_day(day_frame, travel_costs, settings.base_location)
+                date = start + pd.Timedelta(days=int(assigned_day))
+                planned_rows.extend({"day": date, "battery": battery} for battery in ordered)
+
+        scheduled_ids = set(candidates["battery"]) if not candidates.empty else set()
+        remaining = work[~work["battery"].isin(scheduled_ids)].sort_values(
+            ["building", "room", "battery"]
+        )
+        planned_rows.extend(
+            {"day": unscheduled_day, "battery": battery} for battery in remaining["battery"]
+        )
+        return pd.DataFrame(planned_rows, columns=["day", "battery"]).reset_index(drop=True)
+
+    def _batch_buildings(self, candidates: pd.DataFrame) -> pd.DataFrame:
+        batches = []
+        tolerance = self.policy.building_batch_window_days
+        for _, building_rows in candidates.groupby("building", observed=True, sort=False):
+            ordered = building_rows.sort_values(["target_day", "room", "battery"])
+            cluster_start: int | None = None
+            for _, row in ordered.iterrows():
+                target = int(row["target_day"])
+                if cluster_start is None or target - cluster_start > tolerance:
+                    cluster_start = target
+                record = row.to_dict()
+                record["assigned_day"] = cluster_start
+                batches.append(record)
+        return pd.DataFrame(batches)
+
+    def _balance_capacity(self, candidates, travel_costs, settings, horizon):
+        """Move whole building visits to nearby days to avoid hard labor penalties."""
+
+        distances = travel_costs.set_index(["from", "to"])["hours"]
+        base = settings.base_location
+        clusters = []
+        for (building, assigned_day), rows in candidates.groupby(
+            ["building", "assigned_day"], observed=True, sort=True
+        ):
+            travel = 0.0
+            building_change = 0.0
+            if building != base:
+                travel = float(distances.loc[(base, building)]) + float(
+                    distances.loc[(building, base)]
+                )
+                building_change = float(settings.time_per_building_change_hours)
+            room_time = float(rows["room"].nunique()) * float(settings.time_per_room_change_hours)
+            swap_time = len(rows) * float(settings.time_per_battery_hours)
+            clusters.append(
+                {
+                    "building": building,
+                    "target": int(assigned_day),
+                    "indices": rows.index.to_list(),
+                    "hours": travel + building_change + room_time + swap_time,
+                    "batteries": len(rows),
+                }
+            )
+
+        day_hours: dict[int, float] = {}
+        day_indices: dict[int, list[int]] = {}
+
+        def exact_day_hours(indices: list[int]) -> float:
+            rows = candidates.loc[indices]
+            ordered = self._route_day(rows, travel_costs, base)
+            by_battery = rows.set_index("battery")
+            current_building = base
+            current_room = settings.base_room
+            hours = 0.0
+            for battery in ordered:
+                building = str(by_battery.loc[battery, "building"])
+                room = str(by_battery.loc[battery, "room"])
+                if building != current_building:
+                    hours += float(distances.loc[(current_building, building)])
+                    hours += float(settings.time_per_building_change_hours)
+                    current_building = building
+                if room != current_room:
+                    hours += float(settings.time_per_room_change_hours)
+                    current_room = room
+                hours += float(settings.time_per_battery_hours)
+            hours += float(distances.loc[(current_building, base)])
+            return hours
+
+        for cluster in sorted(clusters, key=lambda item: (item["target"], -item["hours"])):
+            target = cluster["target"]
+            first = max(0, target - self.policy.capacity_lookback_days)
+            last = min(horizon, target + self.policy.capacity_lookahead_days)
+            best: tuple[float, int] | None = None
+            for day in range(first, last + 1):
+                proposed_indices = day_indices.get(day, []) + cluster["indices"]
+                projected_day = exact_day_hours(proposed_indices)
+                week = day // 7
+                projected_week = sum(
+                    hours
+                    for assigned_day, hours in day_hours.items()
+                    if assigned_day // 7 == week and assigned_day != day
+                ) + projected_day
+                guarded_daily_limit = (
+                    float(settings.worker_limit_daily_hours)
+                    * self.policy.capacity_daily_limit_fraction
+                )
+                guarded_weekly_limit = (
+                    float(settings.worker_limit_weekly_hours)
+                    * self.policy.capacity_weekly_limit_fraction
+                )
+                overtime = max(projected_day - float(settings.overtime_start), 0.0)
+                daily_penalty = (
+                    float(settings.worker_limit_daily_penalty)
+                    * self.policy.capacity_limit_penalty_multiplier
+                    if projected_day > guarded_daily_limit
+                    else 0.0
+                )
+                weekly_penalty = (
+                    float(settings.worker_limit_weekly_penalty)
+                    * self.policy.capacity_limit_penalty_multiplier
+                    if projected_week >= guarded_weekly_limit
+                    else 0.0
+                )
+                timing = cluster["batteries"] * (
+                    0.5 * (target - day) if day < target else 2.0 * (day - target)
+                )
+                marginal_operational = projected_day - day_hours.get(day, 0.0)
+                cost = (
+                    timing
+                    + self.policy.capacity_operational_cost_weight
+                    * marginal_operational
+                    + overtime * float(settings.overtime_penalty_factor)
+                    + daily_penalty
+                    + weekly_penalty
+                )
+                option = (cost, day)
+                if best is None or option < best:
+                    best = option
+            assert best is not None
+            chosen_day = best[1]
+            chosen_indices = day_indices.get(chosen_day, []) + cluster["indices"]
+            day_indices[chosen_day] = chosen_indices
+            day_hours[chosen_day] = exact_day_hours(chosen_indices)
+            candidates.loc[cluster["indices"], "assigned_day"] = chosen_day
+        return candidates
+
+    @staticmethod
+    def _route_day(day_frame: pd.DataFrame, travel_costs: pd.DataFrame, base: str) -> list[str]:
+        distances = travel_costs.set_index(["from", "to"])["hours"]
+        remaining = set(day_frame["building"].astype(str))
+        current = base
+        building_order: list[str] = []
+        while remaining:
+            next_building = min(
+                remaining,
+                key=lambda building: (float(distances.loc[(current, building)]), building),
+            )
+            building_order.append(next_building)
+            remaining.remove(next_building)
+            current = next_building
+
+        # Nearest-neighbour is a good seed but can leave an expensive final
+        # leg.  A deterministic 2-opt pass materially improves multi-building
+        # days while staying tiny compared with the inference budget.
+        def route_cost(order: list[str]) -> float:
+            points = [base, *order, base]
+            return sum(
+                float(distances.loc[(left, right)])
+                for left, right in zip(points, points[1:])
+            )
+
+        improved = True
+        best_cost = route_cost(building_order)
+        while improved and len(building_order) >= 3:
+            improved = False
+            for left in range(len(building_order) - 1):
+                for right in range(left + 1, len(building_order)):
+                    candidate = (
+                        building_order[:left]
+                        + list(reversed(building_order[left : right + 1]))
+                        + building_order[right + 1 :]
+                    )
+                    candidate_cost = route_cost(candidate)
+                    if candidate_cost + 1e-12 < best_cost:
+                        building_order = candidate
+                        best_cost = candidate_cost
+                        improved = True
+
+        batteries: list[str] = []
+        for building in building_order:
+            local = day_frame[day_frame["building"] == building].sort_values(
+                ["room", "target_day", "battery"]
+            )
+            batteries.extend(local["battery"].astype(str).tolist())
+        return batteries

submission_artifacts/planner.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d75f66c4cabf06c71eefc1714db726b86d02f6108829c51caabde89b0b794ff
+size 3923932

submission_artifacts/planner.json

@@ -0,0 +1,128 @@
+{
+  "dataset_revision": "7f423ac4cb6ab146f7ea7a37872eb4dfc3c9705c",
+  "artifact": "submission_artifacts/planner.joblib",
+  "quantile": 0.05,
+  "event_risk_threshold": 0.5,
+  "prediction_offset_days": -5.0,
+  "calibration_folds": 5,
+  "planner_policy": {
+    "expected_cost": true,
+    "risk_calibration_scale": 1.5,
+    "expected_service_cost_hours": 2.0,
+    "expected_gain_margin": 10.0,
+    "prediction_offset_days": -5.0,
+    "stale_risk_cutoff_days": 7.0,
+    "recent_gap_risk_factor": 0.75,
+    "stale_risk_factor": 0.1,
+    "building_batch_window_days": 4,
+    "capacity_lookahead_days": 21,
+    "capacity_operational_cost_weight": 1.5,
+    "exact_route_capacity": true
+  },
+  "training_rows": 19890,
+  "training_devices": 458,
+  "features": [
+    "voltage_median",
+    "voltage_mean",
+    "voltage_min",
+    "voltage_max",
+    "voltage_std",
+    "temperature_median",
+    "temperature_std",
+    "observations_day",
+    "stable_voltage_median",
+    "history_days",
+    "days_since_previous",
+    "voltage_mean_3d",
+    "voltage_min_3d",
+    "voltage_max_3d",
+    "voltage_std_3d",
+    "temperature_mean_3d",
+    "voltage_slope_3d",
+    "span_3d",
+    "voltage_mean_7d",
+    "voltage_min_7d",
+    "voltage_max_7d",
+    "voltage_std_7d",
+    "temperature_mean_7d",
+    "voltage_slope_7d",
+    "span_7d",
+    "voltage_mean_14d",
+    "voltage_min_14d",
+    "voltage_max_14d",
+    "voltage_std_14d",
+    "temperature_mean_14d",
+    "voltage_slope_14d",
+    "span_14d",
+    "voltage_mean_30d",
+    "voltage_min_30d",
+    "voltage_max_30d",
+    "voltage_std_30d",
+    "temperature_mean_30d",
+    "voltage_slope_30d",
+    "span_30d",
+    "voltage_mean_60d",
+    "voltage_min_60d",
+    "voltage_max_60d",
+    "voltage_std_60d",
+    "temperature_mean_60d",
+    "voltage_slope_60d",
+    "span_60d",
+    "voltage_mean_90d",
+    "voltage_min_90d",
+    "voltage_max_90d",
+    "voltage_std_90d",
+    "temperature_mean_90d",
+    "voltage_slope_90d",
+    "span_90d",
+    "voltage_mean_180d",
+    "voltage_min_180d",
+    "voltage_max_180d",
+    "voltage_std_180d",
+    "temperature_mean_180d",
+    "voltage_slope_180d",
+    "span_180d",
+    "voltage_mean_365d",
+    "voltage_min_365d",
+    "voltage_max_365d",
+    "voltage_std_365d",
+    "temperature_mean_365d",
+    "voltage_slope_365d",
+    "span_365d",
+    "voltage_recent_vs_30d",
+    "voltage_recent_vs_90d",
+    "voltage_range_day",
+    "location_age_days",
+    "data_gap_days",
+    "censor_proxy_rul_days",
+    "scenario_month_sin",
+    "scenario_month_cos",
+    "voltage_rank_global",
+    "voltage_rank_building",
+    "voltage_rank_room",
+    "building_battery_count",
+    "room_battery_count"
+  ],
+  "artifact_sha256": "8d75f66c4cabf06c71eefc1714db726b86d02f6108829c51caabde89b0b794ff",
+  "runtime_versions": {
+    "batteryswap_public": "0.3.4",
+    "fastparquet": "2026.5.0",
+    "joblib": "1.5.3",
+    "numpy": "2.5.2",
+    "pandas": "3.0.5",
+    "scikit-learn": "1.9.0"
+  },
+  "validation_report": "artifacts/submission_cv_final.json",
+  "optimistic_train_score": {
+    "early_swap": 204.9375,
+    "building_change": 8.520833333333334,
+    "weekly_limit": 20.833333333333332,
+    "room_change": 5.489583333333333,
+    "battery_swap": 3.1458333333333335,
+    "late_swap": 98.125,
+    "travel": 34.465079861111114,
+    "overtime": 55.34966666666666,
+    "daily_limit": 31.25,
+    "total_cost": 462.11682986111094
+  }
+}

tests/test_competition_features.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pandas as pd
+
+from batteryswapai.competition_features import build_daily_features, scenario_snapshot
+
+
+def test_scenario_snapshot_never_uses_future_sensor_rows():
+    raw = pd.DataFrame(
+        {
+            "device_id": ["d_a"] * 6,
+            "end_time": pd.to_datetime(
+                [
+                    "2026-01-01 10:00",
+                    "2026-01-01 12:00",
+                    "2026-01-02 10:00",
+                    "2026-01-02 12:00",
+                    "2026-01-03 10:00",
+                    "2026-01-03 12:00",
+                ]
+            ),
+            "voltage": [3.1, 3.0, 2.9, 2.8, 1.0, 1.0],
+            "temperature": [20.0] * 6,
+        }
+    ).set_index(["device_id", "end_time"])
+    locations = pd.DataFrame(
+        {
+            "battery": ["d_a"],
+            "building": ["b_a"],
+            "room": ["r_a"],
+            "start_time": pd.to_datetime(["2025-01-01"]),
+            "end_time": pd.to_datetime(["2026-02-01"]),
+        }
+    )
+
+    daily = build_daily_features(raw, windows=(3, 7, 14, 30, 60, 90, 180, 365))
+    snapshot = scenario_snapshot(daily, locations, "s_0", "2026-01-02")
+    assert snapshot.loc[0, "day"] == pd.Timestamp("2026-01-02")
+    assert np.isclose(snapshot.loc[0, "voltage_median"], 2.85)
+
+
+def test_temperature_filter_falls_back_when_no_stable_reading_exists():
+    raw = pd.DataFrame(
+        {
+            "device_id": ["d_a", "d_a"],
+            "end_time": pd.to_datetime(["2026-01-01 10:00", "2026-01-01 12:00"]),
+            "voltage": [3.0, 2.8],
+            "temperature": [-5.0, 40.0],
+        }
+    ).set_index(["device_id", "end_time"])
+    daily = build_daily_features(raw)
+    assert daily.loc[0, "stable_voltage_median"] == daily.loc[0, "voltage_median"]

tests/test_competition_model.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import numpy as np
+
+from batteryswapai.competition_model import FrozenLogisticCalibrator
+
+
+def test_frozen_logistic_calibrator_is_stable_and_normalized() -> None:
+    calibrator = FrozenLogisticCalibrator(
+        coefficients=np.array([1.5, -0.5]),
+        intercept=-0.25,
+    )
+    values = np.array([[0.0, 0.0], [1000.0, -1000.0], [-1000.0, 1000.0]])
+
+    probabilities = calibrator.predict_proba(values)
+
+    assert probabilities.shape == (3, 2)
+    assert np.isfinite(probabilities).all()
+    np.testing.assert_allclose(probabilities.sum(axis=1), 1.0)
+    assert probabilities[1, 1] == 1.0
+    assert probabilities[2, 1] == 0.0

tests/test_competition_planner.py

@@ -0,0 +1,155 @@
+import numpy as np
+import pandas as pd
+from batteryswap_public.evaluate import EvaluationSettings, check_plan_valid
+
+from batteryswapai.competition_planner import CompetitionPlanner, PlannerPolicy
+
+
+class DummyEventTimeModel:
+    def predict_event_risk(self, snapshot):
+        return np.array([0.9, 0.8, 0.01])
+
+    def predict_rul(self, snapshot):
+        return np.array([20.0, 22.0, 5.0])
+
+
+def _inputs():
+    locations = pd.DataFrame(
+        {
+            "battery": ["d_a", "d_b", "d_c"],
+            "building": ["b_remote", "b_remote", "b_base"],
+            "room": ["r_1", "r_1", "r_base"],
+            "start_time": pd.to_datetime(["2025-01-01"] * 3),
+            "end_time": pd.to_datetime(["2026-12-01"] * 3),
+        }
+    )
+    travel = pd.DataFrame(
+        [
+            {"from": "b_base", "to": "b_base", "hours": 0.0},
+            {"from": "b_base", "to": "b_remote", "hours": 1.0},
+            {"from": "b_remote", "to": "b_base", "hours": 1.0},
+            {"from": "b_remote", "to": "b_remote", "hours": 0.0},
+        ]
+    )
+    settings = EvaluationSettings(base_location="b_base", base_room="r_base")
+    return locations, travel, settings
+
+
+def test_plan_is_complete_and_batches_same_building():
+    locations, travel, settings = _inputs()
+    planner = CompetitionPlanner(
+        DummyEventTimeModel(),
+        PlannerPolicy(
+            event_risk_threshold=0.1,
+            prediction_offset_days=0.0,
+            building_batch_window_days=3,
+        ),
+    )
+    plan = planner.plan_snapshot(
+        locations,
+        locations,
+        travel,
+        settings,
+        "2026-01-01",
+    )
+    check_plan_valid(plan, locations, start_time=pd.Timestamp("2026-01-01"))
+    days = plan.set_index("battery")["day"]
+    assert days["d_a"] == days["d_b"]
+    assert days["d_c"] > pd.Timestamp("2026-02-12")
+
+
+def test_prediction_arrays_can_be_supplied_for_oof_validation():
+    locations, travel, settings = _inputs()
+    planner = CompetitionPlanner(DummyEventTimeModel())
+    plan = planner.plan_snapshot(
+        locations,
+        locations,
+        travel,
+        settings,
+        "2026-01-01",
+        predicted_rul=np.array([5.0, 6.0, 7.0]),
+        predicted_risk=np.array([0.9, 0.01, 0.01]),
+    )
+    inside = plan[plan["day"] <= pd.Timestamp("2026-02-12")]
+    assert inside["battery"].tolist() == ["d_a"]
+
+
+def test_stale_sensor_history_reduces_proactive_risk():
+    locations, travel, settings = _inputs()
+    snapshot = locations.copy()
+    snapshot["data_gap_days"] = [0.0, 8.0, 0.0]
+    planner = CompetitionPlanner(
+        DummyEventTimeModel(),
+        PlannerPolicy(event_risk_threshold=0.5, prediction_offset_days=0.0),
+    )
+
+    plan = planner.plan_snapshot(
+        snapshot,
+        locations,
+        travel,
+        settings,
+        "2026-01-01",
+        predicted_rul=np.array([5.0, 5.0, 5.0]),
+        predicted_risk=np.array([0.6, 0.6, 0.01]),
+    )
+
+    inside = plan[plan["day"] <= pd.Timestamp("2026-02-12")]
+    assert inside["battery"].tolist() == ["d_a"]
+
+
+def test_capacity_balancing_accounts_for_marginal_route_cost():
+    locations = pd.DataFrame(
+        {
+            "battery": ["d_a", "d_b"],
+            "building": ["b_a", "b_b"],
+            "room": ["r_a", "r_b"],
+            "start_time": pd.to_datetime(["2025-01-01"] * 2),
+            "end_time": pd.to_datetime(["2026-12-01"] * 2),
+        }
+    )
+    travel = pd.DataFrame(
+        [
+            {"from": left, "to": right, "hours": 0.0 if left == right else 0.1 if "b_base" not in (left, right) else 1.0}
+            for left in ("b_base", "b_a", "b_b")
+            for right in ("b_base", "b_a", "b_b")
+        ]
+    )
+    settings = EvaluationSettings(base_location="b_base", base_room="r_base")
+    planner = CompetitionPlanner(
+        DummyEventTimeModel(),
+        PlannerPolicy(
+            prediction_offset_days=0.0,
+            building_batch_window_days=0,
+        ),
+    )
+
+    plan = planner.plan_snapshot(
+        locations,
+        locations,
+        travel,
+        settings,
+        "2026-01-01",
+        predicted_rul=np.array([1.0, 2.0]),
+        predicted_risk=np.array([0.9, 0.9]),
+    )
+
+    days = plan.set_index("battery")["day"]
+    assert days["d_a"] == days["d_b"]
+
+
+def test_official_planner_interface_has_a_working_fallback():
+    locations, travel, settings = _inputs()
+    battery_data = pd.DataFrame(
+        {
+            "device_id": ["d_a", "d_b", "d_c"],
+            "end_time": pd.to_datetime(["2026-01-01"] * 3),
+            "voltage": [2.7, 2.8, 3.0],
+            "temperature": [20.0, 20.0, 20.0],
+        }
+    ).set_index(["device_id", "end_time"])
+    planner = CompetitionPlanner(
+        DummyEventTimeModel(),
+        PlannerPolicy(prediction_offset_days=0.0),
+    )
+    plan = planner.plan(battery_data, locations, travel, settings)
+    check_plan_valid(plan, locations, start_time=pd.Timestamp("2026-01-01"))