react-native-nitro-mlx 0.1.0 → 0.2.0

package/ios/Sources/HybridLLM.swift

@@ -0,0 +1,245 @@
+import Foundation
+import NitroModules
+internal import MLX
+internal import MLXLLM
+internal import MLXLMCommon
+
+class HybridLLM: HybridLLMSpec {
+    private var session: ChatSession?
+    private var currentTask: Task<String, Error>?
+    private var container: Any?
+    private var lastStats: GenerationStats = GenerationStats(
+        tokenCount: 0,
+        tokensPerSecond: 0,
+        timeToFirstToken: 0,
+        totalTime: 0
+    )
+    private var modelFactory: ModelFactory = LLMModelFactory.shared
+    private var manageHistory: Bool = false
+    private var messageHistory: [LLMMessage] = []
+
+    var isLoaded: Bool { session != nil }
+    var isGenerating: Bool { currentTask != nil }
+    var modelId: String = ""
+    var debug: Bool = false
+    var systemPrompt: String = "You are a helpful assistant."
+    var additionalContext: LLMMessage = LLMMessage()
+
+    private func log(_ message: String) {
+        if debug {
+            print("[MLXReactNative.HybridLLM] \(message)")
+        }
+    }
+
+    private func getMemoryUsage() -> String {
+        var taskInfo = mach_task_basic_info()
+        var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size)/4
+        let result: kern_return_t = withUnsafeMutablePointer(to: &taskInfo) {
+            $0.withMemoryRebound(to: integer_t.self, capacity: 1) {
+                task_info(mach_task_self_,
+                         task_flavor_t(MACH_TASK_BASIC_INFO),
+                         $0,
+                         &count)
+            }
+        }
+
+        if result == KERN_SUCCESS {
+            let usedMB = Float(taskInfo.resident_size) / 1024.0 / 1024.0
+            return String(format: "%.1f MB", usedMB)
+        } else {
+            return "unknown"
+        }
+    }
+
+    private func getGPUMemoryUsage() -> String {
+        let snapshot = GPU.snapshot()
+        let allocatedMB = Float(snapshot.activeMemory) / 1024.0 / 1024.0
+        let cacheMB = Float(snapshot.cacheMemory) / 1024.0 / 1024.0
+        let peakMB = Float(snapshot.peakMemory) / 1024.0 / 1024.0
+        return String(format: "Allocated: %.1f MB, Cache: %.1f MB, Peak: %.1f MB",
+                     allocatedMB, cacheMB, peakMB)
+    }
+
+    func load(modelId: String, options: LLMLoadOptions?) throws -> Promise<Void> {
+        return Promise.async { [self] in
+            MLX.GPU.set(cacheLimit: 2000000)
+
+            self.currentTask?.cancel()
+            self.currentTask = nil
+            self.session = nil
+            self.container = nil
+            MLX.GPU.clearCache()
+
+            let memoryAfterCleanup = self.getMemoryUsage()
+            let gpuAfterCleanup = self.getGPUMemoryUsage()
+            log("After cleanup - Host: \(memoryAfterCleanup), GPU: \(gpuAfterCleanup)")
+
+            let modelDir = await ModelDownloader.shared.getModelDirectory(modelId: modelId)
+            log("Loading from directory: \(modelDir.path)")
+
+            let config = ModelConfiguration(directory: modelDir)
+            let loadedContainer = try await modelFactory.loadContainer(
+                configuration: config
+            ) { progress in
+                options?.onProgress?(progress.fractionCompleted)
+            }
+
+            let memoryAfterContainer = self.getMemoryUsage()
+            let gpuAfterContainer = self.getGPUMemoryUsage()
+            log("Model loaded - Host: \(memoryAfterContainer), GPU: \(gpuAfterContainer)")
+
+            // Convert [LLMMessage]? to [String: Any]?
+            let additionalContextDict: [String: Any]? = if let messages = options?.additionalContext {
+                ["messages": messages.map { ["role": $0.role, "content": $0.content] }]
+            } else {
+                nil
+            }
+
+            self.container = loadedContainer
+            self.session = ChatSession(loadedContainer, instructions: self.systemPrompt, additionalContext: additionalContextDict)
+            self.modelId = modelId
+
+            self.manageHistory = options?.manageHistory ?? false
+            self.messageHistory = options?.additionalContext ?? []
+
+            if self.manageHistory {
+                log("History management enabled with \(self.messageHistory.count) initial messages")
+            }
+        }
+    }
+
+    func generate(prompt: String) throws -> Promise<String> {
+        guard let session = session else {
+            throw LLMError.notLoaded
+        }
+
+        return Promise.async { [self] in
+            if self.manageHistory {
+                self.messageHistory.append(LLMMessage(role: "user", content: prompt))
+            }
+
+            let task = Task<String, Error> {
+                log("Generating response for: \(prompt.prefix(50))...")
+                let result = try await session.respond(to: prompt)
+                log("Generation complete")
+                return result
+            }
+
+            self.currentTask = task
+
+            do {
+                let result = try await task.value
+                self.currentTask = nil
+
+                if self.manageHistory {
+                    self.messageHistory.append(LLMMessage(role: "assistant", content: result))
+                }
+
+                return result
+            } catch {
+                self.currentTask = nil
+                throw error
+            }
+        }
+    }
+
+    func stream(prompt: String, onToken: @escaping (String) -> Void) throws -> Promise<String> {
+        guard let session = session else {
+            throw LLMError.notLoaded
+        }
+
+        return Promise.async { [self] in
+            if self.manageHistory {
+                self.messageHistory.append(LLMMessage(role: "user", content: prompt))
+            }
+
+            let task = Task<String, Error> {
+                var result = ""
+                var tokenCount = 0
+                let startTime = Date()
+                var firstTokenTime: Date?
+
+                log("Streaming response for: \(prompt.prefix(50))...")
+                for try await chunk in session.streamResponse(to: prompt) {
+                    if Task.isCancelled { break }
+
+                    if firstTokenTime == nil {
+                        firstTokenTime = Date()
+                    }
+                    tokenCount += 1
+                    result += chunk
+                    onToken(chunk)
+                }
+
+                let endTime = Date()
+                let totalTime = endTime.timeIntervalSince(startTime) * 1000
+                let timeToFirstToken = (firstTokenTime ?? endTime).timeIntervalSince(startTime) * 1000
+                let tokensPerSecond = totalTime > 0 ? Double(tokenCount) / (totalTime / 1000) : 0
+
+                self.lastStats = GenerationStats(
+                    tokenCount: Double(tokenCount),
+                    tokensPerSecond: tokensPerSecond,
+                    timeToFirstToken: timeToFirstToken,
+                    totalTime: totalTime
+                )
+
+                log("Stream complete - \(tokenCount) tokens, \(String(format: "%.1f", tokensPerSecond)) tokens/s")
+                return result
+            }
+
+            self.currentTask = task
+
+            do {
+                let result = try await task.value
+                self.currentTask = nil
+
+                if self.manageHistory {
+                    self.messageHistory.append(LLMMessage(role: "assistant", content: result))
+                }
+
+                return result
+            } catch {
+                self.currentTask = nil
+                throw error
+            }
+        }
+    }
+
+    func stop() throws {
+        currentTask?.cancel()
+        currentTask = nil
+    }
+
+    func unload() throws {
+        let memoryBefore = getMemoryUsage()
+        let gpuBefore = getGPUMemoryUsage()
+        log("Before unload - Host: \(memoryBefore), GPU: \(gpuBefore)")
+
+        currentTask?.cancel()
+        currentTask = nil
+        session = nil
+        container = nil
+        messageHistory = []
+        manageHistory = false
+        modelId = ""
+
+        MLX.GPU.clearCache()
+
+        let memoryAfter = getMemoryUsage()
+        let gpuAfter = getGPUMemoryUsage()
+        log("After unload - Host: \(memoryAfter), GPU: \(gpuAfter)")
+    }
+
+    func getLastGenerationStats() throws -> GenerationStats {
+        return lastStats
+    }
+
+    func getHistory() throws -> [LLMMessage] {
+        return messageHistory
+    }
+
+    func clearHistory() throws {
+        messageHistory = []
+        log("Message history cleared")
+    }
+}

