feat(ios-sdk): add full LoRA adapter support with registry and compat check

Siddhesh2377 · Siddhesh2377 · commit 39049f627152 · 2026-02-24T02:26:29.000+05:30
diff --git a/sdk/runanywhere-commons/exports/RACommons.exports b/sdk/runanywhere-commons/exports/RACommons.exports
@@ -202,6 +202,25 @@ _rac_llm_component_load_model
 _rac_llm_component_supports_streaming
 _rac_llm_component_unload
 
+# LLM Component - LoRA
+_rac_llm_component_load_lora
+_rac_llm_component_remove_lora
+_rac_llm_component_clear_lora
+_rac_llm_component_get_lora_info
+_rac_llm_component_check_lora_compat
+
+# LoRA Registry
+_rac_lora_registry_create
+_rac_lora_registry_destroy
+_rac_lora_registry_register
+_rac_lora_registry_remove
+_rac_lora_registry_get_all
+_rac_lora_registry_get_for_model
+_rac_lora_registry_get
+_rac_lora_entry_free
+_rac_lora_entry_array_free
+_rac_lora_entry_copy
+
 # LLM Analytics
 _rac_llm_analytics_complete_generation
 _rac_llm_analytics_create
diff --git a/sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge+LLM.swift b/sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge+LLM.swift
@@ -128,6 +128,23 @@ extension CppBridge {
             logger.info("All LoRA adapters cleared")
         }
 
