Model Loading

API reference for loading models in the LEAP SDK

The LEAP SDK provides multiple model loading options:

• LeapModelDownloader — Platform-specific downloader with background download support (Android: WorkManager + notifications; Apple: NSURLSession background downloads)
• LeapDownloader — Cross-platform (Android, iOS, macOS, JVM), lightweight downloader for all platforms
• Leap.load() — Swift convenience API via the compatibility layer

LeapModelDownloader

The recommended option for production apps on Android and Apple platforms. It provides platform-specific features for robust background downloads.

Kotlin

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. It uses Android WorkManager for background downloads and displays foreground service notifications.

Constructor Parameters

Field	Type	Required	Default	Description
context	Context	Yes	-	Android context (Activity or Application)
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 loads directly without downloading.

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

Returns: ModelRunner instance.

downloadModel

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

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

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

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

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

Swift

On Apple platforms, LeapModelDownloader supports background downloads via NSURLSessionConfiguration.

import LeapModelDownloader

let downloader = LeapModelDownloader()

// Download and get manifest
let manifest = try await downloader.downloadModel(
    model: "LFM2-1.2B",
    quantization: "Q5_K_M"
) { fraction, bytesPerSecond in
    print("Progress: \(Int(fraction * 100))%")
}

// Query download status
let status = await downloader.queryStatus(
    model: "LFM2-1.2B",
    quantization: "Q5_K_M"
)
switch status {
case .notOnLocal:
    print("Model not downloaded")
case .downloadInProgress(let progress):
    print("Downloading: \(Int(progress * 100))%")
case .downloaded:
    print("Model ready")
}

// Remove downloaded model
try await downloader.removeModel(
    model: "LFM2-1.2B",
    quantization: "Q5_K_M"
)

Leap.load() (Swift)

Leap is the static entry point for loading models on Apple platforms via the Swift compatibility layer.

Leap.load(model:quantization:options:downloadProgressHandler:)

Download a model from the LEAP Model Library and load it into memory. If already downloaded, it loads from the local cache.

public struct Leap {
  public static func load(
    model: String,
    quantization: String,
    options: LiquidInferenceEngineManifestOptions? = nil,
    downloadProgressHandler: @escaping (_ progress: Double, _ speed: Int64) -> Void
  ) async throws -> ModelRunner
}

Name	Type	Required	Default	Description
model	String	Yes	-	The model name. See the LEAP Model Library.
quantization	String	Yes	-	The quantization level.
options	LiquidInferenceEngineManifestOptions	No	nil	Override options for loading (advanced).
downloadProgressHandler	(Double, Int64) -> Void	No	nil	Progress callback (0–1 fraction, bytes/sec).

Returns: ModelRunner instance.

Legacy: Leap.load(url:options:)

Load a local model file (.bundle or .gguf) directly:

public struct Leap {
  public static func load(
    url: URL,
    options: LiquidInferenceEngineOptions? = nil
  ) async throws -> ModelRunner
}

// ExecuTorch backend via .bundle
let bundleURL = Bundle.main.url(forResource: "qwen3-0_6b", withExtension: "bundle")!
let runner = try await Leap.load(url: bundleURL)

// llama.cpp backend via .gguf
let ggufURL = Bundle.main.url(forResource: "qwen3-0_6b", withExtension: "gguf")!
let ggufRunner = try await Leap.load(url: ggufURL)

LiquidInferenceEngineOptions

Override runtime configuration when loading from a local file:

public struct LiquidInferenceEngineOptions {
  public var bundlePath: String
  public let cacheOptions: LiquidCacheOptions?
  public let cpuThreads: UInt32?
  public let contextSize: UInt32?
  public let nGpuLayers: UInt32?
  public let mmProjPath: String?
  public let audioDecoderPath: String?
  public let chatTemplate: String?
  public let audioTokenizerPath: String?
  public let extras: String?
}

• cpuThreads: Number of CPU threads for token generation.
• contextSize: Override maximum context length.
• nGpuLayers: Layers to offload to GPU (macOS/Mac Catalyst with Metal).
• mmProjPath: Auxiliary multimodal projection model path. Leave nil to auto-detect mmproj-*.gguf.
• audioDecoderPath: Audio decoder model. Leave nil to auto-detect.

let options = LiquidInferenceEngineOptions(
  bundlePath: bundleURL.path,
  cpuThreads: 6,
  contextSize: 8192
)
let runner = try await Leap.load(url: bundleURL, options: options)

LeapDownloader (Cross-Platform)

A lightweight, cross-platform model loader available in the core leap-sdk module. Works on all platforms (Android, iOS, macOS, JVM).

class LeapDownloader(config: LeapDownloaderConfig = LeapDownloaderConfig())

loadModel

Download and load a model. If already cached, loads from the local cache.

Name	Type	Required	Default	Description
modelSlug	String	Yes	-	The model name. See the LEAP Model Library.
quantizationSlug	String	Yes	-	The quantization level.
modelLoadingOptions	ModelLoadingOptions	No	null	Options for loading. See ModelLoadingOptions.
generationTimeParameters	GenerationTimeParameters	No	null	Generation parameters. See GenerationTimeParameters.
progress	(ProgressData) -> Unit	No	{}	Download progress callback.

Returns: ModelRunner instance.

downloadModel

Download a model without loading it into memory.

Name	Type	Required	Default	Description
modelSlug	String	Yes	-	The model name.
quantizationSlug	String	Yes	-	The quantization level.
progress	(ProgressData) -> Unit	No	{}	Download progress callback.

Returns: Manifest metadata about the downloaded model.

Supporting Types

LeapDownloaderConfig

data class LeapDownloaderConfig(
    val saveDir: String = "leap_models",
    val validateSha256: Boolean = true,
)

GenerationTimeParameters

data class GenerationTimeParameters(
    val samplingParameters: SamplingParameters? = null,
    val numberOfDecodingThreads: Int? = null,
)

SamplingParameters

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

LEAP models are trained to perform well with the default parameters from the model manifest. Overriding with SamplingParameters can degrade output quality.

ProgressData

data class ProgressData(
    val bytes: Long,
    val total: Long,
) {
    val progress: Float // 0.0 to 1.0
}

Manifest

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

ModelLoadingOptions

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

• randomSeed: Set the random seed to reproduce output.
• cpuThreads: Number of threads for generation.

Legacy: LeapClient

The LeapClient class is a legacy entry point. Use LeapDownloader or LeapModelDownloader instead.

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(model: AudioGenerationModelDescriptor, options: ModelLoadingOptions? = null): ModelRunner
}