modelmix 4.4.4 → 4.4.7

package/README.md

@@ -47,7 +47,7 @@ import { ModelMix } from 'modelmix';
 
 // Get structured JSON responses
 const model = ModelMix.new()
-    .sonnet45() // Anthropic claude-sonnet-4-20250514
+    .sonnet46() // Anthropic claude-sonnet-4-6
     .addText("Name and capital of 3 South American countries.");
 
 const outputExample = { countries: [{ name: "", capital: "" }] };
@@ -65,7 +65,7 @@ const setup = {
 };
 
 const model = await ModelMix.new(setup)
-    .sonnet45() // (main model) Anthropic claude-sonnet-4-5-20250929
+    .sonnet46() // (main model) Anthropic claude-sonnet-4-5-20250929
     .gpt5mini() // (fallback 2) OpenAI gpt-5-mini
     .gemini3flash({ config: { temperature: 0 } }) // (fallback 3) Google gemini-3-flash
     .grok3mini() // (fallback 4) Grok grok-3-mini
@@ -146,9 +146,8 @@ Here's a comprehensive list of available methods:
 | `gptOss()`         | Together   | gpt-oss-120B                   | [\$0.15 / \$0.60][7]       |
 | `opus46[think]()`  | Anthropic  | claude-opus-4-6                | [\$5.00 / \$25.00][2]      |
 | `opus45[think]()`  | Anthropic  | claude-opus-4-5-20251101       | [\$5.00 / \$25.00][2]      |
-| `opus41[think]()`  | Anthropic  | claude-opus-4-1-20250805       | [\$15.00 / \$75.00][2]     |
+| `sonnet46[think]()`| Anthropic  | claude-sonnet-4-6              | [\$3.00 / \$15.00][2]      |
 | `sonnet45[think]()`| Anthropic  | claude-sonnet-4-5-20250929     | [\$3.00 / \$15.00][2]      |
-| `sonnet4[think]()` | Anthropic  | claude-sonnet-4-20250514       | [\$3.00 / \$15.00][2]      |
 | `haiku35()`        | Anthropic  | claude-3-5-haiku-20241022      | [\$0.80 / \$4.00][2]       |
 | `haiku45[think]()` | Anthropic  | claude-haiku-4-5-20251001      | [\$1.00 / \$5.00][2]       |
 | `gemini3pro()`     | Google     | gemini-3-pro-preview           | [\$2.00 / \$12.00][3]      |
@@ -208,7 +207,7 @@ ModelMix includes a simple but powerful templating system. You can write your sy
 ### Basic example with `replace`
 
 ```javascript
-const gpt = ModelMix.new().gpt5mini();
+const gpt = ModelMix.new().gpt52();
 
 gpt.addText('Write a short story about a {animal} that lives in {place}.');
 gpt.replace({ '{animal}': 'cat', '{place}': 'a haunted castle' });
@@ -325,19 +324,14 @@ console.log(result);
 
 ### Adding field descriptions
 
-The second argument lets you describe each field so the model understands exactly what you expect:
+The second argument lets you describe each field so the model understands exactly what you expect. Descriptions can be **strings** (simple) or **descriptor objects** (with metadata):
 
 ```javascript
-const model = ModelMix.new()
-    .gpt5mini()
-    .addText('Name and capital of 3 South American countries.');
-
 const result = await model.json(
     { countries: [{ name: "Argentina", capital: "BUENOS AIRES" }] },
     { countries: [{ name: "name of the country", capital: "capital of the country in uppercase" }] },
     { addNote: true }
 );
-console.log(result);
 // { countries: [
 //   { name: "Brazil", capital: "BRASILIA" },
 //   { name: "Colombia", capital: "BOGOTA" },
