README

alta-mlcore

alta-mlcore is reusable infrastructure for building machine-learning models in Python. It provides configuration, dataset utilities, losses, metrics, training and evaluation loops, checkpointing, export, and inference components that model projects can extend.

The package provides common building blocks, not ready-made model architectures or datasets. Model architecture, data loading, and preprocessing remain part of the project using the package. Python 3.11 or newer is required. The installed Python import root is altametris.mlcore.

Structure

altametris/mlcore/
├── config/       Configuration schemas and defaults
├── data/         Dataset base class, label statistics, and weights
├── models/       Model contract and checkpoint handling
├── losses/       Built-in and composite losses
├── metrics/      Segmentation and detection metrics
├── optim/        Optimizer and scheduler builders
├── engine/       Training and evaluation loops
├── export/       Model export, including ONNX
├── inference/    Predictors and runtime backends
├── tracking/     Logging and optional MLflow helpers
└── utils/        Device, tensor, and import helpers

notebooks/        Guided tutorials
tests/            Package tests, grouped by module

Installation

Install the core package:

pip install alta-mlcore

For PyTorch model development and training, install the torch extra:

pip install "alta-mlcore[torch]"

For ONNX Runtime inference, install the onnx extra:

pip install "alta-mlcore[onnx]"

This supports inference without installing PyTorch:

from altametris.mlcore.inference import BasePredictor

predictor = BasePredictor.load("model.onnx")
predictor = BasePredictor.load("model.onnx", "metadata.json")  # Separate metadata path
outputs = predictor.predict(input_array)  # input_array is a numpy.ndarray

Keep the exported JSON metadata sidecar next to the ONNX file. Custom model and label configuration classes referenced by the metadata must be importable without PyTorch; define them in a separate module from Torch-based model implementations. String and pathlib.Path metadata paths are supported, positionally or as metadata_path=.... The backend and predictor_kwargs arguments are keyword-only; replace older calls such as load(path, "torch") with load(path, backend="torch").

For PyTorch-based ONNX export and ONNX Runtime inference, install both extras and onnx:

pip install "alta-mlcore[torch,onnx]" onnx

Notebook data

The data needed for the notebooks is tracked with DVC and stored in Azure. With the Azure CLI installed, run the following commands from the repository root:

az login
pip install "alta-mlcore[dev]"
dvc remote modify --local azure_remote sas_token 'mysastoken'
dvc pull

The dev extra includes DVC and its Azure storage support. Replace mysastoken with a valid SAS token for the configured Azure storage. The --local option keeps the token in Git-ignored local DVC configuration; do not commit or share the token.

Documentation

For a guided introduction, see the tutorial notebooks:

  1. Overview

  2. Configuration

  3. Data, training, and evaluation

  4. Export and inference

For API details, extension points, configuration behavior, and component contracts, see documentation.md.