Packaging models

FLM file structure

The structure of an FLM file is thought to be as simple as possible, and aims at keeping in a single file all the information needed to load and use the model. The structure of an FLM file is as follows:

├── model.flm│   └── model│       ├── model (python object)│       └── meta│           ├── id│           ├── timestamp│           ├── framework│           ├── model│           │   ├── obj│           │   ├── info│           │   ├── params│           │   └── metrics│           └── extra└── artifacts    ├── foo.json    └── bar.csv

Dump method

Flama dump method uses optimal compression with the aim of making the packing process more efficient, and faster. The packing step can live completely out of any Flama application. Indeed, the natural place to package your models will be at the model-building stage, which will be very likely happening on your Jupyter notebook. An example of usage of this method:

import flama
flama.dump(    model,    path="path/to/file.flm",    compression="zstd",    model_id=uuid.uuid4(),    timestamp=datetime.datetime(2023, 3, 10, 11, 30, 0),    params={"optimizer": "adams"},    metrics={"recall": "0.95"},    extra={        "model_version": "1.0.0",        "model_description": "This is a test model",        "model_author": "John Doe",        "model_license": "MIT",        "tags": ["test", "example"],    },    artifacts={"foo.json": "path/to/artifact.json"},)

The first parameter is the model object itself, and the keyword argument path specifies where the resulting file will be stored. The remaining parameters are optional, and are used to add metadata to the resulting file which might be quite useful for model management purposes:

• model_id: a unique identifier for the model. If not provided, a random UUID will be generated.
• compression: the compression format to be used. It can be one of the following: "bz2", "lzma", "zlib", or "zstd". The default value is "zstd" (Zstandard), which offers an excellent balance between compression ratio and speed.
• timestamp: the timestamp of the model. If not provided, the current timestamp will be used.
• params: a dictionary containing hyper-parameters used to train the model.
• metrics: a dictionary containing metrics of the model, e.g. accuracy, recall, precision, etc.
• extra: a dictionary containing any other metadata you might want to add to the model. This is a good place to add information about model version, description, author, license, tags, etc.
• artifacts: a dictionary containing any artifacts associated with the model. The keys are the names of the artifacts, and the values are the paths to the files containing the artifacts. These files will be automatically packed and unpacked when the model is loaded.

Compression

When serialising ML models, the resulting binary data can be quite large, especially for deep learning models with millions of parameters. To address this, Flama applies compression to the model data during the packing process. The compression parameter of the dump method controls which algorithm is used, and this is one of the key features that makes FLM files lightweight.

Flama supports four compression formats, all of which are well-established algorithms widely used in the Python ecosystem:

• bz2 (Burrows-Wheeler): A block-sorting compressor that achieves good compression ratios but at the cost of slower compression and decompression speeds. Part of the Python standard library.
• lzma (Lempel-Ziv-Markov chain): Achieves the highest compression ratios among the supported formats, but is significantly slower than the alternatives. Part of the Python standard library.
• zlib (DEFLATE): A fast and well-proven compressor that offers good compression ratios with low latency. Part of the Python standard library.
• zstd (Zstandard): A modern compression algorithm developed by Meta, designed to provide compression ratios comparable to lzma while approaching the speed of zlib. This is the default format in Flama.

To illustrate the practical impact of these choices, the following table summarises the key characteristics of each format, measured on a simple Scikit-Learn model (MLPClassifier trained on XOR):

As the results clearly show, Zstandard ("zstd") stands out as the winner in most practical scenarios, combining the smallest file size with the fastest dump and load times. This is precisely why Flama uses it as the default compression format. For Python versions prior to 3.14, where zstd is not yet part of the standard library, Flama relies on the python-zstd package as a compatibility layer. From Python 3.14 onwards, zstd is included in the new compression standard library module, and Flama will use it natively.

You can specify the desired compression format when calling flama.dump:

