LoRA adapters

Overview

A LoRA adapter is a small set of weights applied on top of a loaded base model, swapping the model’s behavior without reloading multi-gigabyte weights. Every LoRA call goes through the RunAnywhere.lora namespace, not through top-level extension functions. There is no loadLoraAdapter(), removeLoraAdapter(), clearLoraAdapters(), or getLoadedLoraAdapters().

Imports

import ai.runanywhere.proto.v1.LoraAdapterCatalogEntry
import ai.runanywhere.proto.v1.LoraAdapterCatalogQuery
import com.runanywhere.sdk.public.RunAnywhere
import com.runanywhere.sdk.public.extensions.lora
import com.runanywhere.sdk.public.types.RALoRAAdapterConfig
import com.runanywhere.sdk.public.types.RALoRAApplyRequest
import com.runanywhere.sdk.public.types.RALoRARemoveRequest

RunAnywhere.lora is a property returning a stateless LoRA namespace. All of its members are suspend functions.

Basic usage

// A base LLM must already be loaded.
val adapters = RunAnywhere.lora.adaptersForModel(baseModelId)
val entry = adapters.first()

val path = entry.local_path?.takeIf { it.isNotBlank() }
    ?: RunAnywhere.lora.download(entry) { progress -> updateProgress(progress) }

val result = RunAnywhere.lora.apply(
    entry = entry,
    localPath = path,
    scale = entry.default_scale.takeIf { it > 0f } ?: 1f,
    replaceExisting = true,
)

if (result.success) {
    println(RunAnywhere.generate("What are the symptoms of diabetes?").text)
} else {
    showError(result.error_message ?: "Apply failed")
}

apply() returns a LoRAApplyResult with a success flag; check it rather than relying on an exception.

Applying by path

The catalog-entry form is a convenience. The general form takes the generated request:

RunAnywhere.lora.apply(
    RALoRAApplyRequest(
        adapters = listOf(
            RALoRAAdapterConfig(adapter_path = "/path/to/adapter.gguf", scale = 1f),
        ),
        replace_existing = false,
    ),
)

LoRAAdapterConfig carries adapter_path, scale, adapter_id (links back to a catalog entry so commons can validate the adapter against the loaded base model), metadata, and target_modules.

Scale

scale controls how strongly the adapter shifts generation. 0.0 loads it inert, 1.0 is full strength, and values above 1.0 amplify. LoraAdapterCatalogEntry.default_scale carries the adapter author’s recommendation; fall back to 1f when it is 0.

Stacking

RALoRAApplyRequest.adapters is a list, and replace_existing = false keeps what is already applied. Both mechanisms stack adapters:

RunAnywhere.lora.apply(
    RALoRAApplyRequest(
        adapters = listOf(
            RALoRAAdapterConfig(adapter_path = medicalPath, scale = 1f),
            RALoRAAdapterConfig(adapter_path = conversationalPath, scale = 0.5f),
        ),
    ),
)

val active = RunAnywhere.lora.state().loaded_adapters.count { it.applied }

Removing

// Everything
RunAnywhere.lora.remove(RALoRARemoveRequest(clear_all = true))

// By id or path
RunAnywhere.lora.remove(RALoRARemoveRequest(adapter_ids = listOf("medical-qa-v1")))
RunAnywhere.lora.remove(RALoRARemoveRequest(adapter_paths = listOf(path)))

remove() returns the resulting LoRAState.

Inspecting state

val state = RunAnywhere.lora.state()     // or lora.list()
state.has_active_adapters                // Boolean
state.base_model_id                      // String?
state.loaded_adapters                    // List<LoRAAdapterInfo>

val activeId = state.loaded_adapters
    .firstOrNull { it.applied }
    ?.adapter_id
    ?.takeIf { it.isNotEmpty() }

LoRAAdapterInfo carries adapter_id, adapter_path, scale, applied, loaded_at_ms, error_message, and error_code.

Compatibility

val compat = RunAnywhere.lora.checkCompatibility(
    RALoRAAdapterConfig(adapter_path = path),
)
if (!compat.is_compatible) {
    showError(compat.error_message ?: "Adapter is not compatible with the loaded model")
}

checkCompatibility() returns an incompatible result rather than throwing, including when the underlying call fails. LoraCompatibilityResult carries is_compatible, error_message, base_model_required, warnings, and error_code.

Catalog

Registering an adapter records its metadata so it can be discovered per base model.

RunAnywhere.lora.register(
    LoraAdapterCatalogEntry(
        id = "medical-qa-v1",
        name = "Medical QA adapter",
        description = "Fine-tuned for medical question answering",
        url = "https://huggingface.co/your-org/medical-qa-lora/resolve/main/adapter.gguf",
        filename = "medical-qa.gguf",
        compatible_models = listOf("qwen-0.5b", "qwen-1.5b"),
        size_bytes = 25_000_000L,
        default_scale = 1f,
    ),
)

Field	Type	Description
`id`	`String`	Unique adapter identifier
`name`	`String`	Display name
`description`	`String`	What the adapter does
`url`	`String`	Direct download URL for the `.gguf`
`filename`	`String`	On-disk filename
`compatible_models`	`List<String>`	Base model ids
`size_bytes`	`Long`	`0` when unknown
`default_scale`	`Float`	Recommended scale
`checksum_sha256`	`String?`	Lowercase hex
`author`, `license`, `tags`, `metadata`		Catalog metadata
`local_path`	`String?`	Set after download or import
`is_downloaded`, `is_imported`, `downloaded_at_unix_ms`, `status_message`		Completion state