@@ -345,7 +339,40 @@ console.log(result);
 // ]}
 ```
 
-The example values (like `"Argentina"` and `"BUENOS AIRES"`) show the model the expected format, while the descriptions clarify what each field should contain.
+### Enhanced descriptors
+
+Descriptions support **descriptor objects** with `description`, `required`, `enum`, and `default`:
+
+```javascript
+const result = await model.json(
+    { name: 'martin', age: 22, sex: 'm' },
+    {
+        name: { description: 'Name of the actor', required: false },
+        age: 'Age of the actor',                                     // string still works
+        sex: { description: 'Gender', enum: ['m', 'f', null], default: 'm' }
+    }
+);
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `description` | `string` | — | Field description for the model |
+| `required` | `boolean` | `true` | If `false`, field is removed from `required` and type becomes nullable |
+| `enum` | `array` | — | Allowed values. If includes `null`, type auto-becomes nullable |
+| `default` | `any` | — | Default value for the field |
+
+You can mix strings and descriptor objects freely in the same descriptions parameter.
+
+### Array auto-wrap
+
+When you pass a top-level array as the example, ModelMix automatically wraps it for better LLM compatibility and unwraps the result transparently:
+
+```javascript
+const result = await model.json([{ name: 'martin' }]);
+// result is an array: [{ name: "Martin" }, { name: "Carlos" }, ...]
+```
+
+Internally, the array is wrapped as `{ out: [...] }` so the model receives a proper object schema, then `result.out` is returned automatically.
 
 ### Options
 
@@ -491,15 +518,16 @@ new ModelMix(args = { options: {}, config: {} })
   - `tokens`: Object with `input`, `output`, and `total` token counts
   - `response`: The raw API response
 - `stream(callback)`: Sends the message and streams the response, invoking the callback with each streamed part.
-- `json(schemaExample, descriptions = {})`: Forces the model to return a response in a specific JSON format.
-  - `schemaExample`: Optional example of the JSON structure to be returned.
-  - `descriptions`: Optional descriptions for each field in the JSON structure
+- `json(schemaExample, descriptions = {}, options = {})`: Forces the model to return a response in a specific JSON format.
+  - `schemaExample`: Example of the JSON structure to be returned. Top-level arrays are auto-wrapped for better LLM compatibility.
+  - `descriptions`: Descriptions for each field — can be strings or descriptor objects with `{ description, required, enum, default }`.
+  - `options`: `{ addSchema: true, addExample: false, addNote: false }`
   - Returns a Promise that resolves to the structured JSON response
   - Example:
     ```javascript
     const response = await handler.json(
       { time: '24:00:00', message: 'Hello' },
-      { time: 'Time in format HH:MM:SS' }
+      { time: 'Time in format HH:MM:SS', message: { description: 'Greeting', required: false } }
     );
     ```
 - `block({ addText = true })`: Forces the model to return a response in a specific block format.

package/demo/json.js

@@ -2,7 +2,7 @@ process.loadEnvFile();
 import { ModelMix } from '../index.js';
 
 const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { debug: 3 } })
-    .gemini3flash()
+    .sonnet46()
     // .gptOss()
     // .scout({ config: { temperature: 0 } })    
     // .o4mini()