import flama
# Using the default (zstd), recommended for most use casesflama.dump(model, path="model.flm")
# Explicitly specifying the compression formatflama.dump(model, path="model.flm", compression="lzma")  # Smallest file, slowest speedflama.dump(model, path="model.flm", compression="zlib")   # Good balance, no external dependencyflama.dump(model, path="model.flm", compression="bz2")    # Standard library alternative

The compression format is stored within the FLM file itself, so flama.load automatically detects and applies the correct decompression, you do not need to specify the format when loading:

model_artifact = flama.load(path="model.flm")  # Decompression is automatic

This transparent handling means you can change the compression format at any point without affecting downstream code that loads and uses the model.

Load method

Flama load method is responsible for the efficient unpacking of the model file. The unpacking stage will typically happen within the context of a Flama application. If you're not planning the development of any because you'll be using Flama CLI for this, then you won't have to use the load methods at all. An example of usage of this method:

import flama
model_artifact = flama.load(path="path/to/file.flm")

The keyword argument path specifies the path to the file containing the model. The method returns a ModelArtifact object, which contains the attributes used with the dump method, plus the model itself. The model can be accessed through the model attribute of the ModelArtifact object. As you can easily check, this object contains the artifacts dictionary, which you can inspect to find the path where the artifacts were unpacked automatically. This is a very convenient feature, which allows you to keep track of the artifacts associated with your model, and access them easily, all within the same binary file.

Once we have introduced the methods which allow for packing (flama.dump) and loading (flama.load), we can proceed and introduce how the example files we've been using so far were generated. These files were:

• Scikit Learn model
• TensorFlow model
• PyTorch model

Scikit-Learn

import flamafrom sklearn.neural_network import MLPClassifier
model = MLPClassifier(activation="tanh", max_iter=2000, hidden_layer_sizes=(10,))model.fit(    np.array([[0, 0], [0, 1], [1, 0], [1, 1]]),    np.array([0, 1, 1, 0]),)
flama.dump(model, path="sklearn_model.flm")

TensorFlow

import flamaimport tensorflow as tf
model = tf.keras.models.Sequential(    [        tf.keras.layers.Flatten(input_shape=(2,)),        tf.keras.layers.Dense(10, activation="tanh"),        tf.keras.layers.Dense(1, activation="sigmoid"),    ])
model.compile(optimizer="adam", loss="mse")model.fit(    np.array([[0, 0], [0, 1], [1, 0], [1, 1]]),    np.array([[0], [1], [1], [0]]),    epochs=2000,    verbose=0,)
flama.dump(model, path="tensorflow_model.flm")

PyTorch

import flamaimport torch
class Model(torch.nn.Module):    def __init__(self):        super().__init__()        self.l1 = torch.nn.Linear(2, 10)        self.l2 = torch.nn.Linear(10, 1)
    def forward(self, x):        x = torch.tanh(self.l1(x))        x = torch.sigmoid(self.l2(x))        return x
    def _train(self, X, Y, loss, optimizer):        for m in self.modules():            if isinstance(m, torch.nn.Linear):                m.weight.data.normal_(0, 1)
        steps = X.size(0)        for i in range(2000):            for j in range(steps):                data_point = np.random.randint(steps)                x_var = torch.autograd.Variable(X[data_point], requires_grad=False)                y_var = torch.autograd.Variable(Y[data_point], requires_grad=False)
                optimizer.zero_grad()                y_hat = model(x_var)                loss_result = loss.forward(y_hat, y_var)                loss_result.backward()                optimizer.step()
        return self

X = torch.Tensor([[0, 0], [0, 1], [1, 0], [1, 1]])Y = torch.Tensor([0, 1, 1, 0]).view(-1, 1)model = Model()model._train(X, Y, loss=torch.nn.BCELoss(), optimizer=torch.optim.Adam(model.parameters()))
flama.dump(model, path="pytorch_model.flm")