Note the field names: url not downloadUrl, compatible_models not compatibleModelIds, size_bytes not fileSize, default_scale not defaultScale. Discovery:

val forModel = RunAnywhere.lora.adaptersForModel("qwen-0.5b")
val all = RunAnywhere.lora.allRegistered()

val filtered = RunAnywhere.lora.queryCatalog(
    LoraAdapterCatalogQuery(downloaded_only = true, tags = listOf("medical")),
)

LoraAdapterCatalogQuery accepts adapter_id, model_id, downloaded_only, search_query, and tags. adaptersForModel() and allRegistered() throw SDKException when the underlying catalog call reports failure; queryCatalog() and listCatalog() return the result with its own success flag.

Downloading

val path = RunAnywhere.lora.download(entry) { progress ->
    val percent = if (progress.total_bytes > 0) {
        (progress.bytes_downloaded * 100 / progress.total_bytes).toInt()
    } else {
        (progress.stage_progress.coerceIn(0f, 1f) * 100).toInt()
    }
    updateProgress(percent)
}

One call registers the catalog entry and its download artifact, fetches the bytes through the shared model download pipeline (resume, checksum, progress), records completion in the LoRA catalog, and returns the local path. The progress callback is optional and suspending. total_bytes is 0 until the planner has sized the artifact, which is why the fallback on stage_progress is there.

Importing a local file

val result = RunAnywhere.lora.importAdapter(sourcePath)
val localPath = result.local_path

Your app resolves platform access (a content URI to a readable path) and nothing else. Commons owns catalog matching, canonical placement, registry records, and catalog completion. Apply the returned local_path; never construct an on-disk path yourself.

Full API

Member	Returns
`apply(request: RALoRAApplyRequest)`	`LoRAApplyResult`
`apply(entry, localPath, scale, replaceExisting)`	`LoRAApplyResult`
`applyCatalogAdapter(entry, localPath, scale, replaceExisting)`	`LoRAApplyResult`
`remove(request: RALoRARemoveRequest)`	`RALoRAState`
`list()`	`RALoRAState`
`state()`	`RALoRAState`
`checkCompatibility(config: RALoRAAdapterConfig)`	`LoraCompatibilityResult`
`register(entry)`	`LoraAdapterCatalogEntry`
`registerArtifact(entry)`	`RAModelInfo`
`download(entry, onProgress)`	`String` (local path)
`listCatalog(request)`	`LoraAdapterCatalogListResult`
`queryCatalog(query)`	`LoraAdapterCatalogListResult`
`getCatalogEntry(request)`	`LoraAdapterCatalogGetResult`
`markDownloadCompleted(request)`	`LoraAdapterDownloadCompletedResult`
`markImportCompleted(request)`	`LoraAdapterDownloadCompletedResult`
`importAdapter(sourcePath)`	`LoraAdapterImportResult`
`adaptersForModel(modelId)`	`List<LoraAdapterCatalogEntry>`
`allRegistered()`	`List<LoraAdapterCatalogEntry>`

ViewModel

class LoraViewModel : ViewModel() {
    var adapters by mutableStateOf<List<LoraAdapterCatalogEntry>>(emptyList())
        private set
    var activeId by mutableStateOf<String?>(null)
        private set

    fun apply(entry: LoraAdapterCatalogEntry, path: String) {
        viewModelScope.launch {
            try {
                val result = RunAnywhere.lora.apply(
                    entry = entry,
                    localPath = path,
                    scale = entry.default_scale.takeIf { it > 0f } ?: 1f,
                    replaceExisting = true,
                )
                if (result.success) activeId = entry.id
            } catch (e: CancellationException) {
                throw e
            } catch (e: Exception) {
                // surface e.message
            }
        }
    }

    fun clear() {
        viewModelScope.launch {
            RunAnywhere.lora.remove(RALoRARemoveRequest(clear_all = true))
            activeId = null
        }
    }

    private suspend fun reload(baseModelId: String) {
        adapters = RunAnywhere.lora.adaptersForModel(baseModelId)
        activeId = RunAnywhere.lora.state().loaded_adapters
            .firstOrNull { it.applied }
            ?.adapter_id
            ?.takeIf { it.isNotEmpty() }
    }
}

Notes

Every lora member throws SDKException with ERROR_CODE_NOT_INITIALIZED before RunAnywhere.initialize(), and each one runs the phase-2 service bootstrap on first use. Applying or removing an adapter recreates the inference context, so the KV cache is cleared and conversation history does not carry across a swap.

LLM generation

Text generation with options

LLM streaming

Streaming text generation

RAG pipeline

Retrieval-augmented generation

Best practices

Memory and lifecycle

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

Overview

Imports

Basic usage

Applying by path

Scale

Stacking

Removing

Inspecting state

Compatibility

Catalog

Downloading

Importing a local file

Full API

ViewModel

Notes

LLM generation

LLM streaming

RAG pipeline

Best practices

​Overview

​Imports

​Basic usage

​Applying by path

​Scale

​Stacking

​Removing

​Inspecting state

​Compatibility

​Catalog

​Downloading

​Importing a local file

​Full API

​ViewModel

​Notes

​Related

LLM generation

LLM streaming

RAG pipeline

Best practices

Overview

Imports

Basic usage

Applying by path

Scale

Stacking

Removing

Inspecting state

Compatibility

Catalog

Downloading

Importing a local file

Full API

ViewModel

Notes

Related