Merge branch 'main' into kv-cache

Author: DePasqualeOrg

Applications/MLXChatExample/Services/MLXService.swift

@@ -29,6 +29,7 @@ class MLXService {
             name: "qwen2.5VL:3b", configuration: VLMRegistry.qwen2_5VL3BInstruct4Bit, type: .vlm),
         LMModel(name: "qwen2VL:2b", configuration: VLMRegistry.qwen2VL2BInstruct4Bit, type: .vlm),
         LMModel(name: "smolVLM", configuration: VLMRegistry.smolvlminstruct4bit, type: .vlm),
+        LMModel(name: "acereason:7B", configuration: LLMRegistry.acereason_7b_4bit, type: .llm),
     ]
 
     /// Cache to store loaded model containers to avoid reloading.

Libraries/MLXLLM/Documentation.docc/Documentation.md

@@ -11,8 +11,24 @@ Example implementations of various Large Language Models (LLMs).
 - [MLXVLM](MLXVLM)
 - [StableDiffusion](StableDiffusion)
 
+## Quick Start
+
+See <doc:evaluation>.
+
+Using LLMs and VLMs is as easy as this:
+
+```swift
+let model = try await loadModel(id: "mlx-community/Qwen3-4B-4bit")
+let session = ChatSession(model)
+print(try await session.respond(to: "What are two things to see in San Francisco?")
+print(try await session.respond(to: "How about a great place to eat?")
+```
+
+More advanced APIs are available for those that need them, see <doc:using-model>.
+
 ## Topics
 
+- <doc:evaluation>
 - <doc:adding-model>
 - <doc:using-model>
 
@@ -32,3 +48,4 @@ Example implementations of various Large Language Models (LLMs).
 - ``Starcoder2Model``
 - ``MiMoModel``
 - ``GLM4Model``
+- ``AceReason``

Libraries/MLXLLM/Documentation.docc/evaluation.md

@@ -0,0 +1,70 @@
+#  Evaluation
+
+The simplified LLM/VLM API allows you to load a model and evaluate prompts with only a few lines of code.
+
+For example, this loads a model and asks a question and a follow-on question:
+
+```swift
+let model = try await loadModel(id: "mlx-community/Qwen3-4B-4bit")
+let session = ChatSession(model)
+print(try await session.respond(to: "What are two things to see in San Francisco?")
+print(try await session.respond(to: "How about a great place to eat?")
+```
+
+The second question actually refers to information (the location) from the first
+question -- this context is maintained inside the ``ChatSession`` object.
+
+If you need a one-shot prompt/response simply create a ``ChatSession``, evaluate
+the prompt and discard.  Multiple ``ChatSession`` instances could also be used
+(at the cost of the memory in the `KVCache`) to handle multiple streams of
+context.
+
+## Streaming Output
+
+The previous example produced the entire response in one call.  Often
+users want to see the text as it is generated -- you can do this with
+a stream:
+
+```swift
+let model = try await loadModel(id: "mlx-community/Qwen3-4B-4bit")
+let session = ChatSession(model)
+
+for try await item in session.streamResponse(to: "Why is the sky blue?") {
+    print(item, terminator: "")
+}
+print()
+```
+
+## VLMs (Vision Language Models)
+
+This same API supports VLMs as well.  Simply present the image or video
+to the ``ChatSession``:
+
+```swift
+let model = try await loadModel(id: "mlx-community/Qwen2.5-VL-3B-Instruct-4bit")
+let session = ChatSession(model)
+
+let answer1 = try await session.respond(
+    to: "what kind of creature is in the picture?"
+    image: .url(URL(fileURLWithPath: "support/test.jpg"))
+)
+print(answer1)
+
+// we can ask a followup question referring back to the previous image
+let answer2 = try await session.respond(
+    to: "What is behind the dog?"
+)
+print(answer2)
+```
+
+## Advanced Usage
+
+The ``ChatSession`` has a number of parameters you can supply when creating it:
+
+- **instructions**: optional instructions to the chat session, e.g. describing what type of responses to give
+    - for example you might instruct the language model to respond in rhyme or
+        talking like a famous character from a movie
+    - or that the responses should be very brief
+- **generateParameters**: parameters that control the generation of output, e.g. token limits and temperature
+    - see ``GenerateParameters``
+- **processing**: optional media processing instructions

