llama-cpp-pro 0.2.2

package/ios/Sources/LlamaCppCapacitor/LlamaNativeBridge.swift

@@ -0,0 +1,349 @@
+import Foundation
+
+enum LlamaNativeBridge {
+    enum Failure: LocalizedError {
+        case missingSymbol(String)
+        case modelNotFound(String)
+        case initializationFailed(String)
+        case completionFailed(String)
+        case embeddingFailed(String)
+        case operationFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .missingSymbol(let symbol):
+                return "Native symbol \(symbol) is not linked. Rebuild llama-cpp.framework."
+            case .modelNotFound(let path):
+                return "Model file not found at \(path)"
+            case .initializationFailed(let details):
+                return "Failed to initialize llama context: \(details)"
+            case .completionFailed(let details):
+                return "Failed to run local completion: \(details)"
+            case .embeddingFailed(let details):
+                return "Failed to run local embedding: \(details)"
+            case .operationFailed(let details):
+                return "Operation failed: \(details)"
+            }
+        }
+    }
+
+    private typealias InitContextFn     = @convention(c) (UnsafePointer<CChar>, UnsafePointer<CChar>) -> Int64
+    private typealias ReleaseContextFn  = @convention(c) (Int64) -> Void
+    private typealias RunCompletionFn   = @convention(c) (Int64, UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar>?
+    private typealias FreeResultFn      = @convention(c) (UnsafeMutablePointer<CChar>) -> Void
+    private typealias StopCompletionFn  = @convention(c) (Int64) -> Void
+    private typealias RunEmbeddingJsonFn = @convention(c) (Int64, UnsafePointer<CChar>, UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar>?
+    private typealias JsonOpFn          = @convention(c) (Int64, UnsafePointer<CChar>, UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar>?
+    private typealias SingleArgJsonFn   = @convention(c) (Int64, UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar>?
+    private typealias BoolFn            = @convention(c) (Int64) -> Int32
+    private typealias BoolBoolFn        = @convention(c) (Int64, Int32) -> Int32
+    private typealias SessionSaveFn     = @convention(c) (Int64, UnsafePointer<CChar>, Int32) -> Int32
+    private typealias BenchFn           = @convention(c) (Int64, Int32, Int32, Int32, Int32) -> UnsafeMutablePointer<CChar>?
+    private typealias LoraApplyFn       = @convention(c) (Int64, UnsafePointer<CChar>) -> Int32
+    private typealias VoidFn            = @convention(c) (Int64) -> Void
+    private typealias MultimodalInitFn  = @convention(c) (Int64, UnsafePointer<CChar>, Int32) -> Int32
+    private typealias VocoderInitFn     = @convention(c) (Int64, UnsafePointer<CChar>, Int32) -> Int32
+
+    private static var library: UnsafeMutableRawPointer? = {
+        let fm = FileManager.default
+        var candidates: [String] = []
+        if let fw = Bundle.main.path(forResource: "llama-cpp", ofType: "framework") {
+            candidates.append((fw as NSString).appendingPathComponent("llama-cpp"))
+        }
+        if let exec = Bundle.main.executablePath {
+            candidates.append((exec as NSString).deletingLastPathComponent + "/Frameworks/llama-cpp.framework/llama-cpp")
+        }
+        for path in candidates where fm.fileExists(atPath: path) {
+            if let handle = dlopen(path, RTLD_NOW) {
+                return handle
+            }
+            print("[LlamaNativeBridge] dlopen failed for \(path): \(String(cString: dlerror()))")
+        }
+        print("[LlamaNativeBridge] llama-cpp framework binary not found; tried: \(candidates)")
+        return nil
+    }()
+
+    static func sym<T>(_ name: String, _ type: T.Type) throws -> T {
+        guard let library else {
+            throw Failure.missingSymbol(name)
+        }
+        guard let pointer = dlsym(library, name) else {
+            throw Failure.missingSymbol(name)
+        }
+        return unsafeBitCast(pointer, to: T.self)
+    }
+
+    static func trySymOpt<T>(_ name: String, _ type: T.Type) -> T? {
+        guard let library, let pointer = dlsym(library, name) else { return nil }
+        return unsafeBitCast(pointer, to: T.self)
+    }
+
+    // MARK: - Core
+
+    static func initContext(modelPath: String, paramsJson: String) throws -> Int64 {
+        let normalizedPath = normalizeModelPath(modelPath)
+        guard FileManager.default.fileExists(atPath: normalizedPath) else {
+            throw Failure.modelNotFound(normalizedPath)
+        }
+        let fn = try sym("llama_init_context", InitContextFn.self)
+        let id = normalizedPath.withCString { mp in
+            paramsJson.withCString { pj in fn(mp, pj) }
+        }
+        guard id > 0 else {
+            throw Failure.initializationFailed("native loader returned \(id) for \(normalizedPath)")
+        }
+        return id
+    }
+
+    static func releaseContext(_ contextId: Int64) {
+        guard let fn = try? sym("llama_release_context", ReleaseContextFn.self) else { return }
+        fn(contextId)
+    }
+
+    static func runCompletion(contextId: Int64, paramsJson: String) throws -> [String: Any] {
+        let fn   = try sym("llama_run_completion", RunCompletionFn.self)
+        let free = try sym("llama_free_completion_result", FreeResultFn.self)
+        let ptr  = paramsJson.withCString { fn(contextId, $0) }
+        guard let ptr else { throw Failure.completionFailed("nil result") }
+        defer { free(ptr) }
+        return try decodeJsonDictionary(from: ptr, failure: .completionFailed("invalid JSON"))
+    }
+
+    static func runEmbedding(contextId: Int64, text: String, paramsJson: String) throws -> [String: Any] {
+        let fn   = try sym("llama_run_embedding_json", RunEmbeddingJsonFn.self)
+        let free = try sym("llama_free_completion_result", FreeResultFn.self)
+        let ptr  = text.withCString { t in paramsJson.withCString { p in fn(contextId, t, p) } }
+        guard let ptr else { throw Failure.embeddingFailed("nil result") }
+        defer { free(ptr) }
+        return try decodeJsonDictionary(from: ptr, failure: .embeddingFailed("invalid JSON"))
+    }
+
+    static func stopCompletion(_ contextId: Int64) {
+        guard let fn = try? sym("llama_stop_completion", StopCompletionFn.self) else { return }
+        fn(contextId)
+    }
+
+    // MARK: - Rerank
+
+    /// Returns JSON: [{"score": float, "index": int}, ...]
+    static func runRerank(contextId: Int64, query: String, documentsJson: String) throws -> [[String: Any]] {
+        // llama_rerank_json(context_id, query_cstr, docs_json_cstr) -> char*
+        guard let fn: JsonOpFn = trySymOpt("llama_rerank_json", JsonOpFn.self),
+              let free: FreeResultFn = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_rerank_json")
+        }
+        let ptr = query.withCString { q in documentsJson.withCString { d in fn(contextId, q, d) } }
+        guard let ptr else { throw Failure.operationFailed("rerank returned nil") }
+        defer { free(ptr) }
+        let json = String(cString: ptr)
+        guard let data = json.data(using: .utf8),
+              let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
+            throw Failure.operationFailed("rerank returned invalid JSON")
+        }
+        return arr
+    }
+
+    // MARK: - Bench
+
+    /// Returns the raw bench result string "[modelDesc, size, nParams, ppAvg, ppStd, tgAvg, tgStd]"
+    static func runBench(contextId: Int64, pp: Int, tg: Int, pl: Int, nr: Int) throws -> String {
+        guard let fn: BenchFn = trySymOpt("llama_bench", BenchFn.self),
+              let free: FreeResultFn = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_bench")
+        }
+        let ptr = fn(contextId, Int32(pp), Int32(tg), Int32(pl), Int32(nr))
+        guard let ptr else { return "[]" }
+        defer { free(ptr) }
+        return String(cString: ptr)
+    }
+
+    // MARK: - Session management
+
+    static func loadSession(contextId: Int64, filepath: String) throws -> [String: Any] {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_cap_load_session_file", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_cap_load_session_file")
+        }
+        let ptr = filepath.withCString { fn(contextId, $0) }
+        guard let ptr else { throw Failure.operationFailed("loadSession returned nil for \(filepath)") }
+        defer { free(ptr) }
+        return try decodeJsonDictionary(from: ptr, failure: .operationFailed("loadSession invalid JSON"))
+    }
+
+    static func saveSession(contextId: Int64, filepath: String, size: Int) throws -> Int {
+        guard let fn: SessionSaveFn = trySymOpt("llama_cap_save_session_file", SessionSaveFn.self) else {
+            throw Failure.missingSymbol("llama_cap_save_session_file")
+        }
+        let saved = filepath.withCString { fn(contextId, $0, Int32(size)) }
+        return Int(saved)
+    }
+
+    // MARK: - LoRA
+
+    /// loraAdaptersJson: JSON array [{path:string, scale:float}, ...]
+    static func applyLoraAdapters(contextId: Int64, loraAdaptersJson: String) throws -> Int {
+        guard let fn: LoraApplyFn = trySymOpt("llama_apply_lora_adapters", LoraApplyFn.self) else {
+            throw Failure.missingSymbol("llama_apply_lora_adapters")
+        }
+        let result = loraAdaptersJson.withCString { fn(contextId, $0) }
+        if result < 0 {
+            throw Failure.operationFailed("applyLoraAdapters returned \(result)")
+        }
+        return Int(result)
+    }
+
+    static func removeLoraAdapters(contextId: Int64) throws {
+        guard let fn: VoidFn = trySymOpt("llama_remove_lora_adapters", VoidFn.self) else {
+            throw Failure.missingSymbol("llama_remove_lora_adapters")
+        }
+        fn(contextId)
+    }
+
+    static func getLoadedLoraAdapters(contextId: Int64) throws -> [[String: Any]] {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_get_loaded_lora_adapters", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_get_loaded_lora_adapters")
+        }
+        // fn takes (contextId, empty_cstr) — use "" as placeholder
+        let ptr = "".withCString { fn(contextId, $0) }
+        guard let ptr else { return [] }
+        defer { free(ptr) }
+        let json = String(cString: ptr)
+        guard let data = json.data(using: .utf8),
+              let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
+            return []
+        }
+        return arr
+    }
+
+    // MARK: - Multimodal
+
+    static func initMultimodal(contextId: Int64, mmProjPath: String, useGpu: Bool) throws -> Bool {
+        guard let fn: MultimodalInitFn = trySymOpt("llama_init_multimodal", MultimodalInitFn.self) else {
+            throw Failure.missingSymbol("llama_init_multimodal")
+        }
+        let result = mmProjPath.withCString { fn(contextId, $0, useGpu ? 1 : 0) }
+        return result != 0
+    }
+
+    static func isMultimodalEnabled(contextId: Int64) -> Bool {
+        guard let fn: BoolFn = trySymOpt("llama_is_multimodal_enabled", BoolFn.self) else { return false }
+        return fn(contextId) != 0
+    }
+
+    static func getMultimodalSupport(contextId: Int64) throws -> [String: Any] {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_get_multimodal_support", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_get_multimodal_support")
+        }
+        let ptr = "".withCString { fn(contextId, $0) }
+        guard let ptr else { return ["vision": false, "audio": false] }
+        defer { free(ptr) }
+        return (try? decodeJsonDictionary(from: ptr, failure: .operationFailed("bad JSON"))) ?? ["vision": false, "audio": false]
+    }
+
+    static func releaseMultimodal(contextId: Int64) {
+        guard let fn: VoidFn = trySymOpt("llama_release_multimodal", VoidFn.self) else { return }
+        fn(contextId)
+    }
+
+    // MARK: - TTS / Vocoder
+
+    static func initVocoder(contextId: Int64, path: String, nBatch: Int) throws -> Bool {
+        guard let fn: VocoderInitFn = trySymOpt("llama_init_vocoder", VocoderInitFn.self) else {
+            throw Failure.missingSymbol("llama_init_vocoder")
+        }
+        let result = path.withCString { fn(contextId, $0, Int32(nBatch)) }
+        return result != 0
+    }
+
+    static func isVocoderEnabled(contextId: Int64) -> Bool {
+        guard let fn: BoolFn = trySymOpt("llama_is_vocoder_enabled", BoolFn.self) else { return false }
+        return fn(contextId) != 0
+    }
+
+    static func getFormattedAudioCompletion(contextId: Int64, speakerJson: String, text: String) throws -> [String: Any] {
+        guard let fn: JsonOpFn    = trySymOpt("llama_get_formatted_audio_completion", JsonOpFn.self),
+              let free: FreeResultFn = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_get_formatted_audio_completion")
+        }
+        let ptr = speakerJson.withCString { sp in text.withCString { tx in fn(contextId, sp, tx) } }
+        guard let ptr else { throw Failure.operationFailed("getFormattedAudioCompletion returned nil") }
+        defer { free(ptr) }
+        return try decodeJsonDictionary(from: ptr, failure: .operationFailed("audio completion invalid JSON"))
+    }
+
+    static func getAudioCompletionGuideTokens(contextId: Int64, text: String) throws -> [Int] {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_get_audio_completion_guide_tokens", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_get_audio_completion_guide_tokens")
+        }
+        let ptr = text.withCString { fn(contextId, $0) }
+        guard let ptr else { return [] }
+        defer { free(ptr) }
+        let json = String(cString: ptr)
+        guard let data = json.data(using: .utf8),
+              let arr  = try? JSONSerialization.jsonObject(with: data) as? [Int] else { return [] }
+        return arr
+    }
+
+    static func decodeAudioTokens(contextId: Int64, tokensJson: String) throws -> [Float] {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_decode_audio_tokens", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            throw Failure.missingSymbol("llama_decode_audio_tokens")
+        }
+        let ptr = tokensJson.withCString { fn(contextId, $0) }
+        guard let ptr else { return [] }
+        defer { free(ptr) }
+        let json = String(cString: ptr)
+        guard let data = json.data(using: .utf8),
+              let arr  = try? JSONSerialization.jsonObject(with: data) as? [Double] else { return [] }
+        return arr.map { Float($0) }
+    }
+
+    static func releaseVocoder(contextId: Int64) {
+        guard let fn: VoidFn = trySymOpt("llama_release_vocoder", VoidFn.self) else { return }
+        fn(contextId)
+    }
+
+    // MARK: - GPU info
+
+    /// Returns {"gpu": bool, "reasonNoGPU": string} from native context model JSON
+    static func queryGpuInfo(contextId: Int64) -> (gpu: Bool, reason: String) {
+        guard let fn: SingleArgJsonFn = trySymOpt("llama_get_context_gpu_info", SingleArgJsonFn.self),
+              let free: FreeResultFn  = trySymOpt("llama_free_completion_result", FreeResultFn.self) else {
+            return (false, "llama_get_context_gpu_info not available")
+        }
+        let ptr = "".withCString { fn(contextId, $0) }
+        guard let ptr else { return (false, "no GPU info returned") }
+        defer { free(ptr) }
+        let json = String(cString: ptr)
+        guard let data = json.data(using: .utf8),
+              let d = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return (false, "GPU info JSON parse error")
+        }
+        let gpu = (d["gpu"] as? Bool) ?? false
+        let reason = (d["reasonNoGPU"] as? String) ?? (gpu ? "" : "Metal/GPU not available")
+        return (gpu, reason)
+    }
+
+    // MARK: - Helpers
+
+    static func decodeJsonDictionary(
+        from resultPointer: UnsafeMutablePointer<CChar>,
+        failure: Failure
+    ) throws -> [String: Any] {
+        let jsonString = String(cString: resultPointer)
+        guard let data = jsonString.data(using: .utf8) else { throw failure }
+        let object = try JSONSerialization.jsonObject(with: data, options: [])
+        guard let dictionary = object as? [String: Any] else { throw failure }
+        return dictionary
+    }
+
+    static func normalizeModelPath(_ modelPath: String) -> String {
+        if modelPath.hasPrefix("file://") {
+            return String(modelPath.dropFirst("file://".count))
+        }
+        return modelPath
+    }
+}

