ModelZone SDK

Track training runs locally, save model artifacts, and share them through Azure ML. A run is one training attempt. Registering a run gives its code and artifacts a model name and version for use in inference.

Contents

• Installation
• Workflow
• Model artifacts
• Logging
• CLI options
• Examples

Installation

Requires Python 3.13 or newer. For local tracking and artifact loading:

pip install modelzone-sdk

For Azure ML uploads, registration, and downloads:

pip install modelzone-sdk[azureml]

The authentication with Azure ML uses DefaultAzureCredential. Ensure an identity with access to your workspace is logged in (default approach would be via AzureCLI).

Workflow

1. Train locally

Wrap your training function with mz.default_cli. In mypackage/experiment.py:

import modelzone as mz

def train():
    mz.tracker.log_metric("MAE", 1.23)

def main():
    mz.default_cli(train)

Replace the example metric with your training code. Add a train command to the training project's pyproject.toml:

[project.scripts]
train = "mypackage.experiment:main"

Install the project, then run it:

python -m pip install -e .
train

Each run saves a code snapshot and logged outputs under .runs/<timestamp>. The folder ends in __FINISHED or __FAILED when the run ends. It lives beside the nearest pyproject.toml above the training script; local runs do not need Azure settings.

Snapshots follow Git's ignore rules. Keep .runs/ and your virtual environment in .gitignore.

For custom training arguments, use mz.default_parser() and mz.run(__file__, ...) as shown in the training example. The train command belongs to your project, not the SDK CLI.

2. Upload a run

Add your Azure ML settings to the training project's pyproject.toml:

[tool.modelzone]
subscription_id = "<azure-subscription-id>"
resource_group = "<resource-group>"
workspace_name = "<azure-ml-workspace>"
experiment_name = "my_model"

To train and upload on success:

train --azureml

Or upload the latest successfully finished local run without training again:

modelzone upload

The default selects the newest timestamped __FINISHED directory in .runs/ beside the nearest pyproject.toml, including when called from a subdirectory. Failed and still-running runs are skipped. If no finished run exists, the command exits with an error.

To upload a specific run, pass its directory explicitly:

modelzone upload .runs/2026-07-16T12:11:55__FINISHED

Only finished runs can be uploaded. The saved results/run.json must contain status and duration_seconds. Upload copies the run to Azure ML's Output + logs and adds its tags and metrics. The duration_seconds metric records local training time, not upload time.

3. Register a model

When a model is ready for production, register the uploaded run in Azure ML's model registry:

modelzone register <run_id>

Find run_id in the run's Name property in Azure ML. Registration uses the run's uploaded output/ folder and creates the next version of the model named by experiment_name. The command prints the model name and version to use below.

4. Fetch for inference

In the inference project's pyproject.toml, set the workspace and the registered model name and version:

[tool.modelzone]
subscription_id = "<azure-subscription-id>"
resource_group = "<resource-group>"
workspace_name = "<azure-ml-workspace>"
model_name = "my_model"
model_version = 1

Fetch the model, then install its package in your inference environment:

modelzone fetch model
python -m pip install .model/package

modelzone fetch on its own is short for modelzone fetch model.

To try an uploaded run without registering it, use this fetch command instead:

modelzone fetch run --run-id <run_id>

Both methods download code to .model/package and artifacts to .model/artifacts in the current directory. Installation is always a separate step. Use --dest-dir <dir> to change the destination; only its package/ and artifacts/ folders are replaced, leaving other files untouched.

Model artifacts

Inherit from mz.Artifact to save and load your model using pickle. Define the class in an importable module such as mypackage/forecaster.py, not __main__:

import modelzone as mz

class Forecaster(mz.Artifact):
    def __init__(self, model):
        self.model = model

    def predict(self, features):
        return self.model.predict(features)

Inside your training function, wrap the fitted model and save it:

from mypackage.forecaster import Forecaster

mz.tracker.log_artifact("forecaster", Forecaster(fitted_model))

This writes artifacts/forecaster.pkl in the run. After fetching and installing the package, load it from an inference script at the project root:

from pathlib import Path

from mypackage.forecaster import Forecaster

artifacts_dir = Path(__file__).parent / ".model/artifacts"
forecaster = Forecaster.load("forecaster", artifacts_dir)

Adjust the artifact path if you used --dest-dir. Only load trusted artifacts: unpickling can execute code. The model's package and dependencies must be installed.

Logging

Use mz.tracker inside your tracked training function:

mz.tracker.log_metric("MAE", 1.23)
mz.tracker.log_metric("MAE_by_country", 1.23, dimensions={"country": "DK"})
mz.tracker.log_tag("model_type", "LinearRegression")
mz.tracker.log_message("Finished fitting the model")
mz.tracker.log_file("notes.txt", "Finished evaluating the model")
mz.tracker.log_file("payload.bin", b"example data")

For a Plotly figure, save its HTML as a file:

mz.tracker.log_file("forecast.html", fig.to_html())

Logs are saved under results/: metrics and tags as JSONL, files under files/, and messages in logs.log. Dimensioned metrics also get a text table in results/metrics/; use the same dimension keys for a given metric name.

Tracking calls require an active run. For tracking without code snapshots or uploads, use a with mz.LocalTracker(output_dir): block.

CLI options

modelzone upload, register, and fetch read [tool.modelzone] from the nearest pyproject.toml at or above the current directory.

An option is required when its setting is missing from [tool.modelzone], so no pyproject.toml is needed when all settings are supplied as options:

modelzone fetch run --run-id <run_id> --subscription-id <id> \
    --resource-group <group> --workspace-name <name>

Use modelzone <command> --help for the available options and configured values.

Examples

• Training project
• Inference project
• Full workflow script

To try local training, start at the repository root in a dedicated Python environment:

python -m pip install -e .
cd examples/training_example
python -m pip install -e .
train

For Azure ML support, install python -m pip install -e '.[train]' in the example directory. Its train extra installs the SDK's azureml extra.

The full workflow script resets its named Python environments, removes previous example outputs, and uploads and registers a model in Azure ML. Run it only when those side effects are intended.