Model Loading

The LEAP SDK is now Kotlin Multiplatform and provides two model loading options:

LeapModelDownloader - Android-specific, recommended for Android apps (background downloads, notifications, WorkManager)
LeapDownloader - Cross-platform (Android, iOS, macOS, JVM), use for non-Android platforms or cross-platform code

`LeapModelDownloader` (Android)

The LeapModelDownloader class is the recommended option for Android applications. It provides Android-specific features including background downloads using WorkManager, foreground service notifications, and robust handling of network interruptions.

class LeapModelDownloader(
    private val context: Context,
    modelFileDir: File? = null,
    private val extraHTTPRequestHeaders: Map<String, String> = mapOf(),
    private val notificationConfig: LeapModelDownloaderNotificationConfig = LeapModelDownloaderNotificationConfig(),
)

This class is part of the ai.liquid.leap:leap-model-downloader module, which is Android-specific. For other platforms, see LeapDownloader below.

Constructor Parameters

Field	Type	Required	Default	Description
`context`	`Context`	Yes	-	Android context (Activity or Application context)
`modelFileDir`	`File`	No	`null`	Directory to save models. If null, uses app’s external files directory.
`extraHTTPRequestHeaders`	`Map<String, String>`	No	`mapOf()`	Additional HTTP headers for download requests
`notificationConfig`	`LeapModelDownloaderNotificationConfig`	No	`LeapModelDownloaderNotificationConfig()`	Notification configuration for the foreground service

`loadModel`

Download and load a model in one operation. If the model is already cached, it will be loaded directly without downloading. Arguments

Name	Type	Required	Default	Description
`modelSlug`	`String`	Yes	-	The name of the model to load (e.g., “LFM2-1.2B”). See the LEAP Model Library for available models.
`quantizationSlug`	`String`	Yes	-	The quantization level (e.g., “Q4_K_M”, “Q5_K_M”). See the LEAP Model Library for options.
`modelLoadingOptions`	`ModelLoadingOptions`	No	`null`	Options for loading the model. See `ModelLoadingOptions` for details.
`generationTimeParameters`	`GenerationTimeParameters`	No	`null`	Parameters to control model generation. See `GenerationTimeParameters` for details.
`progress`	`(ProgressData) -> Unit`	No	`{}`	Callback for download progress updates

Returns ModelRunner: A ModelRunner instance for interacting with the loaded model.

`downloadModel`

Download a model without loading it into memory. Useful for pre-downloading models in the background. Arguments

Name	Type	Required	Default	Description
`modelSlug`	`String`	Yes	-	The model name
`quantizationSlug`	`String`	Yes	-	The quantization level
`progress`	`(ProgressData) -> Unit`	No	`{}`	Callback for download progress

Returns Manifest: Metadata about the downloaded model

Example Usage

import ai.liquid.leap.model_downloader.LeapModelDownloader
import ai.liquid.leap.model_downloader.LeapModelDownloaderNotificationConfig

// Initialize downloader
val modelDownloader = LeapModelDownloader(
    context,
    notificationConfig = LeapModelDownloaderNotificationConfig.build {
        notificationTitleDownloading = "Downloading AI model..."
        notificationTitleDownloaded = "Model ready!"
    }
)

// Load model (downloads if needed)
lifecycleScope.launch {
    val modelRunner = modelDownloader.loadModel(
        modelSlug = "LFM2-1.2B",
        quantizationSlug = "Q5_K_M",
        progress = { progressData ->
            println("Progress: ${progressData.progress * 100}%")
        }
    )
    // Use modelRunner...
}

`LeapDownloader` (Cross-Platform)

The LeapDownloader class is a cross-platform model loader available in the core leap-sdk module. It works on Android, iOS, macOS, and JVM platforms. Use this for:

iOS and macOS applications
JVM/Desktop applications
Cross-platform Kotlin Multiplatform code
Android apps that don’t need background download features