Libraries/MLXLLM/Documentation.docc/using-model.md

@@ -2,6 +2,9 @@
 
 Using a model is easy:  load the weights, tokenize and evaluate.
 
+There is a high level API described in <doc:evaluation> and this documentation
+describes the lower level API if you need more control.
+
 ## Loading a Model
 
 A model is typically loaded by using a `ModelFactory` and a `ModelConfiguration`:

Libraries/MLXLLM/LLMModelFactory.swift

@@ -45,6 +45,7 @@ public class LLMTypeRegistry: ModelTypeRegistry, @unchecked Sendable {
             "granite": create(GraniteConfiguration.self, GraniteModel.init),
             "mimo": create(MiMoConfiguration.self, MiMoModel.init),
             "glm4": create(GLM4Configuration.self, GLM4Model.init),
+            "acereason": create(Qwen2Configuration.self, Qwen2Model.init),
         ]
     }
 
@@ -211,6 +212,11 @@ public class LLMRegistry: AbstractModelRegistry, @unchecked Sendable {
         defaultPrompt: "Why is the sky blue?"
     )
 
+    static public let acereason_7b_4bit = ModelConfiguration(
+        id: "mlx-community/AceReason-Nemotron-7B-4bit",
+        defaultPrompt: ""
+    )
+
     private static func all() -> [ModelConfiguration] {
         [
             codeLlama13b4bit,
@@ -240,6 +246,7 @@ public class LLMRegistry: AbstractModelRegistry, @unchecked Sendable {
             smolLM_135M_4bit,
             mimo_7b_sft_4bit,
             glm4_9b_4bit,
+            acereason_7b_4bit,
         ]
     }
 
@@ -312,7 +319,7 @@ public class LLMModelFactory: ModelFactory {
     public func _load(
         hub: HubApi, configuration: ModelConfiguration,
         progressHandler: @Sendable @escaping (Progress) -> Void
-    ) async throws -> ModelContext {
+    ) async throws -> sending ModelContext {
         // download weights and config
         let modelDirectory = try await downloadModel(
             hub: hub, configuration: configuration, progressHandler: progressHandler)
@@ -361,3 +368,9 @@ public class LLMModelFactory: ModelFactory {
     }
 
 }
+
+public class TrampolineModelFactory: NSObject, ModelFactoryTrampoline {
+    public static func modelFactory() -> (any MLXLMCommon.ModelFactory)? {
+        LLMModelFactory.shared
+    }
+}

Libraries/MLXLLM/README.md

@@ -58,9 +58,26 @@ Currently supported model types are:
 - Starcoder2
 - MiMo
 - GLM4
+- AceReason
 
 See [llm-tool](../../Tools/llm-tool)
 
+# Quick Start
+
+Using LLMs and VLMs from MLXLMCommon is as easy as:
+
+```swift
+let model = try await loadModel(id: "mlx-community/Qwen3-4B-4bit")
+let session = ChatSession(model)
+print(try await session.respond(to: "What are two things to see in San Francisco?")
+print(try await session.respond(to: "How about a great place to eat?")
+```
+
+For more information see 
+[Evaluation](https://swiftpackageindex.com/ml-explore/mlx-swift-examples/main/documentation/mlxlmcommon/evaluation)
+or [Using Models](https://swiftpackageindex.com/ml-explore/mlx-swift-examples/main/documentation/mlxlmcommon/using-model)
+for more advanced API.
+
 # Adding a Model
 
 If the model follows the typical LLM pattern: