> ## Documentation Index
> Fetch the complete documentation index at: https://liquidai-alay2shah-sync-notebook-snippets.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Model Loading
> API reference for loading models in the LEAP SDK
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.
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
class LeapModelDownloader(
private val context: Context,
modelFileDir: File? = null,
private val extraHTTPRequestHeaders: Map = 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`](#leapdownloader-cross-platform) 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` | 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](https://leap.liquid.ai/models) for available models. |
| `quantizationSlug` | `String` | Yes | - | The quantization level (e.g., "Q4\_K\_M", "Q5\_K\_M"). See the [LEAP Model Library](https://leap.liquid.ai/models) for options. |
| `modelLoadingOptions` | `ModelLoadingOptions` | No | `null` | Options for loading the model. See [`ModelLoadingOptions`](#modelloadingoptions) for details. |
| `generationTimeParameters` | `GenerationTimeParameters` | No | `null` | Parameters to control model generation. See [`GenerationTimeParameters`](#generationtimeparameters) for details. |
| `progress` | `(ProgressData) -> Unit` | No | `{}` | Callback for download progress updates |
**Returns**
`ModelRunner`: A [`ModelRunner`](./conversation-generation#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
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
class LeapDownloader(config: LeapDownloaderConfig = LeapDownloaderConfig())
```
| Field | Type | Required | Default | Description |
| -------- | ---------------------- | -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `config` | `LeapDownloaderConfig` | No | `LeapDownloaderConfig()` | Configuration options for the downloader. See [`LeapDownloaderConfig`](#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](https://leap.liquid.ai/models) for all available models. |
| `quantizationSlug` | `String` | Yes | - | The quantization level to download for the given model. See the [LEAP Model Library](https://leap.liquid.ai/models) for all available quantization levels. |
| `modelLoadingOptions` | `ModelLoadingOptions` | No | `null` | Options for loading the model. See [`ModelLoadingOptions`](#modelloadingoptions) for more details. |
| `generationTimeParameters` | `GenerationTimeParameters` | No | `null` | Parameters to control model generation at inference time. See [`GenerationTimeParameters`](#generationtimeparameters) for more details. |
| `progress` | `(ProgressData) -> Unit` | No | `{}` | A callback function to receive the download progress. |
**Returns**
`ModelRunner`: A [`ModelRunner`](./conversation-generation#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](https://leap.liquid.ai/models) for all available models. |
| `quantizationSlug` | `String` | Yes | - | The quantization level to download for the given model. See the [LEAP Model Library](https://leap.liquid.ai/models) for all available quantization levels. |
| `progress` | `(ProgressData) -> Unit` | No | `{}` | A callback function to receive the download progress. |
**Returns**
`Manifest`: The [`Manifest`](#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:
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
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.
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
object LeapClient {
suspend fun loadModel(path: String, options: ModelLoadingOptions? = null): ModelRunner
suspend fun loadModelAsResult(path: String, options: ModelLoadingOptions? = null): Result
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`](./conversation-generation#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.
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-result/).
## `ModelLoadingOptions`
A data class to represents options in loading a model.
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
val modelRunner = LeapClient.loadModel(
MODEL_PATH,
ModelLoadingOptions.build {
cpuThread = 4
}
)
```