class LeapDownloader(config: LeapDownloaderConfig = LeapDownloaderConfig())

Field	Type	Required	Default	Description
`config`	`LeapDownloaderConfig`	No	`LeapDownloaderConfig()`	Configuration options for the downloader. See `LeapDownloaderConfig` for more details.

`loadModel`

Download a model from the LEAP Model Library and load it into memory. If the model has already been downloaded, it will be loaded from the local cache without a remote request. Arguments

Name	Type	Required	Default	Description
`modelSlug`	`String`	Yes	-	The name of the model to load. See the LEAP Model Library for all available models.
`quantizationSlug`	`String`	Yes	-	The quantization level to download for the given model. See the LEAP Model Library for all available quantization levels.
`modelLoadingOptions`	`ModelLoadingOptions`	No	`null`	Options for loading the model. See `ModelLoadingOptions` for more details.
`generationTimeParameters`	`GenerationTimeParameters`	No	`null`	Parameters to control model generation at inference time. See `GenerationTimeParameters` for more details.
`progress`	`(ProgressData) -> Unit`	No	`{}`	A callback function to receive the download progress.

Returns ModelRunner: A ModelRunner instance that can be used to interact with the loaded model.

`downloadModel`

Download a model from the LEAP Model Library and save it to the local cache, without loading it into memory. Arguments

Name	Type	Required	Default	Description
`modelSlug`	`String`	Yes	-	The name of the model to download. See the LEAP Model Library for all available models.
`quantizationSlug`	`String`	Yes	-	The quantization level to download for the given model. See the LEAP Model Library for all available quantization levels.
`progress`	`(ProgressData) -> Unit`	No	`{}`	A callback function to receive the download progress.

Returns Manifest: The Manifest instance that contains the metadata of the downloaded model.

`LeapDownloaderConfig`

The LeapDownloaderConfig class contains all the configuration options for LeapDownloader. It is a data class with the following fields:

data class LeapDownloaderConfig (
    val saveDir: String = "leap_models", // The directory to save downloaded models.
    val validateSha256: Boolean = true, // Whether to validate the downloaded model's SHA256 checksum.
)

`GenerationTimeParameters`

The GenerationTimeParameters class contains all the parameters for controlling model generation. It is a data class with the following fields:

data class GenerationTimeParameters (
    val samplingParameters: SamplingParameters? = null, // optional, defaults to values from the model manifest
    val numberOfDecodingThreads: Int? = null, // optional, defaults to optimal number of threads at runtime
)

`SamplingParameters`

The SamplingParameters class contains sampling options to override the values provided in a model manifest. It is a data class with the following fields:

data class SamplingParameters (
    val temperature: Double? = null,
    val topP: Double? = null,
    val minP: Double? = null,
    val repetitionPenalty: Double? = null,
)

Note: LEAP models are generally trained to perform well with the given set of parameters defined in the model manifest (used by default). Overriding these values with the SamplingParameters class can result in degraded output quality - developers should proceed with caution.

`ProgressData`

The ProgressData class can be used to track download progress. It is a data class with the following fields:

data class ProgressData(
    val bytes: Long,
    val total: Long,
) {
    val progress: Float // Returns the progress percentage as a float between 0 and 1.
}

`Manifest`

The Manifest class is a wrapper class to read and encapsulate data read from the model manifests, and contains metadata about a downloaded model. It is a data class with the following fields:

data class Manifest(
    val schemaVersion: String,
    val inferenceType: String,
    val loadTimeParameters: LoadTimeParameters,
    val generationTimeParameters: GenerationTimeParameters? = null,
    val originalUrl: String? = null,
    val pathOnDisk: String? = null,
)

It is rarely necessary to instantiate a Manifest class directly. It is created internally by LeapDownloader to store and return metadata about downloaded models.

Legacy: LeapClient

The LeapClient class is a legacy class that is no longer recommended for use. It is still available for backward compatibility, but it is recommended to use the new LeapDownloader class instead.The entrypoint of LEAP SDK. It doesn’t hold any data.

