modelmix 4.5.16 → 4.5.20

package/README.md

@@ -343,7 +343,7 @@ const result = await model.json(
 
 ### Enhanced descriptors
 
-Descriptions support **descriptor objects** with `description`, `required`, `enum`, and `default`:
+Descriptions support **descriptor objects** with `description`, `required`, `enum`, `default`, and `nullable`:
 
 ```javascript
 const result = await model.json(
@@ -359,11 +359,97 @@ const result = await model.json(
 | 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 |
+| `required` | `boolean` | `true` | If `false`, field is removed from `required` and its type becomes nullable |
+| `enum` | `array` | — | Restricts the field to specific values. Including `null` in the array auto-makes the type nullable |
+| `default` | `any` | — | Default value hint for the model |
+| `nullable` | `boolean` | `false` | If `true`, makes the type nullable without removing from `required` |
 
-You can mix strings and descriptor objects freely in the same descriptions parameter.
+You can mix plain strings and descriptor objects freely in the same descriptions parameter:
+
+```javascript
+const result = await model.json(
+    { name: 'Martin', age: 22, status: 'active' },
+    {
+        name: 'Full name',                                            // plain string
+        age: { description: 'Age in years', required: false },        // optional field
+        status: { description: 'Account status', enum: ['active', 'inactive', 'banned'], default: 'active' }
+    }
+);
+```
+
+### Nested object descriptions
+
+Pass a nested object as the description value to describe fields inside a nested object:
+
+```javascript
+const result = await model.json(
+    { user: { name: 'Alice', age: 30 } },
+    {
+        user: { name: 'Full name of the user', age: 'Age in years' }
+    }
+);
+```
+
+To describe the object field itself (e.g. mark it optional) **and** its nested fields, use the `description` / `required` descriptor for the parent key, which applies only to the parent, while still passing nested descriptions as its own separate key:
+
+```javascript
+// Mark the parent optional but don't describe its children
+const result = await model.json(
+    { user: { name: 'Alice', age: 30 } },
+    { user: { description: 'User details', required: false } }
+);
+```
+
+### Array item descriptions
+
+Pass descriptions for the items of an array by wrapping the descriptions in an array:
+
+```javascript
+const result = await model.json(
+    { countries: [{ name: 'France', capital: 'Paris' }] },
+    { countries: [{ name: 'Country name', capital: 'Capital city in uppercase' }] }
+);
+```
+
+To mark the array field itself optional while keeping item descriptions, use a descriptor on the key:
+
+```javascript
+const result = await model.json(
+    { tags: ['admin'] },
+    { tags: { description: 'List of user roles', required: false } }
+);
+```
+
+### Automatic type and format detection
+
+`generateJsonSchema` infers types and formats automatically from the example values:
+
+| Example value | Inferred schema |
+| --- | --- |
+| `42` | `{ type: 'integer' }` |
+| `19.99` | `{ type: 'number' }` |
+| `true` / `false` | `{ type: 'boolean' }` |
+| `null` | `{ type: 'null' }` |
+| `'hello'` | `{ type: 'string' }` |
+| `'user@example.com'` | `{ type: 'string', format: 'email' }` |
+| `'1990-01-01'` | `{ type: 'string', format: 'date', description: 'Date in format YYYY-MM-DD' }` |
+| `'14:30'` | `{ type: 'string', format: 'time', description: 'Time in format HH:MM' }` |
+| `'09:15:45'` | `{ type: 'string', format: 'time', description: 'Time in format HH:MM:SS' }` |
+| `[{ … }]` | `{ type: 'array', items: { … } }` — schema inferred from the first element |
+| `{ … }` | `{ type: 'object', properties: { … }, required: […] }` |
+
+When a field carries an `enum` that includes `null`, or has `required: false` or `nullable: true`, its type is widened to `[type, 'null']`. For example:
+
+```javascript
+// enum with null → type becomes ['string', 'null']
+{ description: 'Gender', enum: ['m', 'f', null] }
+
+// required: false → removes from required[] and type becomes ['string', 'null']
+{ description: 'Nickname', required: false }
+
+// nullable: true → type becomes ['string', 'null'] but stays in required[]
+{ description: 'Middle name', nullable: true }
+```
 
 ### Array auto-wrap
 

package/index.js

@@ -37,6 +37,8 @@ const MODEL_PRICING = {
     // OpenAI
     'gpt-realtime-mini': [0.60, 2.40],
     'gpt-realtime': [4.00, 16.00],
+    'gpt-5.5-pro': [30.00, 180.00],
+    'gpt-5.5': [5.00, 30.00],
     'gpt-5.4': [2.50, 15.00],
     'gpt-5.4-pro': [30, 180.00],
     'gpt-5.4-mini': [0.75, 4.50],
@@ -319,7 +321,13 @@ class ModelMix {
     }        
     gpt54pro({ options = {}, config = {} } = {}) {
         return this.attach('gpt-5.4-pro', new MixOpenAIResponses({ options, config }));
-    }          
+    }
+    gpt55({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-5.5', new MixOpenAIResponses({ options, config }));
+    }
+    gpt55pro({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-5.5-pro', new MixOpenAIResponses({ options, config }));
+    }
     gptRealtime({ options = {}, config = {} } = {}) {
         return this.attach('gpt-realtime', new MixOpenAIWebSocket({ options, config }));
     }
@@ -522,7 +530,21 @@ class ModelMix {
         if (mix.minimax) return this.attach('MiniMax-M2.7', new MixMiniMax({ options, config }));
         if (mix.together) return this.attach('MiniMaxAI/MiniMax-M2.7', new MixTogether({ options, config }));
         return this;
-    }  
+    }
+
+    mimo25({ options = {}, config = {}, mix = { openrouter: true } } = {}) {
+        mix = { ...this.mix, ...mix };
+        if (mix.openrouter) this.attach('xiaomi/mimo-v2.5', new MixOpenRouter({ options, config }));
+        if (mix.mimo) this.attach('mimo-v2.5', new MixMiMo({ options, config }));
+        return this;
+    }
+
+    mimo25pro({ options = {}, config = {}, mix = { openrouter: true } } = {}) {
+        mix = { ...this.mix, ...mix };
+        if (mix.openrouter) this.attach('xiaomi/mimo-v2.5-pro', new MixOpenRouter({ options, config }));
+        if (mix.mimo) this.attach('mimo-v2.5-pro', new MixMiMo({ options, config }));
+        return this;
+    }
 
     deepseekV4Pro({ options = {}, config = {}, mix = { fireworks: true } } = {}) {
         mix = { ...this.mix, ...mix };
@@ -2308,6 +2330,29 @@ class MixMiniMax extends MixOpenAI {
     }
 }
 
+class MixMiMo extends MixOpenAI {
+    getDefaultConfig(customConfig) {
+        if (!process.env.MIMO_API_KEY) {
+            throw new Error('MiMo API key not found. Please provide it in config or set MIMO_API_KEY environment variable.');
+        }
+
+        return MixCustom.prototype.getDefaultConfig.call(this, {
+            url: 'https://api.xiaomimimo.com/v1/chat/completions',
+            apiKey: process.env.MIMO_API_KEY,
+            ...customConfig
+        });
+    }
+
+    getDefaultHeaders(customHeaders) {
+        return {
+            'accept': 'application/json',
+            'content-type': 'application/json',
+            'api-key': this.config.apiKey,
+            ...customHeaders
+        };
+    }
+}
+
 class MixPerplexity extends MixCustom {
     getDefaultConfig(customConfig) {
 
@@ -2846,4 +2891,4 @@ class MixGoogle extends MixCustom {
     }
 }
 
-module.exports = { MixCustom, ModelMix, MixAnthropic, MixMiniMax, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA };
+module.exports = { MixCustom, ModelMix, MixAnthropic, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.5.16",
+  "version": "4.5.20",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -32,7 +32,7 @@
     "lmstudio",
     "deepseek",
     "oss",
-    "k2",
+    "k26",
     "reasoning",
     "minimax",
     "thinking",

package/skills/modelmix/SKILL.md

@@ -176,7 +176,53 @@ const result = await model.json(
 );
 ```
 
-Descriptor properties: `description` (string), `required` (boolean, default true — if false, field becomes nullable), `enum` (array — if includes null, type auto-becomes nullable), `default` (any).
+Descriptor properties:
+
+| Property | Type | Notes |
+| --- | --- | --- |
+| `description` | string | Field description for the model |
+| `required` | boolean (default `true`) | `false` → removes from `required[]` **and** makes type nullable |
+| `enum` | array | Restricts allowed values. Including `null` auto-makes the type nullable |
+| `default` | any | Default value hint |
+| `nullable` | boolean (default `false`) | `true` → makes type nullable but keeps field in `required[]` |
+
+#### Nested object descriptions
+
+Pass a plain object as the description value to annotate fields inside a nested object:
+
+```javascript
+model.json(
+    { user: { name: 'Alice', age: 30 } },
+    { user: { name: 'Full name', age: 'Age in years' } }
+);
+```
+
+To mark the object itself as optional, use a descriptor (only `description`/`required`/`nullable` keys) — it applies to the parent, not the children:
+
+```javascript
+model.json(
+    { user: { name: 'Alice', age: 30 } },
+    { user: { description: 'User details', required: false } }
+);
+```
+
+#### Array item descriptions
+
+Wrap descriptions in an array to annotate items of an array field:
+
+```javascript
+model.json(
+    { countries: [{ name: 'France', capital: 'Paris' }] },
+    { countries: [{ name: 'Country name', capital: 'Capital in uppercase' }] }
+);
+```
+
+#### Automatic type and format detection
+
+Schema types are inferred from example values: `integer` (whole numbers), `number` (floats), `boolean`, `null`, `string`, and special formats:
+- `'user@example.com'` → `{ type: 'string', format: 'email' }`
+- `'1990-01-01'` → `{ type: 'string', format: 'date' }`
+- `'14:30'` / `'09:15:45'` → `{ type: 'string', format: 'time' }`
 
 #### Array auto-wrap
 
@@ -390,7 +436,7 @@ const model = ModelMix.new({
 - 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 — tool call/response pairs consume history slots.
-- Use `.json()` for structured output instead of parsing text manually. Use descriptor objects `{ description, required, enum, default }` for richer schema control.
+- Use `.json()` for structured output instead of parsing text manually. Use descriptor objects `{ description, required, enum, default, nullable }` 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.

package/test/tokens.test.js

@@ -1,5 +1,5 @@
 import { expect } from 'chai';
-import { ModelMix, MixAnthropic, MixCustom, MixGoogle, MixOpenAIResponses } from '../index.js';
+import { ModelMix, MixAnthropic, MixCustom, MixGoogle, MixMiMo, MixOpenAIResponses, MixOpenRouter } from '../index.js';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -76,6 +76,74 @@ describe('Token Usage Tracking', () => {
         expect(request.prompt_cache_retention).to.equal('24h');
     });
 
+    it('should register GPT-5.5 shortcuts with OpenAI Responses provider', function () {
+        const model = ModelMix.new()
+            .gpt55()
+            .gpt55pro();
+
+        expect(model.models).to.have.length(2);
+        expect(model.models[0].key).to.equal('gpt-5.5');
+        expect(model.models[1].key).to.equal('gpt-5.5-pro');
+        expect(model.models[0].provider).to.be.instanceOf(MixOpenAIResponses);
+        expect(model.models[1].provider).to.be.instanceOf(MixOpenAIResponses);
+    });
+
+    it('should register MiMo shortcuts with native and OpenRouter providers', function () {
+        const originalMimoApiKey = process.env.MIMO_API_KEY;
+        const originalOpenRouterApiKey = process.env.OPENROUTER_API_KEY;
+
+        process.env.MIMO_API_KEY = 'test-mimo-key';
+        process.env.OPENROUTER_API_KEY = 'test-openrouter-key';
+
+        try {
+            const model = ModelMix.new()
+                .mimo25()
+                .mimo25pro({ mix: { mimo: true, openrouter: true } });
+
+            expect(model.models).to.have.length(3);
+            expect(model.models[0].key).to.equal('xiaomi/mimo-v2.5');
+            expect(model.models[1].key).to.equal('mimo-v2.5-pro');
+            expect(model.models[2].key).to.equal('xiaomi/mimo-v2.5-pro');
+
+            expect(model.models[0].provider).to.be.instanceOf(MixOpenRouter);
+            expect(model.models[1].provider).to.be.instanceOf(MixMiMo);
+            expect(model.models[2].provider).to.be.instanceOf(MixOpenRouter);
+        } finally {
+            if (originalMimoApiKey === undefined) delete process.env.MIMO_API_KEY;
+            else process.env.MIMO_API_KEY = originalMimoApiKey;
+
+            if (originalOpenRouterApiKey === undefined) delete process.env.OPENROUTER_API_KEY;
+            else process.env.OPENROUTER_API_KEY = originalOpenRouterApiKey;
+        }
+    });
+
+    it('should use api-key header for MiMo provider', function () {
+        const originalMimoApiKey = process.env.MIMO_API_KEY;
+        process.env.MIMO_API_KEY = 'test-mimo-key';
+
+        try {
+            const provider = new MixMiMo();
+            expect(provider.headers['api-key']).to.equal('test-mimo-key');
+            expect(provider.headers.authorization).to.equal(undefined);
+            expect(provider.config.url).to.equal('https://api.xiaomimimo.com/v1/chat/completions');
+        } finally {
+            if (originalMimoApiKey === undefined) delete process.env.MIMO_API_KEY;
+            else process.env.MIMO_API_KEY = originalMimoApiKey;
+        }
+    });
+
+    it('should throw a clear error when MIMO_API_KEY is missing', function () {
+        const originalMimoApiKey = process.env.MIMO_API_KEY;
+        delete process.env.MIMO_API_KEY;
+
+        try {
+            expect(() => new MixMiMo()).to.throw('MIMO_API_KEY');
+        } finally {
+            if (originalMimoApiKey === undefined) delete process.env.MIMO_API_KEY;
+            else process.env.MIMO_API_KEY = originalMimoApiKey;
+        }
+    });
+
     it('should track tokens in OpenAI response', async function () {
         this.timeout(30000);