modelmix 5.0.2 → 5.0.4

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/demo/short.js

@@ -11,7 +11,7 @@ const setup = {
 const mmix = await ModelMix.new(setup)
     .sonnet46() // (main model) Anthropic claude-sonnet-4-6
     .gpt56luna() // (fallback 1) OpenAI gpt-5.6-luna
-    .gemini36flash({ config: { temperature: 0 } }) // (fallback 2) Google gemini-3.6-flash
+    .gemini37flash() // (fallback 2) Google gemini-3.7-flash
     .gpt41nano() // (fallback 3) OpenAI gpt-4.1-nano
     .grok46() // (fallback 4) Grok grok-4.6
     .addText("What's your name?");

package/effort.js

@@ -70,6 +70,7 @@ const MINIMAX_BANDS = [
 
 /** Exact model → supported Gemini thinkingLevel values */
 const GEMINI_MODEL_LEVELS = {
+    'gemini-3.7-flash': ['low', 'medium', 'high'],
     'gemini-3-pro-preview': ['low', 'high'],
     'gemini-3.1-pro-preview': ['low', 'medium', 'high'],
     'gemini-2.5-pro': ['low', 'medium', 'high'],
@@ -290,6 +291,7 @@ function mapAdaptiveEffort(providerFamily, modelKey) {
         return { thinking: { type: 'adaptive' } };
     }
     if (providerFamily === 'google') {
+        if (modelKey === 'gemini-3.7-flash') return null;
         // Gemini dynamic thinking: thinkingBudget -1 (2.5 official; accepted on 3.x as dynamic)
         return { thinkingConfig: { thinkingBudget: -1 } };
     }

package/index.d.ts

@@ -161,6 +161,8 @@ export interface TokenCostBreakdown {
 export interface TokenUsage {
   input: number;
   output: number;
+  /** Internal reasoning tokens billed at the output rate when reported separately. */
+  thinking: number;
   total: number;
   cached: number;
   cacheWrite: number;
@@ -187,9 +189,86 @@ export interface ModelMixResult {
   tokens?: TokenUsage;
   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 {
+  executionId: string;
+  parentExecutionId: string | null;
+  depth: number;
+}
+
+export type PluginInheritancePolicy =
+  | 'inherit'
+  | 'none'
+  | { include: string[] }
+  | { exclude: string[] };
+
+export interface ChildInvocation {
+  system?: string;
+  systemFile?: string;
+  assign?: Record<string, unknown>;
+  messages: ChatMessage[];
+  tools?: ToolWithCallback[];
+  options?: ModelMixOptions;
+  config?: ModelMixConfig;
+  mix?: ModelMixMixFlags;
+  model?: ModelMix;
+  plugins?: PluginInheritancePolicy;
+  history?: false;
+  outputMode?: ModelMixOutputMode;
+}
+
+export interface PluginExecutionContext {
+  request: {
+    system: string;
+    messages: ChatMessage[];
+    options: ModelMixOptions;
+    config: ModelMixConfig;
+    outputMode: ModelMixOutputMode;
+  };
+  execution: Readonly<PluginExecutionMetadata>;
+  invoke(input: ChildInvocation): Promise<ModelMixResult>;
+}
+
+export interface ModelMixPlugin {
+  name: string;
+  execute(
+    context: PluginExecutionContext,
+    next: () => Promise<ModelMixResult>
+  ): Promise<ModelMixResult>;
+}
+
 export interface StreamChunk {
   response: unknown;
   message: string;
@@ -263,6 +342,7 @@ export interface ProviderConstructorArgs {
 export interface CreateArgs {
   config?: ModelMixConfig;
   options?: ModelMixOptions;
+  outputMode?: ModelMixOutputMode;
 }
 
 export type ProviderFamily =
@@ -279,6 +359,7 @@ export declare class ModelMix {
   tools: Record<string, ToolDefinition[]>;
   toolClient: Record<string, unknown>;
   mcp: Record<string, unknown>;
+  plugins: ModelMixPlugin[];
   options: ModelMixOptions;
   config: ModelMixConfig;
   mix: ModelMixMixFlags;
@@ -288,6 +369,7 @@ export declare class ModelMix {
   constructor(setup?: ModelMixSetup);
 
   static new(setup?: ModelMixSetup): ModelMix;
+  use(plugin: ModelMixPlugin): this;
   static formatJSON(obj: unknown): string;
   static formatMessage(message: unknown): unknown;
   static truncate(str: string, maxLen?: number): string;
@@ -296,6 +378,7 @@ export declare class ModelMix {
     tokens: {
       input: number;
       output: number;
+      thinking?: number;
       total?: number;
       cached?: number;
       cacheWrite?: number;
@@ -308,6 +391,7 @@ export declare class ModelMix {
     tokens: {
       input: number;
       output: number;
+      thinking?: number;
       total?: number;
       cached?: number;
       cacheWrite?: number;
@@ -320,6 +404,7 @@ export declare class ModelMix {
     tokens: {
       input: number;
       output: number;
+      thinking?: number;
       total?: number;
       cached?: number;
       cacheWrite?: number;
@@ -330,6 +415,7 @@ export declare class ModelMix {
   static normalizeTokenUsage(tokens?: {
     input?: number;
     output?: number;
+    thinking?: number;
     total?: number;
     cached?: number;
     cacheWrite?: number;
@@ -395,6 +481,7 @@ export declare class ModelMix {
   gemini31pro(args?: ModelAttachArgs): this;
   gemini3pro(args?: ModelAttachArgs): this;
   gemini3flash(args?: ModelAttachArgs): this;
+  gemini37flash(args?: ModelAttachArgs): this;
   gemini36flash(args?: ModelAttachArgs): this;
   gemini35flash(args?: ModelAttachArgs): this;
   gemini35flashLite(args?: ModelAttachArgs): this;
@@ -455,7 +542,7 @@ export declare class ModelMix {
 
   assignKeyFromFile(key: string, filePath: string): this;
   groupByRoles(messages: ChatMessage[]): ChatMessage[];
-  prepareMessages(): Promise<void>;
+  prepareMessages(): Promise<ChatMessage[]>;
   readFile(filePath: string, options?: { encoding?: BufferEncoding | null }): string | Buffer;
   execute(args?: CreateArgs): Promise<ModelMixResult>;
   processToolCalls(toolCalls: ToolCall[]): Promise<
@@ -511,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 {}
@@ -530,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;