Checkpoint contract

A useful method release pairs runnable code with an actual fitted model and enough metadata to interpret its inputs and outputs. A candidate JSON, metric table, confusion matrix or test-prediction file is not a trained model.

What is fitted

Depending on the selected family/program, the serialized model includes:

Random convolution kernels, random interval definitions, local-shape prototypes and fitted representation objects.
The trained classifier and any learned feature-level scaler.
The global integer class axis and the classes observed during fitting.
A fitted HMM transition matrix and class prior when HMM decoding is enabled.
Fitted member models and fusion weights for ensemble variants.

Configured per-window z-score normalization is computed from each incoming window. It is not a single global sensor-normalization statistic learned from all training participants. A fitted feature-level StandardScaler, where present, is a different transformation and is stored inside the classifier pipeline.

The semantic class names, original sensor units/channel order, windowing/preprocessing rules, recording boundaries and sampling rate must remain in external metadata. The Python object alone is not a universal wearable-data loader.

What the original code saves

The Random/Evolution controller's final-refit path writes selected_model.pkl, selected_candidate.json, locked-test predictions and metrics. It fits the validation-selected candidate on train+validation before testing. This establishes that the implementation can save a fitted model; it does not establish that every historical checkpoint is still retained or included here.

The original fixed-family experiment runner writes model.pkl only when its save_model option is enabled; that option defaults to false. The dedicated CIS campaign's recipe evaluator also did not persist its fitted model. Therefore a fixed-family result folder can contain complete predictions/metrics without a retained checkpoint. Check the actual inventory, rather than assuming that a completed experiment implies a model file exists.

The completed inventory located and copied 180 Random and 180 Evolution checkpoints, totaling 74,911,659,604 bytes, with source/copy SHA256 identity. All 360 passed loading and small synthetic-input predictions; their status is load_and_smoke_verified. Six ADL-Wrist fold-0 models also reproduced all 861 real locked-test predictions on both original frozen inputs and a fresh export. The remaining 354 full test splits were not rerun in this gate. Rescoring saved predictions for all 360 models is a separate check, not a substitute for full inference.

No retained checkpoint was located for the seven fixed variants (including CIS) or two selectors, leaving 1,620 of 1,980 expected keys missing. No missing original model is generated or silently substituted. Root audit and each checkpoint's validation record distinguish loading/synthetic checks from full real-test equivalence.

If a checkpoint is absent, a model retrained from a frozen recipe should be explicitly labelled as a new refit, with its own source version, environment, fitted-data scope and validation result. It must not silently replace an original checkpoint or be claimed byte-identical to it.

Provenance required per model

A model release should record the public method and selected family/candidate, dataset view/source stream, fold, model seed, training/validation split identity, fitted-data scope, ordered class vocabulary, input/preprocessing contract, decoder setting, source commit, environment versions, file checksum, and the evaluation record used to verify it. Select5/Select7 additionally need their validation-selection record; Random/Evolution need the candidate and search configuration.

Paper fold models were fitted for a particular label vocabulary and data distribution. They are not one model covering all eleven datasets. A checkpoint evaluated on a held-out fold is different from a future deployment model refitted on all participants. If publishing a compact featured set, choose it using a declared validation rule or publish clearly labelled representative models. Selecting the highest test-performing fold/seed invalidates any claim that the featured selection was independent of the test set.

Legacy modules and safe loading

Original checkpoints can contain Python class paths such as tsevolve.cpu.algorithms.StateRocketIntervalHMM. The release's canonical name is WISP; renaming a package or the model filename does not rewrite those serialized references. Compatibility support must preserve the original class resolution and fitted-state semantics, or be accompanied by an explicitly validated export/migration. Merely loading a pickle without an exception is not enough: verify predictions against the corresponding recorded input and result where available.

Pickle deserialization can execute code. Use only trusted checkpoints from an authenticated release, review their provenance, and opt in explicitly with --trust-pickle. Verify the checksum independently against the release manifest; a checksum obtained only from the same untrusted download is not a safety guarantee. Do not deserialize arbitrary user-supplied models in an exposed web service.

Use compatible Python/NumPy/SciPy/scikit-learn versions and preserve checkpoint-specific evidence. This release was validated with Python 3.12.13 and the source numerical package freeze: NumPy 2.3.5, SciPy 1.17.1, scikit-learn 1.7.2, joblib 1.5.3 and threadpoolctl 3.6.0. All 360 pickles contain the scikit-learn 1.7.2 version marker. The original virtual-environment creation record names Python 3.12.13, but cannot prove that exact patch version at every historical training runtime. The current gate is not a blanket cross-version guarantee. Do not disregard compatibility warnings simply because a file loads.

The inference CLI can read an explicitly supplied metadata JSON. If omitted, it looks for a sibling checkpoint.json, then <checkpoint_stem>.metadata.json. Supported validation fields are input_shape (time/channel shape, optionally prefixed by the original window count) and label_names. A SHA256 stored in a sidecar is descriptive integrity information; the CLI does not treat that file as an independently trusted source for the --sha256 check.

wisp family-fit writes <output_stem>.metadata.json with the declared method, input shape, global label names, model seed, fitted-data scope, HMM setting, parameters and output checksum. wisp select-fit also writes <output_stem>.selection.json for its validation choice. wisp search writes selected_model.metadata.json for the controller's selected model. A generic new fit does not invent a dataset/fold identity that the caller did not provide. These newly fitted artifacts must be kept distinct from retained paper models.

The manifest inventory is read-only and does not need to deserialize every model. Actual loading/inference verification, hashes, installation and any refit must run on allocated compute nodes. Coverage is reported by the root release audit, not by this explanatory document.

Python inference interface

The release wrapper can also be used without the CLI. This template assumes the paths, verified digest and checkpoint metadata have been selected from a trusted release; it does not download or fit a model:

import json
from wisp_release.data import read_npz
from wisp_release.checkpoints import load_checkpoint, predict_checkpoint

data = read_npz("input.npz")
with open("checkpoint.json", encoding="utf-8") as stream:
    metadata = json.load(stream)
model = load_checkpoint(
    "model.pkl",
    trust_pickle=True,
    expected_sha256="VERIFIED_SHA256_DIGEST",  # replace with a verified 64-hex digest
)
prediction = predict_checkpoint(
    model,
    data["X"],
    subject=data.get("subject"),
    time_index=data.get("time_index"),
    metadata=metadata,
    n_jobs=1,
)

prediction contains encoded integer class IDs on the fitted checkpoint's class axis. Map them to the recorded global label_names; do not construct a new mapping from the predictions. The metadata JSON can check time/channel shape and class-index bounds, but it cannot automatically detect a swapped sensor axis or an incorrect physical unit.