Package boundaries and migration

fovi is one distribution. Install fovi for sensing and KNN layers, fovi[models] for complete networks, and fovi[training] for model and training dependencies. fovi[all] includes every declared optional dependency, the union selected by fovi[models,training]. FFCV-SSL is an external prerequisite installed manually for the built-in data loaders; no extra installs it. CuPy and Warp are base dependencies, so all installation variants include the optimized kernel libraries.

The model and training requirement files are reused when building extras metadata, so their dependency lists have a single source of truth. The wheel includes every namespace, even when its optional dependencies are not installed. Missing capability dependencies raise an error containing the appropriate installation command.

The models extra requires PyTorch 2.5 or later for the public state-dict pre-load hook used by DINO checkpoint compatibility.

Imports

Capability	Public location
Coordinates, retinal transforms, image samplers, fixation policies	`fovi.sensing`
KNN convolution/pooling and CUDA/Warp kernels	Existing `fovi.arch.knn*` primitive modules
Shared MLP, normalization, padding, wrapper primitives	Existing `fovi.arch.mlp`, `norm`, `polar`, `wrapper`
AlexNet, ResNet, ConvNeXt, ViT, DINOv3 and their foveated variants	`fovi.models` modules, such as `fovi.models.knnresnet`
FoviNet and architecture registry	`from fovi.models import FoviNet, ARCHITECTURE_REGISTRY`
Model configuration, checkpoints, inference construction	`fovi.models.loading`
Hub downloads	`fovi.models.hub`
Trainer and training restoration	`fovi.training`
FFCV loader	`fovi.training.loader`
Losses, schedules, KNN probes, FLOP analysis, backup	`fovi.training.utils` modules
Experiment visualizer	`fovi.training.visualizer`

Shared numerical and image transforms remain in fovi.utils and fovi.utils.fastaugs. Importing those transforms no longer attempts to load FFCV. Plotly/video helpers import their optional dependencies only when called.

Pure-Torch losses and schedulers can be imported without the training extra. Each helper requires only the libraries it uses. Importing Trainer requires the training dependencies and research paths, but does not import FFCV. Its built-in create_train_loader and create_val_loader methods require FFCV-SSL and raise with a link to the manual installation instructions when it is missing. Training without FFCV requires external training code or a Trainer subclass that supplies both loaders; selecting training does not introduce a new automatic data-loading backend.

For validation or activation extraction, set training.eval_only=True and data.train_dataset=None. The Trainer creates only the validation loader and restores weights without optimizer state. Calling train() in this mode raises.

Complete-model imports must use fovi.models. The old architecture modules, fovi.fovinet, fovi.probes, fovi.hub, and root model exports have been removed. For example, replace fovi.arch.knnvit with fovi.models.knnvit, import FoviNet from fovi.models, and import checkpoint helpers from fovi.models.loading. KNN primitives such as fovi.arch.knn remain in their existing locations.

This is a Python import-path change, not a checkpoint-key change. Published Hub state dictionaries and the DINO/LoRA compatibility hook do not depend on these aliases. Old scripts, dotted configuration targets, and pickled whole-model objects using the removed paths need migration; prefer saving model state dictionaries.

Old training utility modules, root trainer exports, and fovi.visualizer still forward to their new locations. from fovi.trainer import load_config also remains available; new code should import it from fovi.models.loading.

Prefer explicit imports. from fovi import * resolves the trainer and needs the training dependencies and configured research paths. A plain import fovi does not resolve those exports.

Incidental imports from the old root are not public re-exports: import HiddenPrints from fovi.utils, storage paths from fovi.paths, and OmegaConf from omegaconf. Import submodules explicitly rather than assuming that import fovi populates every fovi.arch attribute. fovi.trainer.get_relative_path was an internal loader helper and has been removed. Request FlashLoader explicitly from fovi.training.loader; wildcard imports of image transforms do not pull in a data loader.

Inference configuration and checkpoints

from fovi.models import get_model_from_base_fn
from fovi.models.loading import load_config

cfg, checkpoint, key = load_config("my_model", load=True, folder="/models", device="cpu")
model = get_model_from_base_fn("my_model", model_dirs=["/models"], device="cpu")

The loader preserves Hydra YAML, standalone Hydra configuration, and legacy params.json formats; sharded checkpoints, state_dict.pth, final_weights.pth, and model.pth retain their precedence and state keys. Distributed module. prefixes are removed during inference restoration. The requested device applies to checkpoint tensors as well as model construction.

DINOv3 restores the known Transformers layer, encoder.layer, and model.layer checkpoint prefixes to the active layout, including LoRA parametrizations. Shape errors, missing keys, and unknown keys still fail strict loading. Existing Hub checkpoints do not need to be rewritten; the configuration must construct the same model and LoRA adapters.

Inference does not import fovi.paths, build a trainer, initialize datasets, or configure experiment tracking. Reading legacy JSON no longer creates a Hydra YAML file beside it. An existing but broken local model now raises its actual error instead of silently trying a different checkpoint from the Hub. If no local model exists, Hub download remains supported.

find_config defaults to ../models and appends configured FOVI_SAVE_DIR/logs and FOVI_SLOW_DIR/logs directories if present. get_model_from_base_fn keeps its existing default search location of ../models. Explicit search directories take precedence.

Development validation

python -m pytest tests/test_package_boundaries.py tests/test_model_loading.py
uv build --wheel
python scripts/check_distribution.py dist/fovi-*.whl

Boundary tests start fresh processes without research environment variables and reject imports across the sensing/model/training boundaries. Loading tests restore local CPU checkpoints without network access or training. Run the existing sensing and model tests after moving any of those implementations. Built-in loader runtime checks require a working FFCV-SSL native installation; installing only the models extra does not provide that runtime.

See versions and releases for the 1.0 baseline and 2.0 release.