modelmix 4.5.16 → 4.5.18

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 }));
     }

package/package.json

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

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

@@ -76,6 +76,18 @@ 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 track tokens in OpenAI response', async function () {
         this.timeout(30000);