clasen/modelmix

ModelMix Library Skill

Overview

ModelMix is a Node.js library that provides a unified fluent API to interact with multiple AI LLM providers. It handles automatic fallback between models, round-robin load balancing, structured JSON output, streaming, MCP tool integration, rate limiting, and token tracking.

Use this skill when:

• Integrating one or more AI models into a Node.js project
• Chaining models with automatic fallback
• Extracting structured JSON from LLMs
• Adding MCP tools or custom tools to models
• Working with templates and file-based prompts

Do NOT use this skill for:

• Python or non-Node.js projects
• Direct HTTP calls to LLM APIs (use ModelMix instead)

Installation

npm install modelmix

Core Concepts

Import

import { ModelMix } from 'modelmix';

Creating an Instance

// Static factory (preferred)
const model = ModelMix.new();

// With global options
const model = ModelMix.new({
    options: { max_tokens: 4096, temperature: 0.7 },
    config: {
        system: "You are a helpful assistant.",
        max_history: 5,
        debug: 0,           // 0=silent, 1=minimal, 2=summary, 3=full
        roundRobin: false    // false=fallback, true=rotate models
    }
});

Attaching Models (Fluent Chain)

Chain shorthand methods to attach providers. First model is primary; others are fallbacks:

const model = ModelMix.new()
    .sonnet45()        // primary
    .gpt5mini()        // fallback 1
    .gemini3flash()    // fallback 2
    .addText("Hello!")

If sonnet45 fails, it automatically tries gpt5mini, then gemini3flash.

Available Model Shorthands

• OpenAI: gpt52 gpt51 gpt5 gpt5mini gpt5nano gpt41 gpt41mini gpt41nano
• Anthropic: opus46 opus45 sonnet45 sonnet4 haiku45 haiku35 (thinking variants: add think suffix)
• Google: gemini3pro gemini3flash gemini25pro gemini25flash
• Grok: grok4 grok41 (thinking variant available)
• Perplexity: sonar sonarPro
• Groq: scout maverick
• Together: qwen3 kimiK2
• Multi-provider: deepseekR1 gptOss
• MiniMax: minimaxM21
• Fireworks: deepseekV32 GLM47

Each method is called as mix.methodName() and accepts optional { options, config } to override per-model settings.

Common Tasks

Get a text response

const answer = await ModelMix.new()
    .gpt5mini()
    .addText("What is the capital of France?")
    .message();

Get structured JSON

const result = await ModelMix.new()
    .gpt5mini()
    .addText("Name and capital of 3 South American countries.")
    .json(
        { countries: [{ name: "", capital: "" }] },                    // schema example
        { countries: [{ name: "country name", capital: "in uppercase" }] }, // descriptions
        { addNote: true }                                               // options
    );
// result.countries → [{ name: "Brazil", capital: "BRASILIA" }, ...]

json() signature: json(schemaExample, schemaDescription?, { addSchema, addExample, addNote }?)

Stream a response

await ModelMix.new()
    .gpt5mini()
    .addText("Tell me a story.")
    .stream(({ delta, message }) => {
        process.stdout.write(delta);
    });

Get raw response (tokens, thinking, tool calls)

const raw = await ModelMix.new()
    .sonnet45think()
    .addText("Solve this step by step: 2+2*3")
    .raw();
// raw.message, raw.think, raw.tokens, raw.toolCalls, raw.response

Access full response after message() or json() with lastRaw

After calling message(), json(), block(), or stream(), use lastRaw to access the complete response (tokens, thinking, tool calls, etc.). It has the same structure as raw().

const model = ModelMix.new().gpt5mini().addText("Hello!");
const text = await model.message();
console.log(model.lastRaw.tokens);
// { input: 122, output: 86, total: 541, cost: 0.000319 }
console.log(model.lastRaw.think);    // reasoning content (if available)
console.log(model.lastRaw.response); // raw API response

Add images

const model = ModelMix.new().sonnet45();
model.addImage('./photo.jpg');                         // from file
model.addImageFromUrl('https://example.com/img.png');  // from URL
model.addText('Describe this image.');
const description = await model.message();

Use templates with placeholders