package/ios/Sources/HybridModelManager.swift

@@ -0,0 +1,77 @@
+import Foundation
+import NitroModules
+internal import MLXLMCommon
+internal import MLXLLM
+
+class HybridModelManager: HybridModelManagerSpec {
+    private let fileManager = FileManager.default
+
+    var debug: Bool {
+        get { ModelDownloader.debug }
+        set { ModelDownloader.debug = newValue }
+    }
+
+    private func log(_ message: String) {
+        if debug {
+            print("[MLXReactNative.HybridModelManager] \(message)")
+        }
+    }
+
+    func download(
+        modelId: String,
+        progressCallback: @escaping (Double) -> Void
+    ) throws -> Promise<String> {
+        return Promise.async { [self] in
+            log("Starting download for: \(modelId)")
+
+            let modelDir = try await ModelDownloader.shared.download(
+                modelId: modelId,
+                progressCallback: progressCallback
+            )
+
+            log("Download complete: \(modelDir.path)")
+            return modelDir.path
+        }
+    }
+
+    func isDownloaded(modelId: String) throws -> Promise<Bool> {
+        return Promise.async {
+            return await ModelDownloader.shared.isDownloaded(modelId: modelId)
+        }
+    }
+
+    func getDownloadedModels() throws -> Promise<[String]> {
+        return Promise.async { [self] in
+            let docsDir = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first!
+            let modelsDir = docsDir.appendingPathComponent("huggingface/models")
+
+            guard fileManager.fileExists(atPath: modelsDir.path) else {
+                return []
+            }
+
+            let contents = try fileManager.contentsOfDirectory(
+                at: modelsDir,
+                includingPropertiesForKeys: [.isDirectoryKey]
+            )
+
+            return contents
+                .filter { url in
+                    var isDir: ObjCBool = false
+                    return fileManager.fileExists(atPath: url.path, isDirectory: &isDir) && isDir.boolValue
+                }
+                .map { $0.lastPathComponent.replacingOccurrences(of: "_", with: "/") }
+        }
+    }
+
+    func deleteModel(modelId: String) throws -> Promise<Void> {
+        return Promise.async {
+            try await ModelDownloader.shared.deleteModel(modelId: modelId)
+        }
+    }
+
+    func getModelPath(modelId: String) throws -> Promise<String> {
+        return Promise.async {
+            return await ModelDownloader.shared.getModelDirectory(modelId: modelId).path
+        }
+    }
+}

