feat(api): add reasoning_effort parameter (OpenAI standard)

Maps `reasoning_effort` (high/medium/low/none) to internal
`thinkingBudget` on both OpenAI and Anthropic endpoints:

- high → 32768 tokens (deep thinking)
- medium → 8192 tokens (balanced)
- low → 1024 tokens (brief thinking)
- none → 0 (disables thinking entirely)

Explicit `thinking_budget` takes precedence over `reasoning_effort`.
Case-insensitive matching. 3 new tests covering decode, mapping, and precedence.

Author: lucasliu

Sources/NovaMLXAPI/APIServer.swift

@@ -481,7 +481,7 @@ public final class NovaMLXAPIServer: @unchecked Sendable {
                     maxTokens: ocrSampling.maxTokens,
                     topP: anthropicReq.topP, topK: anthropicReq.topK,
                     stream: false, stop: ocrStop,
-                    thinkingBudget: anthropicReq.thinkingBudget,
+                    thinkingBudget: anthropicReq.resolvedThinkingBudget,
                     enableThinking: anthropicReq.resolvedEnableThinking,
                     preserveThinking: anthropicReq.resolvedPreserveThinking
                 )
@@ -1726,7 +1726,7 @@ public final class NovaMLXAPIServer: @unchecked Sendable {
             sessionId: sessionId, responseFormat: responseFormat,
             jsonSchemaDef: jsonSchemaDef,
             regexPattern: regexPattern, gbnfGrammar: gbnfGrammar,
-            thinkingBudget: openAIReq.thinkingBudget,
+            thinkingBudget: openAIReq.resolvedThinkingBudget,
             enableThinking: openAIReq.resolvedEnableThinking,
             preserveThinking: openAIReq.resolvedPreserveThinking
         )
@@ -1863,7 +1863,7 @@ public final class NovaMLXAPIServer: @unchecked Sendable {
             sessionId: sessionId, responseFormat: responseFormat,
             jsonSchemaDef: jsonSchemaDef,
             regexPattern: regexPattern, gbnfGrammar: gbnfGrammar,
-            thinkingBudget: openAIReq.thinkingBudget,
+            thinkingBudget: openAIReq.resolvedThinkingBudget,
             enableThinking: openAIReq.resolvedEnableThinking,
             preserveThinking: openAIReq.resolvedPreserveThinking
         )

Sources/NovaMLXAPI/AnthropicTypes.swift