@@ -11,17 +11,19 @@ const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { deb
     // .gemini25flash()
     .addText("Name and capital of 3 South American countries.")
 
-const jsonResult = await model.json({
-    countries: [{
-        name: "Argentina",
-        capital: "BUENOS AIRES"
-    }]
+const jsonResult = await model.json([{
+    name: "Argentina",
+    capital: "BUENOS AIRES"
 }, {
-    countries: [{
-        name: "name of the country",
-        capital: "capital of the country in uppercase"
-    }]
-}, { addNote: true });
+    name: "Brazil",
+    capital: "BRASILIA"
+}, {
+    name: "Colombia",
+    capital: "BOGOTA"
+}], [{
+    name: { description: "name of the country", enum: ["Perú", "Colombia", "Argentina"] },
+    capital: "capital of the country in uppercase"
+}], { addNote: true });
 
 console.log(jsonResult);
 console.log(model.lastRaw.tokens);

package/index.js

@@ -31,6 +31,7 @@ const MODEL_PRICING = {
     'claude-opus-4-6': [5.00, 25.00],
     'claude-opus-4-5-20251101': [5.00, 25.00],
     'claude-opus-4-1-20250805': [15.00, 75.00],
+    'claude-sonnet-4-6': [3.00, 15.00],
     'claude-sonnet-4-5-20250929': [3.00, 15.00],
     'claude-sonnet-4-20250514': [3.00, 15.00],
     'claude-3-5-haiku-20241022': [0.80, 4.00],
@@ -112,7 +113,7 @@ class ModelMix {
 
         this.config = {
             system: 'You are an assistant.',
-            max_history: 1, // Default max history
+            max_history: 0, // 0=no history (stateless), N=keep last N messages, -1=unlimited
             debug: 0, // 0=silent, 1=minimal, 2=readable summary, 3=full (no truncate), 4=verbose (raw details)
             bottleneck: defaultBottleneckConfig,
             roundRobin: false, // false=fallback mode, true=round robin rotation
@@ -305,6 +306,14 @@ class ModelMix {
         options = { ...MixAnthropic.thinkingOptions, ...options };
         return this.attach('claude-sonnet-4-20250514', new MixAnthropic({ options, config }));
     }
+    sonnet46({ options = {}, config = {} } = {}) {
+        return this.attach('claude-sonnet-4-6', new MixAnthropic({ options, config }));
+    }
+    sonnet46think({ options = {}, config = {} } = {}) {
+        options = { ...MixAnthropic.thinkingOptions, ...options };
+        return this.attach('claude-sonnet-4-6', new MixAnthropic({ options, config }));
+    }
+
     sonnet45({ options = {}, config = {} } = {}) {
         return this.attach('claude-sonnet-4-5-20250929', new MixAnthropic({ options, config }));
     }
@@ -640,6 +649,15 @@ class ModelMix {
 
     async json(schemaExample = null, schemaDescription = {}, { type = 'json_object', addExample = false, addSchema = true, addNote = false } = {}) {
 
+        let isArrayWrap = false;
+        if (Array.isArray(schemaExample)) {
+            isArrayWrap = true;
+            schemaExample = { out: schemaExample };
+            if (Array.isArray(schemaDescription)) {
+                schemaDescription = { out: schemaDescription };
+            }
+        }
+
         let options = {
             response_format: { type },
             stream: false,
@@ -666,7 +684,8 @@ class ModelMix {
             }
         }
         const { message } = await this.execute({ options, config });
-        return JSON.parse(this._extractBlock(message));
+        const parsed = JSON.parse(this._extractBlock(message));
+        return isArrayWrap ? parsed.out : parsed;
     }
 
     _extractBlock(response) {
@@ -760,26 +779,26 @@ class ModelMix {
         await this.processImages();
         this.applyTemplate();
 
-        // Smart message slicing to preserve tool call sequences
+        // Smart message slicing based on max_history:
+        // 0 = no history (stateless), N = keep last N messages, -1 = unlimited
         if (this.config.max_history > 0) {
             let sliceStart = Math.max(0, this.messages.length - this.config.max_history);
 
-            // If we're slicing and there's a tool message at the start, 
-            // ensure we include the preceding assistant message with tool_calls
-            while (sliceStart > 0 &&
-                sliceStart < this.messages.length &&
-                this.messages[sliceStart].role === 'tool') {
-                sliceStart--;
-                // Also need to include the assistant message with tool_calls
-                if (sliceStart > 0 &&
-                    this.messages[sliceStart].role === 'assistant' &&
-                    this.messages[sliceStart].tool_calls) {
+            // If we're slicing into the middle of a tool interaction,
+            // backtrack to include the full sequence (user → assistant/tool_calls → tool results)
+            while (sliceStart > 0 && sliceStart < this.messages.length) {
+                const msg = this.messages[sliceStart];
+                if (msg.role === 'tool' || (msg.role === 'assistant' && msg.tool_calls)) {
+                    sliceStart--;
+                } else {
                     break;
                 }
             }
 
             this.messages = this.messages.slice(sliceStart);
         }
+        // max_history = -1: unlimited, no slicing
+        // max_history = 0: no history, messages only contain what was added since last call
 
         this.messages = this.groupByRoles(this.messages);
         this.options.messages = this.messages;
@@ -900,11 +919,12 @@ class ModelMix {
                             this.messages.push({
                                 role: 'tool',
                                 tool_call_id: toolResult.tool_call_id,
+                                name: toolResult.name,
                                 content: toolResult.content
                             });
                         }
 
-                        return this.execute();
+                        return this.execute({ options, config });
                     }
 
                     // debug level 1: Just success indicator
@@ -941,6 +961,29 @@ class ModelMix {
                     if (currentConfig.debug >= 1) console.log('');
 
                     this.lastRaw = result;
+
+                    // Manage conversation history based on max_history setting
+                    if (this.config.max_history === 0) {
+                        // Stateless: clear messages so next call starts fresh
+                        this.messages = [];
+                    } else if (result.message) {
+                        // Persist assistant response for multi-turn conversations
+                        if (result.signature) {
+                            this.messages.push({
+                                role: "assistant", content: [{
+                                    type: "thinking",
+                                    thinking: result.think,
+                                    signature: result.signature
+                                }, {
+                                    type: "text",
+                                    text: result.message
+                                }]
+                            });
+                        } else {
+                            this.addText(result.message, { role: "assistant" });
+                        }
+                    }
+
                     return result;
 
                 } catch (error) {
@@ -1043,7 +1086,7 @@ class ModelMix {
             return;
         }
 
-        if (this.config.max_history < 3) {
+        if (this.config.max_history >= 0 && this.config.max_history < 3) {
             log.warn(`MCP ${key} requires at least 3 max_history. Setting to 3.`);
             this.config.max_history = 3;
         }
@@ -1079,7 +1122,7 @@ class ModelMix {
 
     addTool(toolDefinition, callback) {
 
-        if (this.config.max_history < 3) {
+        if (this.config.max_history >= 0 && this.config.max_history < 3) {
             log.warn(`MCP ${toolDefinition.name} requires at least 3 max_history. Setting to 3.`);
             this.config.max_history = 3;
         }
@@ -1531,6 +1574,18 @@ class MixAnthropic extends MixCustom {
 
         return filteredMessages.map(message => {
             if (message.role === 'tool') {
+                // Handle new format: tool_call_id directly on message
+                if (message.tool_call_id) {
+                    return {
+                        role: "user",
+                        content: [{
+                            type: "tool_result",
+                            tool_use_id: message.tool_call_id,
+                            content: message.content
+                        }]
+                    }
+                }
+                // Handle old format: content is an array
                 return {
                     role: "user",
                     content: message.content.map(content => ({
@@ -1961,13 +2016,33 @@ class MixGoogle extends MixCustom {
             if (message.role === 'assistant' && message.tool_calls) {
                 return {
                     role: 'model',
-                    parts: message.tool_calls.map(toolCall => ({
-                        functionCall: {
-                            name: toolCall.function.name,
-                            args: JSON.parse(toolCall.function.arguments)
-                        },
-                        thought_signature: toolCall.thought_signature || ""
-                    }))
+                    parts: message.tool_calls.map(toolCall => {
+                        const part = {
+                            functionCall: {
+                                name: toolCall.function.name,
+                                args: JSON.parse(toolCall.function.arguments)
+                            }
+                        };
+                        if (toolCall.thought_signature) {
+                            part.thoughtSignature = toolCall.thought_signature;
+                        }
+                        return part;
+                    })
+                }
+            }
+
+            // Handle new tool result format: tool_call_id and name directly on message
+            if (message.role === 'tool' && message.name) {
+                return {
+                    role: 'user',
+                    parts: [{
+                        functionResponse: {
+                            name: message.name,
+                            response: {
+                                output: message.content,
+                            },
+                        }
+                    }]
                 }
             }
 
@@ -1975,6 +2050,7 @@ class MixGoogle extends MixCustom {
             const role = (message.role === 'assistant' || message.role === 'tool') ? 'model' : 'user'
 
             if (message.role === 'tool') {
+                // Handle old format: content is an array of {name, content}
                 return {
                     role,
                     parts: message.content.map(content => ({
@@ -2017,6 +2093,22 @@ class MixGoogle extends MixCustom {
                 })
             }
         });
+
+        // Merge consecutive user messages containing only functionResponse parts
+        // Google requires all function responses for a turn in a single message
+        return converted.reduce((acc, msg) => {
+            if (acc.length > 0) {
+                const prev = acc[acc.length - 1];
+                if (prev.role === 'user' && msg.role === 'user' &&
+                    prev.parts.every(p => p.functionResponse) &&
+                    msg.parts.every(p => p.functionResponse)) {
+                    prev.parts.push(...msg.parts);
+                    return acc;
+                }
+            }
+            acc.push(msg);
+            return acc;
+        }, []);
     }
 
     async create({ config = {}, options = {} } = {}) {
@@ -2042,7 +2134,13 @@ class MixGoogle extends MixCustom {
             generationConfig.topP = options.top_p;
         }
 
-        generationConfig.responseMimeType = "text/plain";
+        // Gemini does not support responseMimeType when function calling is used
+        const hasTools = options.tools && options.tools.length > 0 &&
+            options.tools.some(t => t.functionDeclarations && t.functionDeclarations.length > 0);
+
+        if (!hasTools) {
+            generationConfig.responseMimeType = "text/plain";
+        }
 
         const payload = {
             generationConfig,
@@ -2124,6 +2222,21 @@ class MixGoogle extends MixCustom {
         };
     }
 
+    static stripUnsupportedSchemaProps(schema) {
+        if (!schema || typeof schema !== 'object') return schema;
+        const cleaned = { ...schema };
+        delete cleaned.default;
+        if (cleaned.properties) {
+            cleaned.properties = Object.fromEntries(
+                Object.entries(cleaned.properties).map(([key, value]) => [key, MixGoogle.stripUnsupportedSchemaProps(value)])
+            );
+        }
+        if (cleaned.items) {
+            cleaned.items = MixGoogle.stripUnsupportedSchemaProps(cleaned.items);
+        }
+        return cleaned;
+    }
+
     static getOptionsTools(tools) {
         const functionDeclarations = [];
         for (const tool in tools) {
@@ -2131,7 +2244,7 @@ class MixGoogle extends MixCustom {
                 functionDeclarations.push({
                     name: item.name,
                     description: item.description,
-                    parameters: item.inputSchema
+                    parameters: MixGoogle.stripUnsupportedSchemaProps(item.inputSchema)
                 });
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.4.4",
+  "version": "4.4.7",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -73,4 +73,4 @@
     "test:live.mcp": "mocha test/live.mcp.js --timeout 60000 --require dotenv/config --require test/setup.js",
     "test:tokens": "mocha test/tokens.test.js --timeout 10000 --require dotenv/config --require test/setup.js"
   }
-}
+}

package/schema.js

@@ -1,3 +1,29 @@
+const META_KEYS = new Set(['description', 'required', 'enum', 'default', 'nullable']);
+
+function isDescriptor(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every(k => META_KEYS.has(k));
+}
+
+function makeNullable(fieldSchema) {
+    if (!fieldSchema.type) return fieldSchema;
+    if (Array.isArray(fieldSchema.type)) {
+        if (!fieldSchema.type.includes('null')) fieldSchema.type.push('null');
+    } else {
+        fieldSchema.type = [fieldSchema.type, 'null'];
+    }
+    return fieldSchema;
+}
+
+function getNestedDescriptions(desc) {
+    if (!desc) return {};
+    if (typeof desc === 'string') return {};
+    if (Array.isArray(desc)) return desc[0] || {};
+    if (isDescriptor(desc)) return {};
+    return desc;
+}
+
 function generateJsonSchema(example, descriptions = {}) {
     function detectType(key, value) {
         if (value === null) return { type: 'null' };
@@ -32,7 +58,7 @@ function generateJsonSchema(example, descriptions = {}) {
             if (typeof value[0] === 'object' && !Array.isArray(value[0])) {
                 return {
                     type: 'array',
-                    items: generateJsonSchema(value[0], descriptions[key] || {})
+                    items: generateJsonSchema(value[0], getNestedDescriptions(descriptions[key]))
                 };
             } else {
                 return {
@@ -42,7 +68,7 @@ function generateJsonSchema(example, descriptions = {}) {
             }
         }
         if (typeof value === 'object') {
-            return generateJsonSchema(value, descriptions[key] || {});
+            return generateJsonSchema(value, getNestedDescriptions(descriptions[key]));
         }
         return {};
     }
@@ -65,13 +91,31 @@ function generateJsonSchema(example, descriptions = {}) {
 
     for (const key in example) {
         const fieldSchema = detectType(key, example[key]);
+        const desc = descriptions[key];
+        let isRequired = true;
 
-        if (descriptions[key] && typeof fieldSchema === 'object') {
-            fieldSchema.description = descriptions[key];
+        if (desc) {
+            if (typeof desc === 'string') {
+                fieldSchema.description = desc;
+            } else if (typeof desc === 'object' && !Array.isArray(desc) && isDescriptor(desc)) {
+                if (desc.description) fieldSchema.description = desc.description;
+                if (desc.enum) fieldSchema.enum = desc.enum;
+                if (desc.default !== undefined) fieldSchema.default = desc.default;
+                if (desc.required === false) {
+                    isRequired = false;
+                    makeNullable(fieldSchema);
+                }
+                if (desc.nullable === true) {
+                    makeNullable(fieldSchema);
+                }
+                if (desc.enum && desc.enum.includes(null)) {
+                    makeNullable(fieldSchema);
+                }
+            }
         }
 
         schema.properties[key] = fieldSchema;
-        schema.required.push(key);
+        if (isRequired) schema.required.push(key);
     }
 
     return schema;

package/skills/modelmix/SKILL.md

@@ -75,8 +75,8 @@ Chain shorthand methods to attach providers. First model is primary; others are
 
 ```javascript
 const model = ModelMix.new()
-    .sonnet45()        // primary
-    .gpt5mini()        // fallback 1
+    .sonnet46()        // primary
+    .gpt52()        // fallback 1
     .gemini3flash()    // fallback 2
     .addText("Hello!")
 ```
@@ -86,7 +86,7 @@ If `sonnet45` fails, it automatically tries `gpt5mini`, then `gemini3flash`.
 ## Available Model Shorthands
 
 - **OpenAI**: `gpt52` `gpt51` `gpt5` `gpt5mini` `gpt5nano` `gpt41` `gpt41mini` `gpt41nano`
-- **Anthropic**: `opus46` `opus45` `sonnet45` `sonnet4` `haiku45` `haiku35` (thinking variants: add `think` suffix)
+- **Anthropic**: `opus46` `opus45` `sonnet46` `sonnet45` `haiku45` `haiku35` (thinking variants: add `think` suffix)
 - **Google**: `gemini3pro` `gemini3flash` `gemini25pro` `gemini25flash`
 - **Grok**: `grok4` `grok41` (thinking variant available)
 - **Perplexity**: `sonar` `sonarPro`
@@ -125,6 +125,36 @@ const result = await ModelMix.new()
 
 `json()` signature: `json(schemaExample, schemaDescription?, { addSchema, addExample, addNote }?)`
 
+#### Enhanced descriptors
+
+Descriptions can be **strings** or **descriptor objects** with metadata:
+
+```javascript
+const result = await model.json(
+    { name: 'martin', age: 22, sex: 'Male' },
+    {
+        name: { description: 'Name of the actor', required: false },
+        age: 'Age of the actor',                                     // string still works
+        sex: { description: 'Gender', enum: ['Male', 'Female', null] }
+    }
+);
+```
+
+Descriptor properties:
+- `description` (string) — field description
+- `required` (boolean, default `true`) — if `false`: removed from required array, type becomes nullable
+- `enum` (array) — allowed values; if includes `null`, type auto-becomes nullable
+- `default` (any) — default value
+
+#### Array auto-wrap
+
+Top-level arrays are auto-wrapped as `{ out: [...] }` for better LLM compatibility, and unwrapped on return:
+
+```javascript
+const result = await model.json([{ name: 'martin' }]);
+// result is an array: [{ name: "Martin" }, { name: "Carlos" }, ...]
+```
+
 ### Stream a response
 
 ```javascript
@@ -282,7 +312,7 @@ const reply = await chat.message();  // "Martin"
 - Store API keys in `.env` and load with `dotenv/config` or `process.loadEnvFile()`. Never hardcode keys.
 - Chain models for resilience: primary model first, fallbacks after.
 - When using MCP tools or `addTool()`, set `max_history` to at least 3.
-- Use `.json()` for structured output instead of parsing text manually.
+- Use `.json()` for structured output instead of parsing text manually. Use descriptor objects `{ description, required, enum, default }` in descriptions for richer schema control.
 - Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
 - For thinking models, append `think` to the method name (e.g. `sonnet45think()`).
 - Template placeholders use `{key}` syntax in both system prompts and user messages.
@@ -302,7 +332,7 @@ const reply = await chat.message();  // "Martin"
 | `.replace({})` | `this` | Set placeholder replacements |
 | `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
 | `.message()` | `Promise<string>` | Get text response |
-| `.json(example, desc?, opts?)` | `Promise<object>` | Get structured JSON |
+| `.json(example, desc?, opts?)` | `Promise<object\|array>` | Get structured JSON. Descriptions support descriptor objects `{ description, required, enum, default }`. Top-level arrays auto-wrapped |
 | `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |
 | `.lastRaw` | `object \| null` | Full response from last `message()`/`json()`/`block()`/`stream()` call |
 | `.stream(callback)` | `Promise` | Stream response |