const model = ModelMix.new().gpt5mini();
model.setSystemFromFile('./prompts/system.md');
model.addTextFromFile('./prompts/task.md');
model.replace({
    '{role}': 'data analyst',
    '{language}': 'Spanish'
});
model.replaceKeyFromFile('{code}', './src/utils.js');
console.log(await model.message());

Round-robin load balancing

const pool = ModelMix.new({ config: { roundRobin: true } })
    .gpt5mini()
    .sonnet45()
    .gemini3flash();

// Each call rotates to the next model
const r1 = await pool.new().addText("Request 1").message();
const r2 = await pool.new().addText("Request 2").message();

MCP integration (external tools)

const model = ModelMix.new({ config: { max_history: 10 } }).gpt5nano();
model.setSystem('You are an assistant. Today is ' + new Date().toISOString());
await model.addMCP('@modelcontextprotocol/server-brave-search');
model.addText('Use Internet: What is the latest news about AI?');
console.log(await model.message());

Requires BRAVE_API_KEY in .env for Brave Search MCP.

Custom local tools (addTool)

const model = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();

model.addTool({
    name: "get_weather",
    description: "Get weather for a city",
    inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"]
    }
}, async ({ city }) => {
    return `The weather in ${city} is sunny, 25C`;
});

model.addText("What's the weather in Tokyo?");
console.log(await model.message());

Rate limiting (Bottleneck)

const model = ModelMix.new({
    config: {
        bottleneck: {
            maxConcurrent: 4,
            minTime: 1000
        }
    }
}).gpt5mini();

Debug mode

const model = ModelMix.new({
    config: { debug: 2 }  // 0=silent, 1=minimal, 2=summary, 3=full
}).gpt5mini();

For full debug output, also set the env: DEBUG=ModelMix* node script.js

Use free-tier models

// These use providers with free quotas (OpenRouter, Groq, Cerebras)
const model = ModelMix.new()
    .gptOss()
    .kimiK2()
    .deepseekR1()
    .hermes3()
    .addText("What is the capital of France?");
console.log(await model.message());

Conversation history

const chat = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();
chat.addText("My name is Martin.");
await chat.message();
chat.addText("What's my name?");
const reply = await chat.message();  // "Martin"

Agent Usage Rules

• Always check package.json for modelmix before running npm install.
• Use ModelMix.new() static factory to create instances (not new ModelMix()).
• 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.
• Use .json() for structured output instead of parsing text manually.
• 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.
• The library uses CommonJS internally (require) but supports ESM import via { ModelMix }.
• Available provider Mix classes for custom setups: MixOpenAI, MixAnthropic, MixGoogle, MixPerplexity, MixGroq, MixTogether, MixGrok, MixOpenRouter, MixOllama, MixLMStudio, MixCustom, MixCerebras, MixFireworks, MixMiniMax.

API Quick Reference

| Method | Returns | Description | | --- | --- | --- | | .addText(text) | this | Add user message | | .addTextFromFile(path) | this | Add user message from file | | .setSystem(text) | this | Set system prompt | | .setSystemFromFile(path) | this | Set system prompt from file | | .addImage(path) | this | Add image from file | | .addImageFromUrl(url) | this | Add image from URL or data URI | | .replace({}) | this | Set placeholder replacements | | .replaceKeyFromFile(key, path) | this | Replace placeholder with file content | | .message() | Promise<string> | Get text response | | .json(example, desc?, opts?) | Promise<object> | Get structured JSON | | .raw() | Promise<{message, think, toolCalls, tokens, response}> | Full response | | .lastRaw | object \| null | Full response from last message()/json()/block()/stream() call | | .stream(callback) | Promise | Stream response | | .block() | Promise<string> | Extract code block from response | | .addMCP(package) | Promise | Add MCP server tools | | .addTool(def, callback) | this | Register custom local tool | | .addTools([{tool, callback}]) | this | Register multiple tools | | .removeTool(name) | this | Remove a tool | | .listTools() | {local, mcp} | List registered tools | | .new() | ModelMix | Clone instance sharing models | | .attach(key, provider) | this | Attach custom provider |

References

• GitHub Repository