package/ios/Sources/LlamaCppCapacitor/ModelAdmissionController.swift

@@ -0,0 +1,177 @@
+import Foundation
+
+/// Memory admission control for native model loading on iOS.
+///
+/// This mirrors the Web/WASM `DefaultModelScheduler` + `wasmMemoryPolicy` so that all
+/// three platforms share the same isomorphic admission semantics:
+/// - A hard cap on concurrent loaded models (parity with `WASM_MAX_CONCURRENT_MODELS = 5`).
+/// - Per-model footprint estimation based on GGUF file size.
+/// - A device-memory guard that keeps a reserve free after each load.
+///
+/// Unlike the Web path (bounded by a single 2 GB WASM linear-memory pool), the iOS
+/// ceiling is the per-process memory budget reported by `os_proc_available_memory()`
+/// (the headroom before jetsam terminates the app). The controller rejects a load when
+/// either the slot limit is reached or the projected available memory after loading
+/// would fall below the reserve threshold.
+final class ModelAdmissionController {
+
+    /// Max concurrent native contexts. Parity with `WASM_MAX_CONCURRENT_MODELS`.
+    static let maxConcurrentModels = 5
+
+    /// Keep this much process memory free after a model load (headroom for app + OS).
+    static let defaultReserveBytes: UInt64 = 512 * 1024 * 1024 // 512 MB
+
+    /// Fallback footprint when the GGUF size cannot be determined.
+    private static let unknownModelFootprintBytes: UInt64 = 512 * 1024 * 1024
+
+    enum DeniedBy {
+        case limit
+        case memory
+    }
+
+    /// Result of an admission decision.
+    struct Decision {
+        let allow: Bool
+        let deniedBy: DeniedBy?   // nil when allowed
+        let reason: String?       // nil when allowed
+        let estimatedBytes: UInt64
+
+        static func allowed(_ estimatedBytes: UInt64) -> Decision {
+            Decision(allow: true, deniedBy: nil, reason: nil, estimatedBytes: estimatedBytes)
+        }
+
+        static func denied(_ deniedBy: DeniedBy, _ reason: String, _ estimatedBytes: UInt64) -> Decision {
+            Decision(allow: false, deniedBy: deniedBy, reason: reason, estimatedBytes: estimatedBytes)
+        }
+    }
+
+    /// Lightweight snapshot of process/device memory (mirrors the Web MemorySnapshot).
+    struct MemorySnapshot {
+        let totalBytes: UInt64   // device physical memory
+        let freeBytes: UInt64    // per-process available memory (headroom before jetsam)
+    }
+
+    private let maxModels: Int
+    private let reserveBytes: UInt64
+
+    init(maxModels: Int = ModelAdmissionController.maxConcurrentModels,
+         reserveBytes: UInt64 = ModelAdmissionController.defaultReserveBytes) {
+        self.maxModels = maxModels
+        self.reserveBytes = reserveBytes
+    }
+
+    var maxModelCount: Int { maxModels }
+
+    /// Estimate the resident footprint of a model once loaded.
+    ///
+    /// Native loading (mmap or full read) does not duplicate the GGUF the way a naive
+    /// heap copy would, but the KV cache and compute buffers add headroom on top of the
+    /// mapped weights. The multipliers below match the WASM policy's intent, scaled for
+    /// native memory behaviour.
+    ///
+    /// - Parameters:
+    ///   - fileBytes: GGUF file size in bytes (0 when unknown)
+    ///   - embedding: whether the context is an embedding-only model (lighter headroom)
+    static func estimateModelFootprint(fileBytes: UInt64, embedding: Bool) -> UInt64 {
+        guard fileBytes > 0 else {
+            return unknownModelFootprintBytes
+        }
+        let isLarge = fileBytes > 200 * 1024 * 1024
+        let weightMultiplier: Double = embedding ? 1.15 : (isLarge ? 1.30 : 1.20)
+        let proportionalHeadroom = UInt64((Double(fileBytes) * 0.12).rounded(.up))
+        let minHeadroom: UInt64 = embedding ? 48 * 1024 * 1024 : 96 * 1024 * 1024
+        let headroom = max(minHeadroom, proportionalHeadroom)
+        let weights = UInt64((Double(fileBytes) * weightMultiplier).rounded(.up))
+        return weights + headroom
+    }
+
+    /// Read the GGUF file size, returning 0 when the path is missing or unreadable.
+    static func fileSizeBytes(_ modelPath: String) -> UInt64 {
+        guard !modelPath.isEmpty else { return 0 }
+        // Accept both plain paths and file:// URLs.
+        let path: String
+        if let url = URL(string: modelPath), url.isFileURL {
+            path = url.path
+        } else {
+            path = modelPath
+        }
+        do {
+            let attrs = try FileManager.default.attributesOfItem(atPath: path)
+            if let size = attrs[.size] as? NSNumber {
+                return size.uint64Value
+            }
+        } catch {
+            return 0
+        }
+        return 0
+    }
+
+    /// Capture a process/device memory snapshot.
+    ///
+    /// `os_proc_available_memory()` (iOS 13+) reports the memory the app can still use
+    /// before jetsam terminates it — a more meaningful guard than device-wide free RAM.
+    func memorySnapshot() -> MemorySnapshot {
+        let total = ProcessInfo.processInfo.physicalMemory
+        var free: UInt64 = 0
+        if #available(iOS 13.0, *) {
+            let available = os_proc_available_memory()
+            if available > 0 {
+                free = UInt64(available)
+            }
+        }
+        return MemorySnapshot(totalBytes: total, freeBytes: free)
+    }
+
+    /// Decide whether a new model may be admitted.
+    ///
+    /// - Parameters:
+    ///   - currentlyLoaded: number of contexts already loaded
+    ///   - modelPath: path to the GGUF being loaded (used to size the footprint)
+    ///   - embedding: whether this is an embedding-only context
+    func canAdmit(currentlyLoaded: Int, modelPath: String, embedding: Bool) -> Decision {
+        let fileBytes = Self.fileSizeBytes(modelPath)
+        let estimated = Self.estimateModelFootprint(fileBytes: fileBytes, embedding: embedding)
+
+        // 1. Slot limit (parity with Web).
+        if currentlyLoaded >= maxModels {
+            return .denied(
+                .limit,
+                "Model slot limit reached (\(maxModels) concurrent contexts)",
+                estimated
+            )
+        }
+
+        // 2. Process-memory guard: keep `reserveBytes` free after the load.
+        let mem = memorySnapshot()
+        if mem.freeBytes > 0 {
+            // Guard against unsigned underflow.
+            if mem.freeBytes <= estimated || (mem.freeBytes - estimated) < reserveBytes {
+                return .denied(
+                    .memory,
+                    "Insufficient memory: need ~\(toMb(estimated)) MB, "
+                        + "\(toMb(mem.freeBytes)) MB available, "
+                        + "\(toMb(reserveBytes)) MB reserve required",
+                    estimated
+                )
+            }
+        }
+
+        return .allowed(estimated)
+    }
+
+    /// Snapshot of admission state for diagnostics / health reporting.
+    func status(currentlyLoaded: Int) -> [String: Any] {
+        let mem = memorySnapshot()
+        return [
+            "loadedModels": currentlyLoaded,
+            "maxModels": maxModels,
+            "deviceTotalBytes": mem.totalBytes,
+            "processFreeBytes": mem.freeBytes,
+            "reserveBytes": reserveBytes
+        ]
+    }
+
+    private func toMb(_ bytes: UInt64) -> UInt64 {
+        bytes / (1024 * 1024)
+    }
+}

