Model Registry

With Chalk you can easily register and load machine learning models into your deployments. You can then run inference on these models. This guide covers how to integrate models into your Chalk applications, including loading existing models and running inference.

Chalk has a few key model concepts:

• Model Name: A namespace for a model (which might have multiple implementations).
• Model Version: A model that has been registered with a specific version number—these are models that can be loaded into Chalk deployments.
• Model Artifact: The actual files that make up a model, such as weights, configuration files, and tokenizers.
• Model Reference: A reference to a specific model version. Used to load models into deployments and track model performance and feature distributions for a deployed model.

Generally running inference on models in Chalk involves three steps:

1. Registering models in Chalk
2. Including models in Chalk deployments
3. Connecting your models to features for inference

​

Registering Models in Chalk

To add a model to the Chalk model registry, you can either register an existing model or run training code to create a new model. Once registered, models can be versioned and tracked over time. Registering models through training jobs is covered in the Chalk model training docs.

​

Registering Existing Models

Existing machine learning models can be registered in Chalk using the ChalkClient class. You can register models from local files, cloud storage, or directly from Python objects. All of these are supported through the client.register_model method.

​

Registering From Local Files

To register a model from local files, provide the path to the model files and any additional files needed for inference, such as tokenizers or configuration files. You’ll also want to specify the input and output schema for the model, which helps with validation and integration in your Chalk deployment.

When registering a new model, you can specify a description which will be shown for the Model object in the Chalk dashboard. To register a new model, you should use the client.register_model method. This will create a new model in the registry and add a new model version.

from chalk.client import ChalkClient

client = ChalkClient()

client.register_model(
    name="RiskScoreModel",
    aliases=["v1.0"],
    model_paths=["./risk_score_model.pth"],
    additional_files=[
        "./tokenizer.json"
    ],
    description="Model for predicting user risk scores",
    model_type="pytorch",
    model_format="pytorch",
    metadata={
        "framework": "pytorch",
        "training_date": "2025-07-29",
        "performance_metrics": {
            "accuracy": 0.95,
            "f1_score": 0.92
        }
    }
)

​

Registering From Python Model Objects

Models can also be registered directly from Python objects, such as Scikit-learn or PyTorch models. This allows you to register models directly from your code without needing to save them to disk first.

from chalk.client import ChalkClient
from sklearn.ensemble import RandomForestClassifier

client = ChalkClient()

rfc = RandomForestClassifier()

rfc.fit(X_train, y_train)


# Since the model has already been registered, we can create a new version by calling register_model_version
client.register_model_version(
    name="RiskScoreModel",
    aliases=["v1.0.0"],
    model=rfc,  # Directly pass the model object
    description="Model for predicting user risk scores",
    model_type="sklearn",
    model_format="pickle",
    metadata={
        "framework": "sklearn",
        "training_date": "2025-07-29",
        "performance_metrics": {
            "accuracy": 0.89,
            "precision": 0.91
        }
    }
)

​

Retrieving Model Information

Registered models are tracked in the Chalk Model Registry. They can be loaded through the client and queried for metadata such as versions and performance metrics. They can also be viewed in the Chalk Dashboard. If they’ve been included in a deployment, you will also see feature distributions and model performance over time.

# Get model metadata
model = client.get_model(name="RiskScoreModel")
print(f"Latest version: {model.latest_version}")
print(f"Available versions: {model.versions}")

# Get specific version details
model_v1 = client.get_model(name="RiskScoreModel", version=1)
print(f"Performance: {model_v1.metadata['training_metrics']}")

​

Including Models in Chalk Deployments

To include models in your Chalk deployment, use ModelReference objects. ModelReferences are code-defined objects which should be included in your Chalk code: they are used to connect model versions to model deployments.

from chalk.ml import ModelReference
from chalk import functions as F
from chalk.features import features

# Load a model into the deployment
churn_risk = ModelReference.from_version(
    name="ChurnModel",
    version=2,
)

# Reference the loaded model in inference
@features
class User:
    id: int
    age: int
    income: float
    churn_risk: float = F.inference(
        churn_risk, inputs=[
        _.age,
        _.income
    ])

Once the model is deployed, metrics for the model will be tracked in the Chalk dashboard, including feature distributions and performance over time.

​

Running Inference on Models

Once models are registered and loaded into your deployment, you can run inference on your models:

from chalk.ml import ModelReference
from chalk import functions as F
from datetime import datetime

# Load a model into the deployment using alias
risk_model_latest = ModelReference.from_alias(
    name="RiskScoreModel",
    alias="latest",
)

# Load a model into the deployment using version
risk_model_v1_0_0 = ModelReference.from_version(
    name="RiskScoreModel",
    version=1,
)

# Reference the loaded model(s) in inference
@features
class User:
    id: int
    age: int
    income: float
    risk_score: float = feature(versions={
        1: feature(description="Version 1.0.0", expression=F.inference(risk_model_v1_0_0, inputs=[_.age, 10, _.income]))
        2: feature(description="Latest model version", expression=F.inference(risk_model_latest, inputs=[_.age, 10, _.income])),
    })