modelmix 4.4.4 → 4.4.6

package/demo/json.js

@@ -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

@@ -112,7 +112,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
@@ -640,6 +640,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 +675,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,7 +770,8 @@ 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);
 
@@ -780,6 +791,8 @@ class ModelMix {
 
             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;
@@ -941,6 +954,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 +1079,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 +1115,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;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.4.4",
+  "version": "4.4.6",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {

package/schema.js

@@ -1,3 +1,29 @@
+const META_KEYS = new Set(['description', 'required', 'enum', 'default']);
+
+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,28 @@ 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.enum && desc.enum.includes(null)) {
+                    makeNullable(fieldSchema);
+                }
+            }
         }
 
         schema.properties[key] = fieldSchema;
-        schema.required.push(key);
+        if (isRequired) schema.required.push(key);
     }
 
     return schema;

package/test/bottleneck.test.js

@@ -115,6 +115,7 @@ describe('Rate Limiting with Bottleneck Tests', () => {
             model = ModelMix.new({
                 config: {
                     debug: false,
+                    max_history: -1, // concurrent calls need history to preserve queued messages
                     bottleneck: {
                         maxConcurrent: 2,
                         minTime: 50
@@ -335,6 +336,7 @@ describe('Rate Limiting with Bottleneck Tests', () => {
             const model = ModelMix.new({
                 config: {
                     debug: false,
+                    max_history: -1,
                     bottleneck: {
                         maxConcurrent: 5,
                         minTime: 100,
@@ -385,6 +387,7 @@ describe('Rate Limiting with Bottleneck Tests', () => {
             const model = ModelMix.new({
                 config: {
                     debug: false,
+                    max_history: -1,
                     bottleneck: {
                         maxConcurrent: 1,
                         minTime: 200
@@ -432,6 +435,7 @@ describe('Rate Limiting with Bottleneck Tests', () => {
             const model = ModelMix.new({
                 config: {
                     debug: false,
+                    max_history: -1,
                     bottleneck: {
                         maxConcurrent: 2,
                         minTime: 100,

package/test/history.test.js

@@ -0,0 +1,572 @@
+const { expect } = require('chai');
+const sinon = require('sinon');
+const nock = require('nock');
+const { ModelMix } = require('../index.js');
+
+describe('Conversation History Tests', () => {
+
+    if (global.setupTestHooks) {
+        global.setupTestHooks();
+    }
+
+    afterEach(() => {
+        nock.cleanAll();
+        sinon.restore();
+    });
+
+    describe('Assistant Response Persistence', () => {
+        let model;
+
+        beforeEach(() => {
+            model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+        });
+
+        it('should add assistant response to message history after message()', async () => {
+            model.gpt5mini().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'Hi there!'
+                        }
+                    }]
+                });
+
+            await model.message();
+
+            // After the call, messages should contain both user and assistant
+            expect(model.messages).to.have.length(2);
+            expect(model.messages[0].role).to.equal('user');
+            expect(model.messages[1].role).to.equal('assistant');
+            expect(model.messages[1].content[0].text).to.equal('Hi there!');
+        });
+
+        it('should add assistant response to message history after raw()', async () => {
+            model.sonnet4().addText('Hello');
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'Hi from Claude!'
+                    }]
+                });
+
+            await model.raw();
+
+            expect(model.messages).to.have.length(2);
+            expect(model.messages[0].role).to.equal('user');
+            expect(model.messages[1].role).to.equal('assistant');
+            expect(model.messages[1].content[0].text).to.equal('Hi from Claude!');
+        });
+    });
+
+    describe('Multi-turn Conversations', () => {
+
+        it('should include previous assistant response in second API call (OpenAI)', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gpt5mini();
+
+            // First turn
+            model.addText('Capital of France?');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'The capital of France is Paris.'
+                        }
+                    }]
+                });
+
+            await model.message();
+
+            // Second turn - capture the request body to verify history
+            let capturedBody;
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'The capital of Germany is Berlin.'
+                        }
+                    }]
+                });
+
+            model.addText('Capital of Germany?');
+            await model.message();
+
+            // Verify the second request includes system + user + assistant + user
+            expect(capturedBody.messages).to.have.length(4); // system + 3 conversation messages
+            expect(capturedBody.messages[0].role).to.equal('system');
+            expect(capturedBody.messages[1].role).to.equal('user');
+            expect(capturedBody.messages[2].role).to.equal('assistant');
+            // OpenAI content is an array of {type, text} objects
+            const assistantContent = capturedBody.messages[2].content;
+            const assistantText = Array.isArray(assistantContent)
+                ? assistantContent[0].text
+                : assistantContent;
+            expect(assistantText).to.include('Paris');
+            expect(capturedBody.messages[3].role).to.equal('user');
+        });
+
+        it('should include previous assistant response in second API call (Anthropic)', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.sonnet4();
+
+            // First turn
+            model.addText('Capital of France?');
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'The capital of France is Paris.'
+                    }]
+                });
+
+            await model.message();
+
+            // Second turn - capture the request body
+            let capturedBody;
+            nock('https://api.anthropic.com')
+                .post('/v1/messages', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'The capital of Germany is Berlin.'
+                    }]
+                });
+
+            model.addText('Capital of Germany?');
+            await model.message();
+
+            // Anthropic: system is separate, messages should be user/assistant/user
+            expect(capturedBody.messages).to.have.length(3);
+            expect(capturedBody.messages[0].role).to.equal('user');
+            expect(capturedBody.messages[1].role).to.equal('assistant');
+            expect(capturedBody.messages[1].content[0].text).to.include('Paris');
+            expect(capturedBody.messages[2].role).to.equal('user');
+        });
+
+        it('should not merge consecutive user messages when assistant response is between them', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gpt5mini();
+
+            model.addText('First question');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'First answer'
+                        }
+                    }]
+                });
+
+            await model.message();
+
+            // Capture second request
+            let capturedBody;
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'Second answer'
+                        }
+                    }]
+                });
+
+            model.addText('Second question');
+            await model.message();
+
+            // The two user messages must NOT be merged into one
+            const userMessages = capturedBody.messages.filter(m => m.role === 'user');
+            expect(userMessages).to.have.length(2);
+            expect(userMessages[0].content[0].text).to.equal('First question');
+            expect(userMessages[1].content[0].text).to.equal('Second question');
+        });
+
+        it('should maintain correct alternating roles across 3 turns', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 20 }
+            });
+            model.gpt5mini();
+
+            const turns = [
+                { user: 'Question 1', assistant: 'Answer 1' },
+                { user: 'Question 2', assistant: 'Answer 2' },
+                { user: 'Question 3', assistant: 'Answer 3' },
+            ];
+
+            let capturedBody;
+
+            for (const turn of turns) {
+                model.addText(turn.user);
+
+                nock('https://api.openai.com')
+                    .post('/v1/chat/completions', (body) => {
+                        capturedBody = body;
+                        return true;
+                    })
+                    .reply(200, {
+                        choices: [{
+                            message: {
+                                role: 'assistant',
+                                content: turn.assistant
+                            }
+                        }]
+                    });
+
+                await model.message();
+            }
+
+            // After 3 turns, the last request should have system + 5 messages (u/a/u/a/u)
+            const msgs = capturedBody.messages.filter(m => m.role !== 'system');
+            expect(msgs).to.have.length(5);
+            expect(msgs.map(m => m.role)).to.deep.equal([
+                'user', 'assistant', 'user', 'assistant', 'user'
+            ]);
+        });
+    });
+
+    describe('max_history Limits', () => {
+
+        it('should be stateless with max_history=0 (default)', async () => {
+            const model = ModelMix.new({
+                config: { debug: false } // max_history defaults to 0
+            });
+            model.gpt5mini();
+
+            model.addText('Question 1');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Answer 1' }
+                    }]
+                });
+            await model.message();
+
+            // After call, messages should be cleared (stateless)
+            expect(model.messages).to.have.length(0);
+        });
+
+        it('should not send history on second call with max_history=0', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 0 }
+            });
+            model.gpt5mini();
+
+            // First turn
+            model.addText('Question 1');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Answer 1' }
+                    }]
+                });
+            await model.message();
+
+            // Second turn - capture request
+            let capturedBody;
+            model.addText('Question 2');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Answer 2' }
+                    }]
+                });
+            await model.message();
+
+            // Only system + current user message, no history from turn 1
+            const msgs = capturedBody.messages.filter(m => m.role !== 'system');
+            expect(msgs).to.have.length(1);
+            expect(msgs[0].role).to.equal('user');
+            expect(msgs[0].content[0].text).to.equal('Question 2');
+        });
+
+        it('should trim old messages when max_history is reached', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 2 }
+            });
+            model.gpt5mini();
+
+            // Turn 1
+            model.addText('Question 1');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Answer 1' }
+                    }]
+                });
+            await model.message();
+
+            // Turn 2 - capture request
+            let capturedBody;
+            model.addText('Question 2');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Answer 2' }
+                    }]
+                });
+            await model.message();
+
+            // With max_history=2, only the last 2 messages should be sent (assistant + user)
+            const msgs = capturedBody.messages.filter(m => m.role !== 'system');
+            expect(msgs.length).to.be.at.most(2);
+            // The last message should be the current user question
+            expect(msgs[msgs.length - 1].role).to.equal('user');
+            expect(msgs[msgs.length - 1].content[0].text).to.equal('Question 2');
+        });
+
+        it('should keep full history when max_history is large enough', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 100 }
+            });
+            model.gpt5mini();
+
+            // Turn 1
+            model.addText('Q1');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'A1' }
+                    }]
+                });
+            await model.message();
+
+            // Turn 2
+            let capturedBody;
+            model.addText('Q2');
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'A2' }
+                    }]
+                });
+            await model.message();
+
+            // All 3 messages should be present (user, assistant, user)
+            const msgs = capturedBody.messages.filter(m => m.role !== 'system');
+            expect(msgs).to.have.length(3);
+        });
+
+        it('should handle max_history=-1 (unlimited)', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: -1 }
+            });
+            model.gpt5mini();
+
+            for (let i = 1; i <= 5; i++) {
+                model.addText(`Question ${i}`);
+                nock('https://api.openai.com')
+                    .post('/v1/chat/completions')
+                    .reply(200, {
+                        choices: [{
+                            message: { role: 'assistant', content: `Answer ${i}` }
+                        }]
+                    });
+                await model.message();
+            }
+
+            // After 5 turns, all 10 messages should be in history (5 user + 5 assistant)
+            expect(model.messages).to.have.length(10);
+        });
+    });
+
+    describe('Cross-provider History', () => {
+
+        it('should maintain history when using Anthropic provider', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.haiku35();
+
+            model.addText('Hello');
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{ type: 'text', text: 'Hi there!' }]
+                });
+            await model.message();
+
+            let capturedBody;
+            model.addText('How are you?');
+            nock('https://api.anthropic.com')
+                .post('/v1/messages', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    content: [{ type: 'text', text: 'I am well!' }]
+                });
+            await model.message();
+
+            // Anthropic sends system separately; messages should be u/a/u
+            expect(capturedBody.messages).to.have.length(3);
+            expect(capturedBody.messages[0].role).to.equal('user');
+            expect(capturedBody.messages[1].role).to.equal('assistant');
+            expect(capturedBody.messages[1].content[0].text).to.equal('Hi there!');
+            expect(capturedBody.messages[2].role).to.equal('user');
+        });
+
+        it('should maintain history when using Google provider', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gemini25flash();
+
+            model.addText('Hello');
+            nock('https://generativelanguage.googleapis.com')
+                .post(/.*generateContent/)
+                .reply(200, {
+                    candidates: [{
+                        content: {
+                            parts: [{ text: 'Hi from Gemini!' }]
+                        }
+                    }]
+                });
+            await model.message();
+
+            let capturedBody;
+            model.addText('How are you?');
+            nock('https://generativelanguage.googleapis.com')
+                .post(/.*generateContent/, (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    candidates: [{
+                        content: {
+                            parts: [{ text: 'Great, thanks!' }]
+                        }
+                    }]
+                });
+            await model.message();
+
+            // Google sends messages in contents array with user/model roles
+            const userMsgs = capturedBody.contents.filter(m => m.role === 'user');
+            const modelMsgs = capturedBody.contents.filter(m => m.role === 'model');
+            expect(userMsgs).to.have.length(2);
+            expect(modelMsgs).to.have.length(1);
+        });
+    });
+
+    describe('Edge Cases', () => {
+
+        it('should handle single turn without breaking', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gpt5mini().addText('Just one question');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Just one answer' }
+                    }]
+                });
+
+            const response = await model.message();
+            expect(response).to.equal('Just one answer');
+            expect(model.messages).to.have.length(2);
+        });
+
+        it('should handle empty assistant response gracefully', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gpt5mini().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: '' }
+                    }]
+                });
+
+            const response = await model.message();
+            // Empty string is falsy, so assistant message should NOT be added
+            expect(response).to.equal('');
+        });
+
+        it('should handle multiple addText before first message()', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, max_history: 10 }
+            });
+            model.gpt5mini();
+
+            model.addText('Part 1');
+            model.addText('Part 2');
+
+            let capturedBody;
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', (body) => {
+                    capturedBody = body;
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{
+                        message: { role: 'assistant', content: 'Response' }
+                    }]
+                });
+
+            await model.message();
+
+            // Two consecutive user messages should be grouped into one by groupByRoles
+            const userMsgs = capturedBody.messages.filter(m => m.role === 'user');
+            expect(userMsgs).to.have.length(1);
+            expect(userMsgs[0].content).to.have.length(2);
+            expect(userMsgs[0].content[0].text).to.equal('Part 1');
+            expect(userMsgs[0].content[1].text).to.equal('Part 2');
+        });
+    });
+});