package/ios/embed-metal-shaders.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Merge ggml headers into ggml-metal.metal and emit assembly that embeds the source
+# for LM_GGML_METAL_EMBED_LIBRARY (runtime Metal shader compilation).
+set -euo pipefail
+
+COMMON="$1"
+SOURCE="$2"
+IMPL="$3"
+OUT_ASM="$4"
+OUT_METAL="$5"
+TMP_METAL="${OUT_METAL}.tmp"
+
+sed -e "/__embed_ggml-common.h__/r ${COMMON}" -e "/__embed_ggml-common.h__/d" < "${SOURCE}" > "${TMP_METAL}"
+sed -e "/#include \"ggml-metal-impl.h\"/r ${IMPL}" -e "/#include \"ggml-metal-impl.h\"/d" < "${TMP_METAL}" > "${OUT_METAL}"
+rm -f "${TMP_METAL}"
+
+cat > "${OUT_ASM}" <<EOF
+.section __DATA,__ggml_metallib
+.globl _lm_ggml_metallib_start
+_lm_ggml_metallib_start:
+.incbin "${OUT_METAL}"
+.globl _lm_ggml_metallib_end
+_lm_ggml_metallib_end:
+EOF

package/ios/metal-embed.cmake

@@ -0,0 +1,29 @@
+# Embed ggml-metal.metal (with merged headers) for LM_GGML_METAL_EMBED_LIBRARY.
+# Runtime compiles shaders from the embedded source — no default.metallib bundle needed.
+
+set(METALLIB_COMMON "${SOURCE_DIR}/ggml-common.h")
+set(METALLIB_SOURCE "${SOURCE_DIR}/ggml-metal.metal")
+set(METALLIB_IMPL "${SOURCE_DIR}/ggml-metal-impl.h")
+set(METALLIB_EMBED_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/embed-metal-shaders.sh")
+
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/autogenerated")
+
+set(METALLIB_EMBED_ASM "${CMAKE_CURRENT_BINARY_DIR}/autogenerated/ggml-metal-embed.s")
+set(METALLIB_SOURCE_EMBED "${CMAKE_CURRENT_BINARY_DIR}/autogenerated/ggml-metal-embed.metal")
+
+add_custom_command(
+    OUTPUT "${METALLIB_EMBED_ASM}"
+    COMMAND "${METALLIB_EMBED_SCRIPT}"
+        "${METALLIB_COMMON}"
+        "${METALLIB_SOURCE}"
+        "${METALLIB_IMPL}"
+        "${METALLIB_EMBED_ASM}"
+        "${METALLIB_SOURCE_EMBED}"
+    DEPENDS
+        "${METALLIB_EMBED_SCRIPT}"
+        "${METALLIB_COMMON}"
+        "${METALLIB_SOURCE}"
+        "${METALLIB_IMPL}"
+    COMMENT "Generate assembly for embedded Metal shader source"
+    VERBATIM
+)