modelmix 5.0.3 → 5.0.4

package/README.md

@@ -982,6 +982,18 @@ new ModelMix(args = { options: {}, config: {} })
   - `toolCalls`: Array of tool calls made by the model (if any)
   - `tokens`: Normalized token counts (`input`, `output`, `thinking`, `total`, `cached`, `cacheWrite`, `cacheWrite5m`, `cacheWrite1h`, `uncachedInput`, `cacheHitRate`), cache economics (`cacheSavings`, `cacheWritePremium`, `breakEvenHits`), plus `cost`, `costBreakdown` (USD), and `speed` (output tokens/sec)
   - `response`: The raw API response
+- `ModerationMix` owns moderation-only provider chains. Use `openai()` to attach OpenAI's current `omni-moderation-latest`; `raw()` exposes the results under `moderation` (`flagged`, `categories`, `category_scores`, and `category_applied_input_types`). It uses `/v1/moderations`, rejects generative providers, does not generate text, and does not support streaming. Future moderation providers can be appended as fallbacks.
+  ```javascript
+  const { ModerationMix } = require('modelmix');
+
+  const { moderation: [profile] } = await ModerationMix.new()
+      .openai()
+      .addText(username)
+      .addImageFromUrl(avatarUrl)
+      .raw();
+
+  if (profile.flagged) throw new Error('Profile rejected by moderation');
+  ```
 - `stream(callback)`: Sends the message and streams the response, invoking the callback with each streamed part.
 - `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.

package/demo/moderation.js

@@ -0,0 +1,17 @@
+import { ModerationMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
+const username = 'player_name';
+const avatarUrl = 'https://example.com/avatar.png';
+
+const { moderation: [profileModeration] } = await ModerationMix.new()
+    .openai()
+    .addText(username)
+    .addImageFromUrl(avatarUrl)
+    .raw();
+
+console.log({
+    allowed: !profileModeration.flagged,
+    categories: profileModeration.categories,
+    scores: profileModeration.category_scores
+});

package/index.d.ts

@@ -190,9 +190,36 @@ export interface ModelMixResult {
   response?: unknown;
   assistantMessage?: ChatMessage;
   execution?: PluginExecutionMetadata;
+  moderation?: ModerationResult[];
   [key: string]: unknown;
 }
 
+export interface ModerationCategories {
+  harassment: boolean;
+  'harassment/threatening': boolean;
+  hate: boolean;
+  'hate/threatening': boolean;
+  illicit: boolean | null;
+  'illicit/violent': boolean | null;
+  'self-harm': boolean;
+  'self-harm/instructions': boolean;
+  'self-harm/intent': boolean;
+  sexual: boolean;
+  'sexual/minors': boolean;
+  violence: boolean;
+  'violence/graphic': boolean;
+}
+
+export type ModerationCategoryScores = Record<keyof ModerationCategories, number>;
+export type ModerationAppliedInputTypes = Record<keyof ModerationCategories, Array<'text' | 'image'>>;
+
+export interface ModerationResult {
+  flagged: boolean;
+  categories: ModerationCategories;
+  category_scores: ModerationCategoryScores;
+  category_applied_input_types: ModerationAppliedInputTypes;
+}
+
 export type ModelMixOutputMode = 'message' | 'json' | 'block' | 'raw' | 'stream';
 
 export interface PluginExecutionMetadata {
@@ -571,7 +598,14 @@ export declare class MixCustom {
 }
 
 export declare class MixOpenAI extends MixCustom {}
+export declare class MixModeration extends MixCustom {}
 export declare class MixOpenAIResponses extends MixOpenAI {}
+export declare class MixOpenAIModeration extends MixModeration {
+  static messagesToModerationInput(messages?: ChatMessage[]): Array<
+    | { type: 'text'; text: string }
+    | { type: 'image_url'; image_url: { url: string } }
+  >;
+}
 export declare class MixOpenAIWebSocket extends MixOpenAIResponses {}
 export declare class MixOpenRouter extends MixOpenAI {}
 export declare class MixKimi extends MixOpenAI {}
@@ -590,6 +624,18 @@ export declare class MixFireworks extends MixCustom {}
 export declare class MixNVIDIA extends MixCustom {}
 export declare class MixGoogle extends MixCustom {}
 
+export declare class ModerationMix extends ModelMix {
+  constructor(setup?: Omit<ModelMixSetup, 'mix'>);
+  static new(setup?: Omit<ModelMixSetup, 'mix'>): ModerationMix;
+  new(setup?: Omit<ModelMixSetup, 'mix'>): ModerationMix;
+  attach(key: string, provider: MixModeration): this;
+  openai(args?: ModelAttachArgs): this;
+  message(): Promise<never>;
+  json(): Promise<never>;
+  block(): Promise<never>;
+  stream(): Promise<never>;
+}
+
 /** Normalize unified effort to integer -1 or 0..100. */
 export function normalizeEffort(value: unknown): EffortValue;
 

package/index.js

@@ -2602,6 +2602,12 @@ class MixOpenAI extends MixCustom {
     }
 }
 
+class MixModeration extends MixCustom {
+    getOptionsTools() {
+        return {};
+    }
+}
+
 class MixOpenAIResponses extends MixOpenAI {
     async create({ config = {}, options = {} } = {}) {
 
@@ -2833,6 +2839,109 @@ class MixOpenAIResponses extends MixOpenAI {
     }
 }
 
+class MixOpenAIModeration extends MixModeration {
+    getDefaultConfig(customConfig) {
+        const apiKey = customConfig.apiKey || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OpenAI API key not found. Please provide it in config or set OPENAI_API_KEY environment variable.');
+        }
+
+        return super.getDefaultConfig({
+            url: 'https://api.openai.com/v1/moderations',
+            apiKey,
+            ...customConfig
+        });
+    }
+
+    async create({ config = {}, options = {} } = {}) {
+        if (options.stream) {
+            throw new Error('Stream is not supported for OpenAI moderation');
+        }
+
+        const input = MixOpenAIModeration.messagesToModerationInput(options.messages);
+        const response = await fetchJsonResponse(this.config.url, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ model: options.model, input })
+        });
+
+        return {
+            moderation: response.data.results,
+            tokens: ModelMix.normalizeTokenUsage(),
+            response: response.data
+        };
+    }
+
+    static messagesToModerationInput(messages = []) {
+        const input = [];
+
+        for (const message of messages) {
+            if (typeof message.content === 'string') {
+                input.push({ type: 'text', text: message.content });
+                continue;
+            }
+            if (!Array.isArray(message.content)) continue;
+
+            for (const content of message.content) {
+                if (content?.type === 'text') {
+                    input.push({ type: 'text', text: content.text });
+                } else if (content?.type === 'image') {
+                    const { media_type: mediaType, data } = content.source || {};
+                    if (!mediaType || !data) {
+                        throw new Error('OpenAI moderation images must be prepared as base64 data URLs');
+                    }
+                    input.push({
+                        type: 'image_url',
+                        image_url: { url: `data:${mediaType};base64,${data}` }
+                    });
+                }
+            }
+        }
+
+        return input;
+    }
+}
+
+class ModerationMix extends ModelMix {
+    static new(setup = {}) {
+        return new ModerationMix(setup);
+    }
+
+    new({ options = {}, config = {} } = {}) {
+        return new ModerationMix({
+            options: { ...this.options, ...options },
+            config: { ...this.config, ...config }
+        });
+    }
+
+    attach(key, provider) {
+        if (!(provider instanceof MixModeration)) {
+            throw new Error('ModerationMix only accepts moderation providers.');
+        }
+        return super.attach(key, provider);
+    }
+
+    openai({ options = {}, config = {} } = {}) {
+        return this.attach('omni-moderation-latest', new MixOpenAIModeration({ options, config }));
+    }
+
+    async message() {
+        throw new Error('ModerationMix does not generate messages. Use raw() and read result.moderation.');
+    }
+
+    async json() {
+        throw new Error('ModerationMix does not generate JSON. Use raw() and read result.moderation.');
+    }
+
+    async block() {
+        throw new Error('ModerationMix does not generate blocks. Use raw() and read result.moderation.');
+    }
+
+    async stream() {
+        throw new Error('ModerationMix does not support streaming. Use raw().');
+    }
+}
+
 class MixOpenAIWebSocket extends MixOpenAIResponses {
     getDefaultConfig(customConfig) {
         return super.getDefaultConfig({
@@ -4020,4 +4129,4 @@ class MixGoogle extends MixCustom {
     }
 }
 
-module.exports = { MixCustom, ModelMix, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };
+module.exports = { MixCustom, ModelMix, ModerationMix, MixModeration, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIModeration, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -77,7 +77,6 @@
     "test:tokens": "mocha test/tokens.test.js --timeout 10000 --require test/setup.js",
     "test:plugins": "mocha test/plugins.test.js --timeout 10000 --require test/setup.js",
     "test:rlm": "mocha plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js",
-    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js test/plugins.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
-  },
-  "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c"
-}
+    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js test/moderation.test.js test/plugins.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
+  }
+}

package/skills/modelmix/SKILL.md

@@ -137,6 +137,9 @@ ModelMix.new({ config: { effort: 80 } })
 ## Available Model Shorthands
 
 ### OpenAI
+
+Use `ModerationMix.new().openai()` with `.raw()` to classify text and images through OpenAI's Moderations endpoint. Read the results from `raw.moderation`. `ModerationMix` accepts moderation providers as ordered fallbacks, rejects generative providers, and does not generate text or support streaming.
+
 `gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
 
 ### Anthropic