+        /// Check if a LoRA adapter is compatible with the currently loaded model
+        public func checkLoraCompatibility(loraPath: String) -> LoraCompatibilityResult {
+            guard let handle = handle else {
+                return LoraCompatibilityResult(isCompatible: false, error: "No LLM component active")
+            }
+            var errorPtr: UnsafeMutablePointer<CChar>?
+            let result = loraPath.withCString { pathPtr in
+                rac_llm_component_check_lora_compat(handle, pathPtr, &errorPtr)
+            }
+            if result == RAC_SUCCESS {
+                return LoraCompatibilityResult(isCompatible: true)
+            }
+            let errorMsg = errorPtr.map { String(cString: $0) }
+            if let ptr = errorPtr { rac_free(ptr) }
+            return LoraCompatibilityResult(isCompatible: false, error: errorMsg)
+        }
+
         /// Get info about all loaded LoRA adapters
         public func getLoadedLoraAdapters() throws -> [LoRAAdapterInfo] {
             guard let handle = handle else { return [] }
diff --git a/sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge+LoraRegistry.swift b/sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge+LoraRegistry.swift
@@ -0,0 +1,117 @@
+// CppBridge+LoraRegistry.swift
+// RunAnywhere SDK
+//
+// LoRA registry bridge - wraps C++ rac_lora_registry_* for adapter catalog management.
+
+import CRACommons
+import Foundation
+
+extension CppBridge {
+
+    // MARK: - LoRA Registry Bridge
+
+    /// Actor wrapping the C++ LoRA adapter registry.
+    /// Holds an in-memory catalog of adapters registered at startup.
+    public actor LoraRegistry {
+
+        /// Shared registry instance
+        public static let shared = LoraRegistry()
+
+        private var handle: rac_lora_registry_handle_t?
+        private let logger = SDKLogger(category: "CppBridge.LoraRegistry")
+
+        private init() {
+            var h: rac_lora_registry_handle_t?
+            let result = rac_lora_registry_create(&h)
+            if result == RAC_SUCCESS {
+                handle = h
+                logger.debug("LoRA registry created")
+            } else {
+                logger.error("Failed to create LoRA registry: \(result)")
+            }
+        }
+
+        deinit {
+            if let h = handle {
+                rac_lora_registry_destroy(h)
+            }
+        }
+
+        // MARK: - Registration
+
+        /// Register a LoRA adapter in the catalog
+        public func register(_ entry: LoraAdapterCatalogEntry) throws {
+            guard let handle = handle else {
+                throw SDKError.general(.initializationFailed, "LoRA registry not initialized")
+            }
+
+            // Allocate C strings via strdup so lifetime is independent of Swift strings
+            let cId = strdup(entry.id)
+            let cName = strdup(entry.name)
+            let cDesc = strdup(entry.adapterDescription)
+            let cUrl = strdup(entry.downloadURL.absoluteString)
+            let cFile = strdup(entry.filename)
+            let cCompatIds = entry.compatibleModelIds.map { strdup($0) }
+            defer {
+                [cId, cName, cDesc, cUrl, cFile].forEach { if let p = $0 { free(p) } }
+                cCompatIds.forEach { if let p = $0 { free(p) } }
+            }
+
+            var mutableCompatIds = cCompatIds
+            let result: rac_result_t = mutableCompatIds.withUnsafeMutableBufferPointer { compatBuf in
+                var cEntry = rac_lora_entry_t()
+                cEntry.id = cId
+                cEntry.name = cName
+                cEntry.description = cDesc
+                cEntry.download_url = cUrl
+                cEntry.filename = cFile
+                cEntry.compatible_model_ids = compatBuf.baseAddress
+                cEntry.compatible_model_count = entry.compatibleModelIds.count
+                cEntry.file_size = entry.fileSize
+                cEntry.default_scale = entry.defaultScale
+                return rac_lora_registry_register(handle, &cEntry)
+            }
+
+            guard result == RAC_SUCCESS else {
+                throw SDKError.general(.processingFailed, "Failed to register LoRA adapter '\(entry.id)': \(result)")
+            }
+            logger.info("LoRA adapter registered: \(entry.id)")
+        }
+
+        // MARK: - Queries
+
+        /// Get all registered LoRA adapters
+        public func getAll() -> [LoraAdapterCatalogEntry] {
+            guard let handle = handle else { return [] }
+
+            var entriesPtr: UnsafeMutablePointer<UnsafeMutablePointer<rac_lora_entry_t>?>?
+            var count: Int = 0
+            let result = rac_lora_registry_get_all(handle, &entriesPtr, &count)
+            guard result == RAC_SUCCESS, let entries = entriesPtr else { return [] }
+            defer { rac_lora_entry_array_free(entries, count) }
+
+            return (0..<count).compactMap { i in
+                guard let entry = entries[i] else { return nil }
+                return LoraAdapterCatalogEntry(from: entry.pointee)
+            }
+        }
+
+        /// Get LoRA adapters compatible with a specific model
+        public func getForModel(_ modelId: String) -> [LoraAdapterCatalogEntry] {
+            guard let handle = handle else { return [] }
+
+            var entriesPtr: UnsafeMutablePointer<UnsafeMutablePointer<rac_lora_entry_t>?>?
+            var count: Int = 0
+            let result = modelId.withCString { mid in
+                rac_lora_registry_get_for_model(handle, mid, &entriesPtr, &count)
+            }
+            guard result == RAC_SUCCESS, let entries = entriesPtr else { return [] }
+            defer { rac_lora_entry_array_free(entries, count) }
+
+            return (0..<count).compactMap { i in
+                guard let entry = entries[i] else { return nil }
+                return LoraAdapterCatalogEntry(from: entry.pointee)
+            }
+        }
+    }
+}
diff --git a/sdk/runanywhere-swift/Sources/RunAnywhere/Public/Extensions/LLM/LLMTypes.swift b/sdk/runanywhere-swift/Sources/RunAnywhere/Public/Extensions/LLM/LLMTypes.swift
@@ -405,7 +405,6 @@ public struct ThinkingTagPattern: Codable, Sendable {
 // MARK: - LoRA Adapter Types
 
 /// Configuration for loading a LoRA adapter.
-/// Mirrors the C++ LoraAdapterEntry and Kotlin LoRAAdapterConfig.
 public struct LoRAAdapterConfig: Sendable {
 
     /// Path to the LoRA adapter GGUF file
@@ -422,7 +421,6 @@ public struct LoRAAdapterConfig: Sendable {
 }
 
 /// Info about a loaded LoRA adapter (read-only).
-/// Mirrors the C++ LoRA info JSON structure.
 public struct LoRAAdapterInfo: Sendable {
 
     /// Path used when loading the adapter
@@ -435,6 +433,88 @@ public struct LoRAAdapterInfo: Sendable {
     public let applied: Bool
 }
 
+/// Catalog entry for a LoRA adapter registered with the SDK.
+/// Register adapters at app startup via RunAnywhere.registerLoraAdapter(_:).
+public struct LoraAdapterCatalogEntry: Sendable {
+
+    /// Unique adapter identifier
+    public let id: String
+
+    /// Human-readable display name
+    public let name: String
+
+    /// Short description of what this adapter does
+    public let adapterDescription: String
+
+    /// Direct download URL for the GGUF file
+    public let downloadURL: URL
+
+    /// Filename to save as on disk
+    public let filename: String
+
+    /// Model IDs this adapter is compatible with
+    public let compatibleModelIds: [String]
+
+    /// File size in bytes (0 if unknown)
+    public let fileSize: Int64
+
+    /// Recommended LoRA scale (e.g. 0.3 for F16 adapters on quantized bases)
+    public let defaultScale: Float
+
+    public init(
+        id: String,
+        name: String,
+        description: String,
+        downloadURL: URL,
+        filename: String,
+        compatibleModelIds: [String],
+        fileSize: Int64 = 0,
+        defaultScale: Float = 1.0
+    ) {
+        self.id = id
+        self.name = name
+        self.adapterDescription = description
+        self.downloadURL = downloadURL
+        self.filename = filename
+        self.compatibleModelIds = compatibleModelIds
+        self.fileSize = fileSize
+        self.defaultScale = defaultScale
+    }
+
+    // Internal init from C struct
+    init(from cEntry: rac_lora_entry_t) {
+        self.id = String(cString: cEntry.id)
+        self.name = String(cString: cEntry.name)
+        self.adapterDescription = String(cString: cEntry.description)
+        self.downloadURL = URL(string: String(cString: cEntry.download_url)) ?? URL(fileURLWithPath: "")
+        self.filename = String(cString: cEntry.filename)
+        var modelIds: [String] = []
+        if let ids = cEntry.compatible_model_ids {
+            for i in 0..<cEntry.compatible_model_count {
+                if let ptr = ids[i] { modelIds.append(String(cString: ptr)) }
+            }
+        }
+        self.compatibleModelIds = modelIds
+        self.fileSize = cEntry.file_size
+        self.defaultScale = cEntry.default_scale
+    }
+}
+
+/// Result of a LoRA compatibility pre-check.
+public struct LoraCompatibilityResult: Sendable {
+
+    /// Whether the adapter is compatible with the currently loaded model
+    public let isCompatible: Bool
+
+    /// Error message if not compatible
+    public let error: String?
+
+    public init(isCompatible: Bool, error: String? = nil) {
+        self.isCompatible = isCompatible
+        self.error = error
+    }
+}
+
 // MARK: - Structured Output Types
 
 /// Protocol for types that can be generated as structured output from LLMs
diff --git a/sdk/runanywhere-swift/Sources/RunAnywhere/Public/Extensions/LLM/RunAnywhere+LoRA.swift b/sdk/runanywhere-swift/Sources/RunAnywhere/Public/Extensions/LLM/RunAnywhere+LoRA.swift
@@ -1,24 +1,19 @@
+// RunAnywhere+LoRA.swift
+// RunAnywhere SDK
 //
-//  RunAnywhere+LoRA.swift
-//  RunAnywhere SDK
-//
-//  Public API for LoRA adapter management.
-//  Delegates to C++ via CppBridge.LLM for all operations.
-//
+// Public API for LoRA adapter management.
+// Runtime operations delegate to CppBridge.LLM; catalog operations delegate to CppBridge.LoraRegistry.
 
 import Foundation
 
 // MARK: - LoRA Adapter Management
 
 public extension RunAnywhere {
 
+    // MARK: Runtime Operations
+
     /// Load and apply a LoRA adapter to the currently loaded model.
-    ///
-    /// The adapter is loaded from a GGUF file and applied with the given scale.
     /// Multiple adapters can be stacked. Context is recreated internally.
-    ///
-    /// - Parameter config: LoRA adapter configuration (path and scale)
-    /// - Throws: `SDKError` if no model is loaded or loading fails
     static func loadLoraAdapter(_ config: LoRAAdapterConfig) async throws {
         guard isInitialized else {
             throw SDKError.general(.notInitialized, "SDK not initialized")
@@ -27,9 +22,6 @@ public extension RunAnywhere {
     }
 
     /// Remove a specific LoRA adapter by path.
-    ///
-    /// - Parameter path: Path that was used when loading the adapter
-    /// - Throws: `SDKError` if adapter not found or removal fails
     static func removeLoraAdapter(_ path: String) async throws {
         guard isInitialized else {
             throw SDKError.general(.notInitialized, "SDK not initialized")
@@ -38,8 +30,6 @@ public extension RunAnywhere {
     }
 
     /// Remove all loaded LoRA adapters.
-    ///
-    /// - Throws: `SDKError` if clearing fails
     static func clearLoraAdapters() async throws {
         guard isInitialized else {
             throw SDKError.general(.notInitialized, "SDK not initialized")
@@ -48,12 +38,37 @@ public extension RunAnywhere {
     }
 
     /// Get info about all currently loaded LoRA adapters.
-    ///
-    /// - Returns: List of loaded adapter info (path, scale, applied status)
     static func getLoadedLoraAdapters() async throws -> [LoRAAdapterInfo] {
         guard isInitialized else {
             throw SDKError.general(.notInitialized, "SDK not initialized")
         }
         return try await CppBridge.LLM.shared.getLoadedLoraAdapters()
     }
+
+    /// Check if a LoRA adapter file is compatible with the currently loaded model.
+    /// This is a lightweight pre-check; the definitive check happens on load.
+    static func checkLoraCompatibility(loraPath: String) async -> LoraCompatibilityResult {
+        guard isInitialized else {
+            return LoraCompatibilityResult(isCompatible: false, error: "SDK not initialized")
+        }
+        return await CppBridge.LLM.shared.checkLoraCompatibility(loraPath: loraPath)
+    }
+
+    // MARK: Catalog Operations
+
+    /// Register a LoRA adapter in the SDK catalog at app startup.
+    /// Call this before loading any adapters so the SDK knows what's available.
+    static func registerLoraAdapter(_ entry: LoraAdapterCatalogEntry) async throws {
+        try await CppBridge.LoraRegistry.shared.register(entry)
+    }
+
+    /// Get all LoRA adapters compatible with a specific model.
+    static func loraAdaptersForModel(_ modelId: String) async -> [LoraAdapterCatalogEntry] {
+        return await CppBridge.LoraRegistry.shared.getForModel(modelId)
+    }
+
+    /// Get all registered LoRA adapters.
+    static func allRegisteredLoraAdapters() async -> [LoraAdapterCatalogEntry] {
+        return await CppBridge.LoraRegistry.shared.getAll()
+    }
 }