package/ios/Sources/LLMError.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+public enum LLMError: Error {
+    case notLoaded
+    case generationFailed(String)
+}

package/ios/Sources/ModelDownloader.swift

@@ -0,0 +1,103 @@
+import Foundation
+
+actor ModelDownloader: NSObject {
+    static let shared = ModelDownloader()
+    static var debug: Bool = false
+
+    private let fileManager = FileManager.default
+
+    private func log(_ message: String) {
+        if Self.debug {
+            print("[Downloader] \(message)")
+        }
+    }
+
+    func download(
+        modelId: String,
+        progressCallback: @escaping (Double) -> Void
+    ) async throws -> URL {
+        let requiredFiles = [
+            "config.json",
+            "tokenizer.json",
+            "tokenizer_config.json",
+            "model.safetensors"
+        ]
+
+        let modelDir = getModelDirectory(modelId: modelId)
+        try fileManager.createDirectory(at: modelDir, withIntermediateDirectories: true)
+
+        log("Model directory: \(modelDir.path)")
+        log("Files to download: \(requiredFiles)")
+
+        var downloaded = 0
+
+        for file in requiredFiles {
+            let destURL = modelDir.appendingPathComponent(file)
+
+            if fileManager.fileExists(atPath: destURL.path) {
+                log("File exists, skipping: \(file)")
+                downloaded += 1
+                progressCallback(Double(downloaded) / Double(requiredFiles.count))
+                continue
+            }
+
+            let urlString = "https://huggingface.co/\(modelId)/resolve/main/\(file)"
+            guard let url = URL(string: urlString) else {
+                log("Invalid URL: \(urlString)")
+                continue
+            }
+
+            log("Downloading: \(file)")
+
+            let (tempURL, response) = try await URLSession.shared.download(from: url)
+
+            guard let httpResponse = response as? HTTPURLResponse else {
+                log("Invalid response for: \(file)")
+                continue
+            }
+
+            log("Response status: \(httpResponse.statusCode) for \(file)")
+
+            if httpResponse.statusCode == 200 {
+                if fileManager.fileExists(atPath: destURL.path) {
+                    try fileManager.removeItem(at: destURL)
+                }
+                try fileManager.moveItem(at: tempURL, to: destURL)
+                log("Saved: \(file)")
+            } else {
+                log("Failed to download: \(file) - Status: \(httpResponse.statusCode)")
+            }
+
+            downloaded += 1
+            progressCallback(Double(downloaded) / Double(requiredFiles.count))
+        }
+
+        return modelDir
+    }
+
+    func isDownloaded(modelId: String) -> Bool {
+        let modelDir = getModelDirectory(modelId: modelId)
+        let requiredFiles = ["config.json", "model.safetensors", "tokenizer.json"]
+
+        let allExist = requiredFiles.allSatisfy { file in
+            fileManager.fileExists(atPath: modelDir.appendingPathComponent(file).path)
+        }
+
+        log("isDownloaded(\(modelId)): \(allExist)")
+        return allExist
+    }
+
+    func getModelDirectory(modelId: String) -> URL {
+        let docsDir = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first!
+        return docsDir
+            .appendingPathComponent("huggingface/models")
+            .appendingPathComponent(modelId.replacingOccurrences(of: "/", with: "_"))
+    }
+
+    func deleteModel(modelId: String) throws {
+        let modelDir = getModelDirectory(modelId: modelId)
+        if fileManager.fileExists(atPath: modelDir.path) {
+            try fileManager.removeItem(at: modelDir)
+        }
+    }
+}

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["LLM","ModelManager","MLXModel"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,GAAG,QAAQ,UAAO;AAC3B,SAASC,YAAY,QAAQ,mBAAgB;AAC7C,SAASC,QAAQ,QAAQ,aAAU","ignoreList":[]}
+{"version":3,"names":["LLM","ModelManager","MLXModel"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,GAAG,QAAsB,UAAO;AACzC,SAASC,YAAY,QAAQ,mBAAgB;AAC7C,SAASC,QAAQ,QAAQ,aAAU","ignoreList":[]}

package/lib/module/llm.js

@@ -35,10 +35,10 @@ export const LLM = {
   /**
    * Load a model into memory. Downloads the model from HuggingFace if not already cached.
    * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
-   * @param onProgress - Callback invoked with loading progress (0-1)
+   * @param options - Callback invoked with loading progress (0-1)
    */
-  load(modelId, onProgress) {
-    return getInstance().load(modelId, onProgress);
+  load(modelId, options) {
+    return getInstance().load(modelId, options);
   },
   /**
    * Generate a complete response for a prompt. Blocks until generation is complete.
@@ -64,6 +64,13 @@ export const LLM = {
   stop() {
     getInstance().stop();
   },
+  /**
+   * Unload the current model and release memory.
+   * Call this when you're done with the model to free up memory.
+   */
+  unload() {
+    getInstance().unload();
+  },
   /**
    * Get statistics from the last generation.
    * @returns Statistics including token count, tokens/sec, TTFT, and total time
@@ -71,6 +78,19 @@ export const LLM = {
   getLastGenerationStats() {
     return getInstance().getLastGenerationStats();
   },
+  /**
+   * Get the message history if management is enabled.
+   * @returns Array of messages in the history
+   */
+  getHistory() {
+    return getInstance().getHistory();
+  },
+  /**
+   * Clear the message history.
+   */
+  clearHistory() {
+    getInstance().clearHistory();
+  },
   /** Whether a model is currently loaded and ready for generation */
   get isLoaded() {
     return getInstance().isLoaded;

package/lib/module/llm.js.map

@@ -1 +1 @@
-{"version":3,"names":["NitroModules","instance","getInstance","createHybridObject","LLM","load","modelId","onProgress","generate","prompt","stream","onToken","stop","getLastGenerationStats","isLoaded","isGenerating","debug","value","systemPrompt"],"sourceRoot":"../../src","sources":["llm.ts"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,IAAIC,QAAwB,GAAG,IAAI;AAEnC,SAASC,WAAWA,CAAA,EAAY;EAC9B,IAAI,CAACD,QAAQ,EAAE;IACbA,QAAQ,GAAGD,YAAY,CAACG,kBAAkB,CAAU,KAAK,CAAC;EAC5D;EACA,OAAOF,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,GAAG,GAAG;EACjB;AACF;AACA;AACA;AACA;EACEC,IAAIA,CAACC,OAAe,EAAEC,UAAsC,EAAiB;IAC3E,OAAOL,WAAW,CAAC,CAAC,CAACG,IAAI,CAACC,OAAO,EAAEC,UAAU,CAAC;EAChD,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,QAAQA,CAACC,MAAc,EAAmB;IACxC,OAAOP,WAAW,CAAC,CAAC,CAACM,QAAQ,CAACC,MAAM,CAAC;EACvC,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,MAAMA,CAACD,MAAc,EAAEE,OAAgC,EAAmB;IACxE,OAAOT,WAAW,CAAC,CAAC,CAACQ,MAAM,CAACD,MAAM,EAAEE,OAAO,CAAC;EAC9C,CAAC;EAED;AACF;AACA;EACEC,IAAIA,CAAA,EAAS;IACXV,WAAW,CAAC,CAAC,CAACU,IAAI,CAAC,CAAC;EACtB,CAAC;EAED;AACF;AACA;AACA;EACEC,sBAAsBA,CAAA,EAAoB;IACxC,OAAOX,WAAW,CAAC,CAAC,CAACW,sBAAsB,CAAC,CAAC;EAC/C,CAAC;EAED;EACA,IAAIC,QAAQA,CAAA,EAAY;IACtB,OAAOZ,WAAW,CAAC,CAAC,CAACY,QAAQ;EAC/B,CAAC;EAED;EACA,IAAIC,YAAYA,CAAA,EAAY;IAC1B,OAAOb,WAAW,CAAC,CAAC,CAACa,YAAY;EACnC,CAAC;EAED;EACA,IAAIT,OAAOA,CAAA,EAAW;IACpB,OAAOJ,WAAW,CAAC,CAAC,CAACI,OAAO;EAC9B,CAAC;EAED;EACA,IAAIU,KAAKA,CAAA,EAAY;IACnB,OAAOd,WAAW,CAAC,CAAC,CAACc,KAAK;EAC5B,CAAC;EAED,IAAIA,KAAKA,CAACC,KAAc,EAAE;IACxBf,WAAW,CAAC,CAAC,CAACc,KAAK,GAAGC,KAAK;EAC7B,CAAC;EAED;AACF;AACA;AACA;AACA;EACE,IAAIC,YAAYA,CAAA,EAAW;IACzB,OAAOhB,WAAW,CAAC,CAAC,CAACgB,YAAY;EACnC,CAAC;EAED,IAAIA,YAAYA,CAACD,KAAa,EAAE;IAC9Bf,WAAW,CAAC,CAAC,CAACgB,YAAY,GAAGD,KAAK;EACpC;AACF,CAAC","ignoreList":[]}
+{"version":3,"names":["NitroModules","instance","getInstance","createHybridObject","LLM","load","modelId","options","generate","prompt","stream","onToken","stop","unload","getLastGenerationStats","getHistory","clearHistory","isLoaded","isGenerating","debug","value","systemPrompt"],"sourceRoot":"../../src","sources":["llm.ts"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,IAAIC,QAAwB,GAAG,IAAI;AAOnC,SAASC,WAAWA,CAAA,EAAY;EAC9B,IAAI,CAACD,QAAQ,EAAE;IACbA,QAAQ,GAAGD,YAAY,CAACG,kBAAkB,CAAU,KAAK,CAAC;EAC5D;EACA,OAAOF,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,GAAG,GAAG;EACjB;AACF;AACA;AACA;AACA;EACEC,IAAIA,CAACC,OAAe,EAAEC,OAAuB,EAAiB;IAC5D,OAAOL,WAAW,CAAC,CAAC,CAACG,IAAI,CAACC,OAAO,EAAEC,OAAO,CAAC;EAC7C,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,QAAQA,CAACC,MAAc,EAAmB;IACxC,OAAOP,WAAW,CAAC,CAAC,CAACM,QAAQ,CAACC,MAAM,CAAC;EACvC,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,MAAMA,CAACD,MAAc,EAAEE,OAAgC,EAAmB;IACxE,OAAOT,WAAW,CAAC,CAAC,CAACQ,MAAM,CAACD,MAAM,EAAEE,OAAO,CAAC;EAC9C,CAAC;EAED;AACF;AACA;EACEC,IAAIA,CAAA,EAAS;IACXV,WAAW,CAAC,CAAC,CAACU,IAAI,CAAC,CAAC;EACtB,CAAC;EAED;AACF;AACA;AACA;EACEC,MAAMA,CAAA,EAAS;IACbX,WAAW,CAAC,CAAC,CAACW,MAAM,CAAC,CAAC;EACxB,CAAC;EAED;AACF;AACA;AACA;EACEC,sBAAsBA,CAAA,EAAoB;IACxC,OAAOZ,WAAW,CAAC,CAAC,CAACY,sBAAsB,CAAC,CAAC;EAC/C,CAAC;EAED;AACF;AACA;AACA;EACEC,UAAUA,CAAA,EAAc;IACtB,OAAOb,WAAW,CAAC,CAAC,CAACa,UAAU,CAAC,CAAC;EACnC,CAAC;EAED;AACF;AACA;EACEC,YAAYA,CAAA,EAAS;IACnBd,WAAW,CAAC,CAAC,CAACc,YAAY,CAAC,CAAC;EAC9B,CAAC;EAED;EACA,IAAIC,QAAQA,CAAA,EAAY;IACtB,OAAOf,WAAW,CAAC,CAAC,CAACe,QAAQ;EAC/B,CAAC;EAED;EACA,IAAIC,YAAYA,CAAA,EAAY;IAC1B,OAAOhB,WAAW,CAAC,CAAC,CAACgB,YAAY;EACnC,CAAC;EAED;EACA,IAAIZ,OAAOA,CAAA,EAAW;IACpB,OAAOJ,WAAW,CAAC,CAAC,CAACI,OAAO;EAC9B,CAAC;EAED;EACA,IAAIa,KAAKA,CAAA,EAAY;IACnB,OAAOjB,WAAW,CAAC,CAAC,CAACiB,KAAK;EAC5B,CAAC;EAED,IAAIA,KAAKA,CAACC,KAAc,EAAE;IACxBlB,WAAW,CAAC,CAAC,CAACiB,KAAK,GAAGC,KAAK;EAC7B,CAAC;EAED;AACF;AACA;AACA;AACA;EACE,IAAIC,YAAYA,CAAA,EAAW;IACzB,OAAOnB,WAAW,CAAC,CAAC,CAACmB,YAAY;EACnC,CAAC;EAED,IAAIA,YAAYA,CAACD,KAAa,EAAE;IAC9BlB,WAAW,CAAC,CAAC,CAACmB,YAAY,GAAGD,KAAK;EACpC;AACF,CAAC","ignoreList":[]}

package/lib/typescript/src/index.d.ts

@@ -1,6 +1,6 @@
-export { LLM } from './llm';
+export { LLM, type Message } from './llm';
 export { ModelManager } from './modelManager';
 export { MLXModel } from './models';
-export type { GenerationStats, LLM as LLMSpec } from './specs/LLM.nitro';
+export type { GenerationStats, LLM as LLMSpec, LLMLoadOptions } from './specs/LLM.nitro';
 export type { ModelManager as ModelManagerSpec } from './specs/ModelManager.nitro';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,YAAY,EAAE,eAAe,EAAE,GAAG,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,YAAY,EAAE,eAAe,EAAE,GAAG,IAAI,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACxF,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,4BAA4B,CAAA"}

package/lib/typescript/src/llm.d.ts

@@ -1,4 +1,8 @@
-import type { GenerationStats } from './specs/LLM.nitro';
+import type { GenerationStats, LLMLoadOptions } from './specs/LLM.nitro';
+export type Message = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+};
 /**
  * LLM text generation using MLX on Apple Silicon.
  *
@@ -25,9 +29,9 @@ export declare const LLM: {
     /**
      * Load a model into memory. Downloads the model from HuggingFace if not already cached.
      * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
-     * @param onProgress - Callback invoked with loading progress (0-1)
+     * @param options - Callback invoked with loading progress (0-1)
      */
-    load(modelId: string, onProgress: (progress: number) => void): Promise<void>;
+    load(modelId: string, options: LLMLoadOptions): Promise<void>;
     /**
      * Generate a complete response for a prompt. Blocks until generation is complete.
      * For streaming responses, use `stream()` instead.
@@ -46,11 +50,25 @@ export declare const LLM: {
      * Stop the current generation. Safe to call even if not generating.
      */
     stop(): void;
+    /**
+     * Unload the current model and release memory.
+     * Call this when you're done with the model to free up memory.
+     */
+    unload(): void;
     /**
      * Get statistics from the last generation.
      * @returns Statistics including token count, tokens/sec, TTFT, and total time
      */
     getLastGenerationStats(): GenerationStats;
+    /**
+     * Get the message history if management is enabled.
+     * @returns Array of messages in the history
+     */
+    getHistory(): Message[];
+    /**
+     * Clear the message history.
+     */
+    clearHistory(): void;
     /** Whether a model is currently loaded and ready for generation */
     readonly isLoaded: boolean;
     /** Whether text is currently being generated */

package/lib/typescript/src/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../src/llm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,mBAAmB,CAAA;AAWxE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,GAAG;IACd;;;;OAIG;kBACW,MAAM,cAAc,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;;;;OAKG;qBACc,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzC;;;;;OAKG;mBACY,MAAM,WAAW,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE;;OAEG;YACK,IAAI;IAIZ;;;OAGG;8BACuB,eAAe;IAIzC,mEAAmE;uBACnD,OAAO;IAIvB,gDAAgD;2BAC5B,OAAO;IAI3B,oEAAoE;sBACrD,MAAM;IAIrB,sCAAsC;WACzB,OAAO;IAQpB;;;;OAIG;kBACiB,MAAM;CAO3B,CAAA"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../src/llm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAkB,MAAM,mBAAmB,CAAA;AAIxF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAA;IACrC,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,GAAG;IACd;;;;OAIG;kBACW,MAAM,WAAW,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;OAKG;qBACc,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzC;;;;;OAKG;mBACY,MAAM,WAAW,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE;;OAEG;YACK,IAAI;IAIZ;;;OAGG;cACO,IAAI;IAId;;;OAGG;8BACuB,eAAe;IAIzC;;;OAGG;kBACW,OAAO,EAAE;IAIvB;;OAEG;oBACa,IAAI;IAIpB,mEAAmE;uBACnD,OAAO;IAIvB,gDAAgD;2BAC5B,OAAO;IAI3B,oEAAoE;sBACrD,MAAM;IAIrB,sCAAsC;WACzB,OAAO;IAQpB;;;;OAIG;kBACiB,MAAM;CAO3B,CAAA"}

package/lib/typescript/src/specs/LLM.nitro.d.ts

@@ -12,6 +12,20 @@ export interface GenerationStats {
     /** Total generation time in milliseconds */
     totalTime: number;
 }
+export interface LLMMessage {
+    role: string;
+    content: string;
+}
+/** Options for loading a model.
+ */
+export interface LLMLoadOptions {
+    /** Callback invoked with loading progress (0-1) */
+    onProgress?: (progress: number) => void;
+    /** Additional context to provide to the model */
+    additionalContext?: LLMMessage[];
+    /** Whether to automatically manage message history */
+    manageHistory?: boolean;
+}
 /**
  * Low-level LLM interface for text generation using MLX.
  * @internal Use the `LLM` export from `react-native-nitro-mlx` instead.
@@ -22,9 +36,9 @@ export interface LLM extends HybridObject<{
     /**
      * Load a model into memory. Downloads from HuggingFace if not already cached.
      * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
-     * @param onProgress - Callback invoked with loading progress (0-1)
+     * @param options - Callback invoked with loading progress (0-1)
      */
-    load(modelId: string, onProgress: (progress: number) => void): Promise<void>;
+    load(modelId: string, options?: LLMLoadOptions): Promise<void>;
     /**
      * Generate a complete response for a prompt.
      * @param prompt - The input text to generate a response for
@@ -42,11 +56,24 @@ export interface LLM extends HybridObject<{
      * Stop the current generation.
      */
     stop(): void;
+    /**
+     * Unload the current model and release memory.
+     */
+    unload(): void;
     /**
      * Get statistics from the last generation.
      * @returns Statistics including token count, speed, and timing
      */
     getLastGenerationStats(): GenerationStats;
+    /**
+     * Get the message history if management is enabled.
+     * @returns Array of messages in the history
+     */
+    getHistory(): LLMMessage[];
+    /**
+     * Clear the message history.
+     */
+    clearHistory(): void;
     /** Whether a model is currently loaded */
     readonly isLoaded: boolean;
     /** Whether text is currently being generated */

package/lib/typescript/src/specs/LLM.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LLM.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/LLM.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAA;IACxB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,GAAI,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;IACzD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5E;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzE;;OAEG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;OAGG;IACH,sBAAsB,IAAI,eAAe,CAAA;IAEzC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;CACrB"}
+{"version":3,"file":"LLM.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/LLM.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAA;IACxB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;GACG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,UAAU,EAAE,CAAA;IAChC,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,GAAI,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;IACzD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzE;;OAEG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;OAEG;IACH,MAAM,IAAI,IAAI,CAAA;IAEd;;;OAGG;IACH,sBAAsB,IAAI,eAAe,CAAA;IAEzC;;;OAGG;IACH,UAAU,IAAI,UAAU,EAAE,CAAA;IAE1B;;OAEG;IACH,YAAY,IAAI,IAAI,CAAA;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;CACrB"}