@@ -35,6 +35,7 @@ public struct AnthropicRequest: Codable, Sendable {
     public let enableThinking: Bool?
     public let preserveThinking: Bool?
     public let chatTemplateKwargs: [String: AnyCodable]?
+    public let reasoningEffort: String?
 
     private enum CodingKeys: String, CodingKey {
         case model, messages, maxTokens = "max_tokens", system, temperature
@@ -44,6 +45,7 @@ public struct AnthropicRequest: Codable, Sendable {
         case enableThinking = "enable_thinking"
         case preserveThinking = "preserve_thinking"
         case chatTemplateKwargs = "chat_template_kwargs"
+        case reasoningEffort = "reasoning_effort"
     }
 
     public init(
@@ -61,7 +63,8 @@ public struct AnthropicRequest: Codable, Sendable {
         thinkingBudget: Int? = nil,
         enableThinking: Bool? = nil,
         preserveThinking: Bool? = nil,
-        chatTemplateKwargs: [String: AnyCodable]? = nil
+        chatTemplateKwargs: [String: AnyCodable]? = nil,
+        reasoningEffort: String? = nil
     ) {
         self.model = model
         self.messages = messages
@@ -78,6 +81,7 @@ public struct AnthropicRequest: Codable, Sendable {
         self.enableThinking = enableThinking
         self.preserveThinking = preserveThinking
         self.chatTemplateKwargs = chatTemplateKwargs
+        self.reasoningEffort = reasoningEffort
     }
 
     /// Resolve thinking toggle from multiple client formats, mirrors OpenAI pattern
@@ -104,6 +108,19 @@ public struct AnthropicRequest: Codable, Sendable {
         }
         return nil
     }
+
+    /// Map reasoning_effort to thinkingBudget (same mapping as OpenAI).
+    public var resolvedThinkingBudget: Int? {
+        if let budget = thinkingBudget { return budget }
+        guard let effort = reasoningEffort?.lowercased() else { return nil }
+        switch effort {
+        case "high": return 32768
+        case "medium": return 8192
+        case "low": return 1024
+        case "none": return 0
+        default: return nil
+        }
+    }
 }
 
 public struct AnthropicTokenCountRequest: Codable, Sendable {

Sources/NovaMLXAPI/OpenAITypes.swift

@@ -179,6 +179,7 @@ public struct OpenAIRequest: Codable, Sendable {
     public let enableThinking: Bool?
     public let preserveThinking: Bool?
     public let chatTemplateKwargs: [String: AnyCodable]?
+    public let reasoningEffort: String?
 
     private enum CodingKeys: String, CodingKey {
         case model, messages, temperature, stream, stop, n, seed, tools
@@ -197,6 +198,7 @@ public struct OpenAIRequest: Codable, Sendable {
         case enableThinking = "enable_thinking"
         case preserveThinking = "preserve_thinking"
         case chatTemplateKwargs = "chat_template_kwargs"
+        case reasoningEffort = "reasoning_effort"
     }
 
     public init(
@@ -222,7 +224,8 @@ public struct OpenAIRequest: Codable, Sendable {
         thinkingBudget: Int? = nil,
         enableThinking: Bool? = nil,
         preserveThinking: Bool? = nil,
-        chatTemplateKwargs: [String: AnyCodable]? = nil
+        chatTemplateKwargs: [String: AnyCodable]? = nil,
+        reasoningEffort: String? = nil
     ) {
         self.model = model
         self.messages = messages
@@ -247,6 +250,7 @@ public struct OpenAIRequest: Codable, Sendable {
         self.enableThinking = enableThinking
         self.preserveThinking = preserveThinking
         self.chatTemplateKwargs = chatTemplateKwargs
+        self.reasoningEffort = reasoningEffort
     }
 
     /// Resolve thinking toggle from multiple client formats:
@@ -286,6 +290,25 @@ public struct OpenAIRequest: Codable, Sendable {
         return nil
     }
 
+    /// Map OpenAI-standard `reasoning_effort` to internal `thinkingBudget`.
+    /// Only used when `thinkingBudget` is not explicitly set — explicit budget wins.
+    /// - "high" → 32768 tokens (deep thinking)
+    /// - "medium" → 8192 tokens (balanced)
+    /// - "low" → 1024 tokens (brief thinking)
+    /// - "none" → 0 (disables thinking entirely)
+    public var resolvedThinkingBudget: Int? {
+        // Explicit thinking_budget takes precedence
+        if let budget = thinkingBudget { return budget }
+        guard let effort = reasoningEffort?.lowercased() else { return nil }
+        switch effort {
+        case "high": return 32768
+        case "medium": return 8192
+        case "low": return 1024
+        case "none": return 0
+        default: return nil
+        }
+    }
+
 }
 
 public enum MessageContent: Codable, Sendable {

Tests/NovaMLXAPITests/APITests.swift

@@ -442,4 +442,50 @@ struct APITypesTests {
         #expect(img.url == "https://example.com/photo.jpg")
         #expect(img.detail == "high")
     }
+
+    // MARK: - reasoning_effort mapping
+
+    @Test("reasoning_effort decodes from JSON")
+    func reasoningEffortDecodes() throws {
+        let json = """
+        {"model":"test","messages":[],"reasoning_effort":"high"}
+        """
+        let data = json.data(using: .utf8)!
+        let req = try JSONDecoder().decode(OpenAIRequest.self, from: data)
+        #expect(req.reasoningEffort == "high")
+    }
+
+    @Test("reasoning_effort maps to thinking budget")
+    func reasoningEffortMapping() throws {
+        let cases: [(String?, Int?)] = [
+            ("high", 32768),
+            ("medium", 8192),
+            ("low", 1024),
+            ("none", 0),
+            ("HIGH", 32768), // case-insensitive
+            (nil, nil),
+            ("unknown", nil),
+        ]
+        for (effort, expected) in cases {
+            let req = OpenAIRequest(
+                model: "test",
+                messages: [],
+                reasoningEffort: effort
+            )
+            #expect(req.resolvedThinkingBudget == expected,
+                    "reasoning_effort=\(effort ?? "nil") should map to \(String(describing: expected))")
+        }
+    }
+
+    @Test("explicit thinking_budget wins over reasoning_effort")
+    func thinkingBudgetPrecedence() throws {
+        let req = OpenAIRequest(
+            model: "test",
+            messages: [],
+            thinkingBudget: 2048,
+            reasoningEffort: "high"
+        )
+        #expect(req.resolvedThinkingBudget == 2048,
+                "Explicit thinking_budget should take precedence over reasoning_effort")
+    }
 }