blinklinmult.models

Loading trained v2 models for inference, without the training stack.

BlinkCNN’s weights live in a Lightning checkpoint, but nothing about running one needs Lightning. Importing blinklinmult.train.module pulls in lightning, torchmetrics, h5py, omniloader and pandas – five packages an inference caller has no use for – so this module rebuilds the bare Module from the checkpoint’s own stored hyperparameters instead.

That is possible because the checkpoint is self-describing: save_hyperparameters stores model_config and train_config as plain dicts (deliberately, so weights_only=True loading works), and build_model can rebuild the network from them. The weights then load with zero missing and zero unexpected keys.

Published weights are stripped of optimizer and loop state before upload – 57 MB of Lightning checkpoint is only 19.1 MB of parameters – so load_checkpoint() accepts both shapes: a full training checkpoint from results/, and the slim published file.

Attributes

logger	Module-level logger.
RETIRED_1X_MODELS	Names blinklinmult.models exported in 1.x, when it was a package.
MODEL_PREFIX	Prefix Lightning adds to the wrapped network's parameter names.
DEFAULT_TARGETS	Head names assumed when a checkpoint does not record its own.

Exceptions

ModelLoadError

Raised when a checkpoint cannot be rebuilt into a usable model.

Functions

strip_checkpoint(→ dict[str, Any])	Reduce a training checkpoint to what inference needs.
load_checkpoint(→ blinklinmult.train.model.BlinkModel)	Rebuild a trained v2 model from its checkpoint, ready for inference.
__getattr__(→ object)	Explain the 1.x models' move rather than failing opaquely.

Module Contents

blinklinmult.models.logger

Module-level logger.

blinklinmult.models.RETIRED_1X_MODELS = ('DenseNet121', 'BlinkLinT', 'BlinkLinMulT', 'LinT', 'AbstractModule')

Names blinklinmult.models exported in 1.x, when it was a package.

It is a module now, and a different one: this file loads trained v2 checkpoints. An old script importing one of these gets a bare “cannot import name” otherwise, which says nothing about where the models went – so __getattr__() answers that instead. See docs/migration.md.

blinklinmult.models.MODEL_PREFIX = 'model.'

Prefix Lightning adds to the wrapped network’s parameter names.

blinklinmult.models.DEFAULT_TARGETS = ['eye_state']

Head names assumed when a checkpoint does not record its own.

exception blinklinmult.models.ModelLoadError

Bases: Exception

Raised when a checkpoint cannot be rebuilt into a usable model.

Initialize self. See help(type(self)) for accurate signature.

blinklinmult.models.strip_checkpoint(checkpoint: dict[str, Any]) → dict[str, Any]

Reduce a training checkpoint to what inference needs.

Drops optimizer state, LR schedules, loop counters and callback state, all of which exist to resume training and are dead weight in a published artifact. On fw-focal-augment this takes 57 MB down to 19.1 MB.

Parameters:

checkpoint (dict[str, Any]) – A loaded Lightning checkpoint.

Returns:

{"state_dict", "hyper_parameters"} only.

Return type:

dict[str, Any]

Raises:

ModelLoadError – If either required key is absent.

blinklinmult.models.load_checkpoint(path: str | pathlib.Path) → blinklinmult.train.model.BlinkModel

Rebuild a trained v2 model from its checkpoint, ready for inference.

Parameters:

path (str | Path) – A full training checkpoint or a stripped published one.

Returns:

The network in eval mode with its weights loaded.

Return type:

BlinkModel

Raises:

ModelLoadError – If the file is not a usable checkpoint, or its weights do not fit the architecture its own hyperparameters describe.

blinklinmult.models.__getattr__(name: str) → object

Explain the 1.x models’ move rather than failing opaquely.

Parameters:

name (str) – The attribute being looked up.

Returns:

Never returns; the lookup always fails.

Return type:

object

Raises:

AttributeError – Naming the replacement when a retired 1.x symbol is asked for, and the plain message otherwise.