object LeapClient {
  suspend fun loadModel(path: String, options: ModelLoadingOptions? = null): ModelRunner
  suspend fun loadModelAsResult(path: String, options: ModelLoadingOptions? = null): Result<ModelRunner>
  suspend fun loadModel(bundlePath: String, mmprojPath: String, options: ModelLoadingOptions? = null): ModelRunner
  suspend fun loadModel(bundlePath: String, mmprojPath: String, options: ModelLoadingOptions? = null): ModelRunner
  suspend fun loadModel(model: AudioGenerationModelDescriptor, options: ModelLoadingOptions? = null): ModelRunner
}

`loadModel`

This function can be called from UI thread. The app should hold the ModelRunner object returned by this function until there is no need to interact with the model anymore. See ModelRunner for more details.Arguments

path: A local path pointing to model bundle file. Both .bundle files and .gguf files are supported.
options: Options for loading the model.
mmprojPath: Optional multimodal projection model path. This parameter should only be filled if the model needs a separate multimodal projection model to parsing multimodal (image, audio, etc.) contents.

The function will throw LeapModelLoadingException if LEAP fails to load the model.

`AudioGenerationModelDescriptor`

For audio generation model, an instance of AudioGenerationModelDescriptor contains all components that are necessary for audio generation.

data class AudioGenerationModelDescriptor(
    val modelPath: String,
    val mmprojPath: String,
    val audioDecoderPath: String,
    val audioTokenizerPath: String? = null,
)

modelPath: Main model path.
mmprojPath: Multimodal projection model path.
audioDecoderPath: Audio decoder model path.
audioTokenizerPath: Audio tokenizer model path.

`loadModelAsResult`

This function can be called from UI thread. The path should be a local path pointing to model bundle file. This function is merely a wrapper around loadModel function to return a Result.

`ModelLoadingOptions`

A data class to represents options in loading a model.

data class ModelLoadingOptions(var randomSeed: Long? = null, var cpuThreads: Int = 2) {
    companion object {
        fun build(action: ModelLoadingOptions.() -> Unit): ModelLoadingOptions
    }
}

randomSeed: Set the random seed for loading the model to reproduce the output
cpuThreads: How many threads to use in the generation.

Kotlin builder function ModelLoadingOptions.build is also available. For example, loading a model with 4 CPU threads can be done by

val modelRunner = LeapClient.loadModel(
    MODEL_PATH,
    ModelLoadingOptions.build {
        cpuThread = 4
    }
)

Get Started

iOS

Android

Model Bundling Service

`LeapModelDownloader` (Android)

Constructor Parameters

`loadModel`

`downloadModel`

Example Usage

`LeapDownloader` (Cross-Platform)

`loadModel`

`downloadModel`

`LeapDownloaderConfig`

`GenerationTimeParameters`

`SamplingParameters`

`ProgressData`

`Manifest`

`loadModel`

`AudioGenerationModelDescriptor`

`loadModelAsResult`

`ModelLoadingOptions`

Get Started

iOS

Android

Model Bundling Service

​LeapModelDownloader (Android)

​Constructor Parameters

​loadModel

​downloadModel

​Example Usage

​LeapDownloader (Cross-Platform)

​loadModel

​downloadModel

​LeapDownloaderConfig

​GenerationTimeParameters

​SamplingParameters

​ProgressData

​Manifest

​loadModel

​AudioGenerationModelDescriptor

​loadModelAsResult

​ModelLoadingOptions

`LeapModelDownloader` (Android)

Constructor Parameters

`loadModel`

`downloadModel`

Example Usage

`LeapDownloader` (Cross-Platform)

`loadModel`

`downloadModel`

`LeapDownloaderConfig`

`GenerationTimeParameters`

`SamplingParameters`

`ProgressData`

`Manifest`

`loadModel`

`AudioGenerationModelDescriptor`

`loadModelAsResult`

`ModelLoadingOptions`