@@ -610,7 +613,7 @@ const model = ModelMix.new({
 
 ## Available Provider Classes
 
-`MixOpenAI` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixLambda`
+`ModerationMix` `MixModeration` `MixOpenAI` `MixOpenAIResponses` `MixOpenAIModeration` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixLambda`
 
 ## Troubleshooting
 

package/test/moderation.test.js

@@ -0,0 +1,135 @@
+const { expect } = require('chai');
+const nock = require('nock');
+const { ModerationMix, MixModeration, MixOpenAIModeration } = require('../index.js');
+
+describe('OpenAI moderation', () => {
+    const moderationResult = {
+        flagged: true,
+        categories: { violence: true },
+        category_scores: { violence: 0.98 },
+        category_applied_input_types: { violence: ['text', 'image'] }
+    };
+
+    it('registers omni-moderation-latest with openai()', () => {
+        const model = ModerationMix.new().openai({ config: { apiKey: 'test-key' } });
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('omni-moderation-latest');
+        expect(model.models[0].provider).to.be.instanceOf(MixOpenAIModeration);
+        expect(model.models[0].provider.config.url).to.equal('https://api.openai.com/v1/moderations');
+    });
+
+    it('accepts an explicit API key without requiring the environment variable', () => {
+        const originalApiKey = process.env.OPENAI_API_KEY;
+        delete process.env.OPENAI_API_KEY;
+
+        try {
+            const model = ModerationMix.new().openai({ config: { apiKey: 'explicit-key' } });
+            expect(model.models[0].provider.config.apiKey).to.equal('explicit-key');
+        } finally {
+            if (originalApiKey === undefined) delete process.env.OPENAI_API_KEY;
+            else process.env.OPENAI_API_KEY = originalApiKey;
+        }
+    });
+
+    it('sends text and image input to the Moderations endpoint', async () => {
+        const api = nock('https://api.openai.com')
+            .post('/v1/moderations', body => {
+                expect(body).to.deep.equal({
+                    model: 'omni-moderation-latest',
+                    input: [
+                        { type: 'text', text: 'Check this' },
+                        {
+                            type: 'image_url',
+                            image_url: { url: 'data:image/png;base64,aW1hZ2U=' }
+                        }
+                    ]
+                });
+                return true;
+            })
+            .reply(200, {
+                id: 'modr-test',
+                model: 'omni-moderation-latest',
+                results: [moderationResult]
+            });
+
+        const result = await ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this')
+            .addImageFromUrl('data:image/png;base64,aW1hZ2U=')
+            .raw();
+
+        expect(result.moderation).to.deep.equal([moderationResult]);
+        api.done();
+    });
+
+    it('exposes the complete API response through raw()', async () => {
+        const response = {
+            id: 'modr-test',
+            model: 'omni-moderation-latest',
+            results: [moderationResult]
+        };
+        const api = nock('https://api.openai.com')
+            .post('/v1/moderations')
+            .reply(200, response);
+
+        const raw = await ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this')
+            .raw();
+
+        expect(raw.moderation).to.deep.equal(response.results);
+        expect(raw.response).to.deep.equal(response);
+        expect(raw.tokens).to.include({ input: 0, output: 0, total: 0, cost: 0 });
+        api.done();
+    });
+
+    it('rejects streaming because the Moderations endpoint does not support it', async () => {
+        const model = ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this');
+
+        try {
+            await model.stream(() => {});
+            throw new Error('Expected stream() to reject');
+        } catch (error) {
+            expect(error.message).to.equal('ModerationMix does not support streaming. Use raw().');
+        }
+    });
+
+    it('rejects generative providers from the moderation chain', () => {
+        const model = ModerationMix.new();
+
+        expect(() => model.gpt41nano()).to.throw(
+            'ModerationMix only accepts moderation providers.'
+        );
+    });
+
+    it('accepts additional moderation providers as fallbacks', () => {
+        class TestModeration extends MixModeration {}
+        const model = ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .attach('test-moderation', new TestModeration({ config: { apiKey: 'test-key' } }));
+
+        expect(model.models.map(({ key }) => key)).to.deep.equal([
+            'omni-moderation-latest',
+            'test-moderation'
+        ]);
+    });
+
+    for (const method of ['message', 'json', 'block']) {
+        it(`rejects ${method}() because moderation is not generative`, async () => {
+            const model = ModerationMix.new()
+                .openai({ config: { apiKey: 'test-key' } })
+                .addText('Check this');
+
+            try {
+                await model[method]();
+                throw new Error(`Expected ${method}() to reject`);
+            } catch (error) {
+                expect(error.message).to.include('ModerationMix does not generate');
+            }
+        });
+    }
+
+});