package/test/json.test.js

@@ -181,6 +181,163 @@ describe('JSON Schema and Structured Output Tests', () => {
         });
     });
 
+    describe('Enhanced Descriptor Descriptions', () => {
+        it('should support required: false (not in required + nullable)', () => {
+            const example = { name: 'Alice', nickname: 'Ali' };
+            const descriptions = {
+                name: 'Full name',
+                nickname: { description: 'Optional nickname', required: false }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.required).to.deep.equal(['name']);
+            expect(schema.properties.nickname).to.deep.equal({
+                type: ['string', 'null'],
+                description: 'Optional nickname'
+            });
+            expect(schema.properties.name).to.deep.equal({
+                type: 'string',
+                description: 'Full name'
+            });
+        });
+
+        it('should support enum', () => {
+            const example = { status: 'active' };
+            const descriptions = {
+                status: { description: 'Account status', enum: ['active', 'inactive', 'banned'] }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.status).to.deep.equal({
+                type: 'string',
+                description: 'Account status',
+                enum: ['active', 'inactive', 'banned']
+            });
+            expect(schema.required).to.deep.equal(['status']);
+        });
+
+        it('should make type nullable when enum includes null', () => {
+            const example = { sex: 'm' };
+            const descriptions = {
+                sex: { description: 'Gender', enum: ['m', 'f', null] }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.sex).to.deep.equal({
+                type: ['string', 'null'],
+                description: 'Gender',
+                enum: ['m', 'f', null]
+            });
+        });
+
+        it('should support default value', () => {
+            const example = { theme: 'light' };
+            const descriptions = {
+                theme: { description: 'UI theme', default: 'light', enum: ['light', 'dark'] }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.theme).to.deep.equal({
+                type: 'string',
+                description: 'UI theme',
+                default: 'light',
+                enum: ['light', 'dark']
+            });
+        });
+
+        it('should mix string and descriptor descriptions', () => {
+            const example = { name: 'martin', age: 22, sex: 'm' };
+            const descriptions = {
+                name: { description: 'Name of the actor', required: false },
+                age: 'Age of the actor',
+                sex: { description: 'Gender', enum: ['m', 'f', null], default: 'm' }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.required).to.deep.equal(['age', 'sex']);
+            expect(schema.properties.name).to.deep.equal({
+                type: ['string', 'null'],
+                description: 'Name of the actor'
+            });
+            expect(schema.properties.age).to.deep.equal({
+                type: 'integer',
+                description: 'Age of the actor'
+            });
+            expect(schema.properties.sex).to.deep.equal({
+                type: ['string', 'null'],
+                description: 'Gender',
+                enum: ['m', 'f', null],
+                default: 'm'
+            });
+        });
+
+        it('should not apply descriptor as nested descriptions for objects', () => {
+            const example = { user: { name: 'Alice', age: 30 } };
+            const descriptions = {
+                user: { description: 'User details', required: false }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.required).to.deep.equal([]);
+            expect(schema.properties.user.description).to.equal('User details');
+            expect(schema.properties.user.properties.name).to.deep.equal({ type: 'string' });
+            expect(schema.properties.user.properties.age).to.deep.equal({ type: 'integer' });
+        });
+
+        it('should pass nested descriptions correctly for objects', () => {
+            const example = { user: { name: 'Alice', age: 30 } };
+            const descriptions = {
+                user: { name: 'User name', age: 'User age' }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.user.properties.name).to.deep.equal({
+                type: 'string',
+                description: 'User name'
+            });
+            expect(schema.properties.user.properties.age).to.deep.equal({
+                type: 'integer',
+                description: 'User age'
+            });
+        });
+
+        it('should handle array descriptions in array format', () => {
+            const example = {
+                countries: [{ name: 'France', capital: 'Paris' }]
+            };
+            const descriptions = {
+                countries: [{ name: 'Country name', capital: 'Capital city' }]
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.countries.type).to.equal('array');
+            expect(schema.properties.countries.items.properties.name.description).to.equal('Country name');
+            expect(schema.properties.countries.items.properties.capital.description).to.equal('Capital city');
+        });
+
+        it('should handle descriptor for array field itself', () => {
+            const example = { tags: ['admin'] };
+            const descriptions = {
+                tags: { description: 'User tags', required: false }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            expect(schema.properties.tags.description).to.equal('User tags');
+            expect(schema.required).to.deep.equal([]);
+        });
+
+        it('should not double-add null to type', () => {
+            const example = { status: 'active' };
+            const descriptions = {
+                status: { required: false, enum: ['active', null] }
+            };
+            const schema = generateJsonSchema(example, descriptions);
+
+            const nullCount = schema.properties.status.type.filter(t => t === 'null').length;
+            expect(nullCount).to.equal(1);
+        });
+    });
+
     describe('ModelMix JSON Output', () => {
         let model;
 
@@ -291,5 +448,33 @@ describe('JSON Schema and Structured Output Tests', () => {
                 expect(error.message).to.include('JSON');
             }
         });
+
+        it('should auto-wrap top-level array and unwrap on return', async () => {
+            model.gpt41().addText('List 3 countries');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: JSON.stringify({
+                                out: [
+                                    { name: 'France' },
+                                    { name: 'Germany' },
+                                    { name: 'Spain' }
+                                ]
+                            })
+                        }
+                    }]
+                });
+
+            const result = await model.json([{ name: 'France' }]);
+
+            expect(result).to.be.an('array');
+            expect(result).to.have.length(3);
+            expect(result[0]).to.have.property('name', 'France');
+            expect(result[2]).to.have.property('name', 'Spain');
+        });
     });
 });