modelmix 3.1.8 → 3.3.2

package/MODELS.md

@@ -0,0 +1,249 @@
+# ModelMix Provider Documentation
+
+This document describes how each model provider in ModelMix handles data input and output formats.
+
+## Common Structure
+
+All providers inherit from `MixCustom` base class which provides common functionality for:
+- API key management
+- Error handling
+- Basic request/response processing
+- Stream handling
+
+## Provider-Specific Details
+
+### OpenAI (MixOpenAI)
+- **Base URL**: `https://api.openai.com/v1/chat/completions`
+- **Input Format**:
+  ```json
+  {
+    "messages": [
+      {
+        "role": "system",
+        "content": "system message"
+      },
+      {
+        "role": "user",
+        "content": [
+          {
+            "type": "text",
+            "text": "message text"
+          },
+          {
+            "type": "image_url",
+            "image_url": {
+              "url": "data:image/jpeg;base64,..."
+            }
+          }
+        ]
+      }
+    ],
+    "model": "model-name",
+    "temperature": 1,
+    "max_tokens": 5000,
+    "top_p": 1
+  }
+  ```
+- **Output Format**:
+  ```json
+  {
+    "choices": [
+      {
+        "message": {
+          "content": "response text"
+        }
+      }
+    ]
+  }
+  ```
+- **Special Notes**: 
+  - Removes `max_tokens` and `temperature` for o1/o3 models
+  - Converts image messages to base64 data URLs
+
+### Anthropic (MixAnthropic)
+- **Base URL**: `https://api.anthropic.com/v1/messages`
+- **Input Format**:
+  ```json
+  {
+    "system": "system message",
+    "messages": [
+      {
+        "role": "user",
+        "content": [
+          {
+            "type": "text",
+            "text": "message text"
+          },
+          {
+            "type": "image",
+            "source": {
+              "type": "base64",
+              "media_type": "image/jpeg",
+              "data": "base64data"
+            }
+          }
+        ]
+      }
+    ],
+    "model": "claude-3-sonnet-20240229",
+    "temperature": 1,
+    "top_p": 1
+  }
+  ```
+- **Output Format**:
+  ```json
+  {
+    "content": [
+      {
+        "text": "response text"
+      }
+    ]
+  }
+  ```
+- **Special Notes**:
+  - Removes `top_p` when thinking mode is enabled
+  - Uses `x-api-key` header instead of `authorization`
+  - Requires `anthropic-version` header
+
+### Perplexity (MixPerplexity)
+- **Base URL**: `https://api.perplexity.ai/chat/completions`
+- **Input Format**: Same as OpenAI
+- **Output Format**: Same as OpenAI
+- **Special Notes**: Uses standard OpenAI-compatible format
+
+### Grok (MixGrok)
+- **Base URL**: `https://api.x.ai/v1/chat/completions`
+- **Input Format**: Same as OpenAI
+- **Output Format**: Same as OpenAI
+- **Special Notes**: Inherits from MixOpenAI
+
+### Together (MixTogether)
+- **Base URL**: `https://api.together.xyz/v1/chat/completions`
+- **Input Format**:
+  ```json
+  {
+    "messages": [
+      {
+        "role": "system",
+        "content": "system message"
+      },
+      {
+        "role": "user",
+        "content": "message text"
+      }
+    ],
+    "model": "model-name",
+    "stop": ["<|eot_id|>", "<|eom_id|>"]
+  }
+  ```
+- **Output Format**: Same as OpenAI
+- **Special Notes**: 
+  - Flattens content arrays to strings
+  - Adds default stop tokens
+
+### Google (MixGoogle)
+- **Base URL**: `https://generativelanguage.googleapis.com/v1beta/models`
+- **Input Format**:
+  ```json
+  {
+    "contents": [
+      {
+        "role": "user",
+        "parts": [
+          {
+            "text": "message text"
+          },
+          {
+            "inline_data": {
+              "mime_type": "image/jpeg",
+              "data": "base64data"
+            }
+          }
+        ]
+      }
+    ],
+    "generationConfig": {
+      "responseMimeType": "text/plain"
+    }
+  }
+  ```
+- **Output Format**:
+  ```json
+  {
+    "candidates": [
+      {
+        "content": {
+          "parts": [
+            {
+              "text": "response text"
+            }
+          ]
+        }
+      }
+    ]
+  }
+  ```
+- **Special Notes**:
+  - Uses different role names (`model` instead of `assistant`)
+  - Requires model ID in URL path
+  - Doesn't support streaming
+  - Available Gemini models:
+    - `gemini-2.5-flash-preview-04-17`
+    - `gemini-2.5-pro-exp-03-25`
+    - `gemini-2.5-pro-preview-05-06`
+  - Each model has different capabilities:
+    - Flash: Fastest response time, best for simple tasks
+    - Pro: More capable, better for complex tasks
+    - Pro Exp: Experimental version with latest features
+
+### Cerebras (MixCerebras)
+- **Base URL**: `https://api.cerebras.ai/v1/chat/completions`
+- **Input Format**: Same as Together
+- **Output Format**: Same as OpenAI
+- **Special Notes**: Uses Together's message conversion
+
+### Ollama (MixOllama)
+- **Base URL**: `http://localhost:11434/api/chat`
+- **Input Format**:
+  ```json
+  {
+    "messages": [
+      {
+        "role": "system",
+        "content": "system message",
+        "images": []
+      },
+      {
+        "role": "user",
+        "content": "message text",
+        "images": ["base64data"]
+      }
+    ]
+  }
+  ```
+- **Output Format**:
+  ```json
+  {
+    "message": {
+      "content": "response text"
+    }
+  }
+  ```
+- **Special Notes**: 
+  - Local deployment only
+  - Handles images in separate array
+  - No API key required
+
+### LM Studio (MixLMStudio)
+- **Base URL**: `http://localhost:1234/v1/chat/completions`
+- **Input Format**: Same as OpenAI
+- **Output Format**: Same as OpenAI
+- **Special Notes**: 
+  - Local deployment only
+  - No API key required
+
+### Groq (MixGroq)
+- **Base URL**: `https://api.groq.com/openai/v1/chat/completions`
+- **Input Format**: Same as OpenAI
+- **Output Format**: Same as OpenAI
+- **Special Notes**: Uses OpenAI-compatible format 

package/README.md

@@ -2,13 +2,16 @@
 
 **ModelMix** is a versatile module that enables seamless integration of various language models from different providers through a unified interface. With ModelMix, you can effortlessly manage and utilize multiple AI models while controlling request rates to avoid provider restrictions.
 
+Are you one of those developers who wants to apply language models to everything? Do you need a reliable fallback system to ensure your application never fails? ModelMix is the answer! It allows you to chain multiple models together, automatically falling back to the next model if one fails, ensuring your application always gets a response.
+
 ## ✨ Features
 
 - **Unified Interface**: Interact with multiple AI models through a single, coherent API.
 - **Request Rate Control**: Manage the rate of requests to adhere to provider limitations using Bottleneck.
-- **Flexible Integration**: Easily integrate popular models like OpenAI, Anthropic, Perplexity, Groq, Together AI, Ollama, LM Studio or custom models.
+- **Flexible Integration**: Easily integrate popular models like OpenAI, Anthropic, Perplexity, Groq, Together AI, Ollama, LM Studio, Google Gemini or custom models.
 - **History Tracking**: Automatically logs the conversation history with model responses, allowing you to limit the number of historical messages with `max_history`.
 - **Model Fallbacks**: Automatically try different models if one fails or is unavailable.
+- **Chain Multiple Models**: Create powerful chains of models that work together, with automatic fallback if one fails.
 
 ## 📦 Installation
 
@@ -18,7 +21,7 @@ First, install the ModelMix package:
 npm install modelmix
 ```
 
-Optional: install dotenv to manage environment variables:
+Recommended: install dotenv to manage environment variables:
 
 ```bash
 npm install dotenv
@@ -35,129 +38,106 @@ Here's a quick example to get you started:
     PPLX_API_KEY="your_perplexity_api_key"
     GROQ_API_KEY="your_groq_api_key"
     TOGETHER_API_KEY="your_together_api_key"
+    GOOGLE_API_KEY="your_google_api_key"
     ```
 
 2. **Create and configure your models**:
 
-    ```javascript
-    import 'dotenv/config';
-    import { ModelMix, MixOpenAI, MixAnthropic, MixPerplexity, MixOllama, MixTogether } from 'modelmix';
-
-    const env = process.env;
-
-    const mmix = new ModelMix({
-        options: {
-            max_tokens: 200,
-        },
-        config: {
-            system: "You are {name} from Melmac.",
-            max_history: 2,
-            bottleneck: { maxConcurrent: 2 },
-            debug: true
-        }
-    });
-
-    mmix.replace({ '{name}': 'ALF' });
-
-    mmix.attach(new MixOpenAI({ config: { apiKey: env.OPENAI_API_KEY } }));
-    mmix.attach(new MixAnthropic()); // it will use the default apiKey from process.env
-    mmix.attach(new MixPerplexity({
-        config: {
-            apiKey: env.PPLX_API_KEY
-        },
-        options: {
-            system: "You are my personal assistant."
-        }
-    }));
-    mmix.attach(new MixOllama({
-        config: {
-            url: 'http://localhost:11434/api/chat',
-            prefix: ['llava'],
-        },
-        options: {
-            temperature: 0.5,
-        }
-    }));
-    mmix.attach(new MixTogether());
-    ```
-
-3. **Generate responses from different models**:
-
-    #### Model Fallbacks
-    ```javascript
-    // Create a message handler with multiple fallback models
-    const handler = mmix.create(['grok-2-latest', 'claude-3-7-sonnet-20250219']);
-    
-    // If the first model (grok-2-latest) fails or is unavailable,
-    // ModelMix will automatically try the next model (claude-3-7-sonnet)
-    const response = await handler.addText('do you like cats?').message();
-    ```
+```javascript
+import 'dotenv/config';
+import { ModelMix } from 'modelmix';
 
-    The `create()` method accepts either a single model name as a string or an array of model names. When an array is provided, ModelMix will attempt to use each model in order until a successful response is received. This is useful for:
-    - Implementing fallback options when a primary model is unavailable
-    - Load balancing across different providers
-    - Ensuring high availability in your application
+// Get structured JSON responses
+const model = ModelMix.new()
+    .sonnet37() // Anthropic claude-3-7-sonnet-20250219
+    .addText("Name and capital of 3 South American countries.");
 
-    #### gpt-4o-mini
-    ```javascript
-    const gpt = mmix.create('gpt-4o-mini', { options: { temperature: 0 } });
-    gpt.addText("Have you ever eaten a {animal}?");
-    gpt.replace({ '{animal}': 'cat' });
-    console.log(await gpt.message());
-    ```
+const outputExample = { countries: [{ name: "", capital: "" }] };
+console.log(await model.json(outputExample));
+```
 
-    #### gpt-4.1-nano (json)
-    ```javascript
-    console.log("\n" + '--------| gpt-4.1-nano |--------');
-    const gpt = mmix.create('gpt-4.1-nano', { options: { temperature: 0 } }).addText("Have you ever eaten a {animal}?");
-    gpt.replace({ '{animal}': 'cat' });
-    const schemaExample = { time: '24:00:00', message: 'Hello' };
-    const schemaDescription = { time: 'Time in format HH:MM:SS' }; // optional
-    console.log(await gpt.json(schemaExample, schemaDescription));
-    ```
+```javascript
+// Basic setup with system prompt and debug mode
+const setup = {
+    config: {
+        system: "You are ALF, if they ask your name, respond with 'ALF'.",
+        debug: true
+    }
+};
+
+// Chain multiple models with automatic fallback
+const model = await ModelMix.new(setup)
+    .sonnet37think() // (main model) Anthropic claude-3-7-sonnet-20250219
+    .o4mini() // (fallback 1) OpenAI o4-mini
+    .gemini25proExp({ config: { temperature: 0 } }) // (fallback 2) Google gemini-2.5-pro-exp-03-25
+    .gpt41nano() // (fallback 3) OpenAI gpt-4.1-nano
+    .grok3mini() // (fallback 4) Grok grok-3-mini-beta
+    .addText("What's your name?");
+
+console.log(await model.message());
+```
 
-    #### claude-3-5-sonnet-20240620 (writer)
-    ```javascript
-    const writer = mmix.create('claude-3-5-sonnet-20240620', { options: { temperature: 0.5 } });
-    writer.setSystem('You are a writer like Stephen King'); // or setSystemFromFile
-    writer.replace({ '{story_title}': 'The Mysterious Package' })
-    // or write.replaceKeyFromFile('{story_title}', './title.md');
-    const story = await writer.addTextFromFile('./prompt.md').message();
-    console.log(story);
-    ```
-    #### claude-3-5-sonnet-20240620 (image)
-    ```javascript
-    console.log("\n" + '--------|  |--------');
-    const claude = mmix.create('claude-3-5-sonnet-20240620', { options: { temperature: 0 } });
-    claude.addImage("./watson.jpg"); // or claude.addImageFromUrl(url)
-    const imageDescription = await claude.addText("Describe the image").message();
-    console.log(imageDescription);
-    ```
+```javascript
 
-    #### pplx-70b-online
-    ```javascript
-    const pplx = mmix.create('pplx-70b-online', { config: { max_tokens: 500 } });
-    pplx.addText('How much is ETH trading in USD?');
-    const news = await pplx.addText('What are the 3 most recent Ethereum news?').message();
-    console.log(news);
-    ```
+const ETH = ModelMix.new()
+  .sonar() // Perplexity sonar
+  .addText('How much is ETH trading in USD?')
+  .json({ price: 1000.1 });
+console.log(ETH.price);
+```
 
-    #### ollama (llava:latest)
-    ```javascript
-    await mmix.create('llava:latest')
-        .addImage("./watson.jpg")
-        .addText("What is the predominant color?")
-        .stream((data) => { console.log(data.message); });
-    ```
+This pattern allows you to:
+- Chain multiple models together
+- Automatically fall back to the next model if one fails
+- Get structured JSON responses when needed
+- Keep your code clean and maintainable
+
+## ⚡️ Shorthand Methods
+
+ModelMix provides convenient shorthand methods for quickly accessing different AI models. Here's a comprehensive list of available methods:
+
+| Method             | Provider   | Model                          | Price (I/O) per 1 M tokens |
+| ------------------ | ---------- | ------------------------------ | -------------------------- |
+| `gpt41()`          | OpenAI     | gpt-4.1                        | [\$2.00 / \$8.00][1]       |
+| `gpt41mini()`      | OpenAI     | gpt-4.1-mini                   | [\$0.40 / \$1.60][1]       |
+| `gpt41nano()`      | OpenAI     | gpt-4.1-nano                   | [\$0.10 / \$0.40][1]       |
+| `gpt4o()`          | OpenAI     | gpt-4o                         | [\$5.00 / \$20.00][1]      |
+| `o4mini()`         | OpenAI     | o4-mini                        | [\$1.10 / \$4.40][1]       |
+| `o3()`             | OpenAI     | o3                             | [\$10.00 / \$40.00][1]     |
+| `sonnet37()`       | Anthropic  | claude-3-7-sonnet-20250219     | [\$3.00 / \$15.00][2]      |
+| `sonnet37think()`  | Anthropic  | claude-3-7-sonnet-20250219     | [\$3.00 / \$15.00][2]      |
+| `sonnet35()`       | Anthropic  | claude-3-5-sonnet-20241022     | [\$3.00 / \$15.00][2]      |
+| `haiku35()`        | Anthropic  | claude-3-5-haiku-20241022      | [\$0.80 / \$4.00][2]       |
+| `gemini25flash()`   | Google     | gemini-2.5-flash-preview-04-17  | [\$0.00 / \$0.00][5]       |
+| `gemini25proExp()` | Google     | gemini-2.5-pro-exp-03-25       | [\$0.00 / \$0.00][5]       |
+| `gemini25pro()`    | Google     | gemini-2.5-pro-preview-05-06   | [\$2.50 / \$15.00][5]      |
+| `grok2()`          | Grok       | grok-2-latest                  | [\$2.00 / \$10.00][9]      |
+| `grok3()`          | Grok       | grok-3-beta                    | [\$3.00 / \$15.00][9]      |
+| `grok3mini()`      | Grok       | grok-3-mini-beta               | [\$0.30 / \$0.50][9]       |
+| `sonar()`          | Perplexity | sonar                          | [\$1.00 / \$1.00][7]       |
+| `sonarPro()`       | Perplexity | sonar-pro                      | [\$3.00 / \$15.00][7]      |
+| `qwen3()`          | Groq       | Qwen3-235B-A22B-fp8-tput       | [\$0.29 / \$0.39][8]       |
+| `scout()`          | Groq       | Llama-4-Scout-17B-16E-Instruct | [\$0.11 / \$0.34][8]       |
+| `maverick()`       | Groq       | Maverick-17B-128E-Instruct-FP8 | [\$0.20 / \$0.60][8]       |
+
+[1]: https://openai.com/api/pricing/ "Pricing | OpenAI"
+[2]: https://www.anthropic.com/pricing "Pricing - Anthropic"
+[5]: https://ai.google.dev/gemini-api/docs/pricing "Google AI for Developers"
+[7]: https://docs.perplexity.ai/guides/pricing "Pricing - Perplexity"
+[8]: https://groq.com/pricing/ "Groq Pricing"
+[9]: https://docs.x.ai/docs/models "xAI"
+
+Each method accepts optional `options` and `config` parameters to customize the model's behavior. For example:
 
-    #### Together AI (deepseek-ai/DeepSeek-R1)
-    ```javascript
-    const together = mmix.create('deepseek-ai/DeepSeek-R1', { options: { temperature: 0.7 } });
-    together.addText('What are the main differences between Python and JavaScript?');
-    const comparison = await together.message();
-    console.log(comparison);
-    ```
-4. Find the files for this example at: [/ModelMix/demo](https://github.com/clasen/ModelMix/tree/master/demo).
+```javascript
+const result = await ModelMix.new({ 
+        options: { temperature: 0.7 },
+        config: { system: "You are a helpful assistant" }
+    })
+    .sonnet37()
+    .addText("Tell me a story about a cat");
+    .message();
+```
 
 ## 🔄 Templating Methods
 
@@ -167,7 +147,7 @@ The `replace` method is used to define key-value pairs for text replacement in t
 
 #### Usage:
 ```javascript
-gpt.replace({ '{{key1}}': 'value1', '{{key2}}': 'value2' });
+model.replace({ '{{key1}}': 'value1', '{{key2}}': 'value2' });
 ```
 
 #### How it works:
@@ -176,7 +156,7 @@ gpt.replace({ '{{key1}}': 'value1', '{{key2}}': 'value2' });
 
 #### Example:
 ```javascript
-gpt
+model
   .replace({ '{{name}}': 'Alice', '{{age}}': '30' })
   .addText('Hello {{name}}, are you {{age}} years old?');
 ```
@@ -188,7 +168,7 @@ The `replaceKeyFromFile` method is similar to `replace`, but it reads the replac
 
 #### Usage:
 ```javascript
-messageHandler.replaceKeyFromFile('longText', './path/to/file.txt');
+model.replaceKeyFromFile('longText', './path/to/file.txt');
 ```
 
 #### How it works:
@@ -216,7 +196,7 @@ To activate debug mode in ModelMix and view detailed request information, follow
 1. In the ModelMix constructor, include `debug: true` in the configuration:
 
    ```javascript
-   const mix = new ModelMix({
+   const mix = ModelMix.new({
      config: {
        debug: true
        // ... other configuration options ...
@@ -242,16 +222,16 @@ ModelMix now uses Bottleneck for efficient rate limiting of API requests. This i
 
 1. **Configuration**: Bottleneck is configured in the ModelMix constructor. You can customize the settings or use the default configuration:
 
-    ```javascript
-    const mmix = new ModelMix({
-        config: {
-            bottleneck: {
-                maxConcurrent: 8,     // Maximum number of concurrent requests
-                minTime: 500          // Minimum time between requests (in ms)
-            }
+```javascript
+const setup = {
+    config: {
+        bottleneck: {
+            maxConcurrent: 8,     // Maximum number of concurrent requests
+            minTime: 500          // Minimum time between requests (in ms)
         }
-    });
-    ```
+    }
+};
+```
 
 2. **Rate Limiting**: When you make a request using any of the attached models, Bottleneck automatically manages the request flow based on the configured settings.
 
@@ -284,14 +264,10 @@ new ModelMix(args = { options: {}, config: {} })
 
 **Methods**
 
-- `attach(modelInstance)`: Attaches a model instance to the `ModelMix`.
-- `create(modelKey, overOptions = {})`: Creates a new `MessageHandler` for the specified model.
-
-### MessageHandler Class Overview
+- `attach(modelKey, modelInstance)`: Attaches a model instance to the `ModelMix`.
+- `new()`: `static` Creates a new `ModelMix`.
+- `new()`: Creates a new `ModelMix` using instance setup.
 
-**Methods**
-
-- `new()`: Initializes a new message handler instance.
 - `addText(text, config = { role: "user" })`: Adds a text message.
 - `addTextFromFile(filePath, config = { role: "user" })`: Adds a text message from a file path.
 - `addImage(filePath, config = { role: "user" })`: Adds an image message from a file path.
@@ -404,6 +380,16 @@ new MixTogether(args = { config: {}, options: {} })
   - **config**: Specific configuration settings for Together AI, including the `apiKey`.
   - **options**: Default options for Together AI model instances.
 
+### MixGoogle Class Overview
+
+```javascript
+new MixGoogle(args = { config: {}, options: {} })
+```
+
+- **args**: Configuration object with `config` and `options` properties.
+  - **config**: Specific configuration settings for Google Gemini, including the `apiKey`.
+  - **options**: Default options for Google Gemini model instances.
+
 ## 🤝 Contributing
 
 Contributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the [GitHub repository](https://github.com/clasen/ModelMix).

package/demo/custom.mjs

@@ -1,6 +1,6 @@
 import 'dotenv/config'
 
-import { ModelMix, MixCerebras, MixTogether } from '../index.js';
+import { ModelMix, MixCustom } from '../index.js';
 
 const mmix = new ModelMix({
     options: {
@@ -13,8 +13,46 @@ const mmix = new ModelMix({
     }
 });
 
-mmix.attach(new MixCerebras());
+class MixTogether extends MixCustom {
+    getDefaultConfig(customConfig) {
+        return super.getDefaultConfig({
+            url: 'https://api.together.xyz/v1/chat/completions',
+            apiKey: process.env.TOGETHER_API_KEY,
+            ...customConfig
+        });
+    }
+
+    getDefaultOptions(customOptions) {
+        return {
+            stop: ["<|eot_id|>", "<|eom_id|>"],
+            ...customOptions
+        };
+    }
+
+    static convertMessages(messages) {
+        return messages.map(message => {
+            if (message.content instanceof Array) {
+                message.content = message.content.map(content => content.text).join("\n\n");
+            }
+            return message;
+        });
+    }
+
+    async create({ config = {}, options = {} } = {}) {
+        if (!this.config.apiKey) {
+            throw new Error('Together API key not found. Please provide it in config or set TOGETHER_API_KEY environment variable.');
+        }
+
+        const content = config.system + config.systemExtra;
+        options.messages = [{ role: 'system', content }, ...options.messages || []];
+        options.messages = MixTogether.convertMessages(options.messages);
+
+        return super.create({ config, options });
+    }
+}
+
+mmix.attach('Qwen/Qwen3-235B-A22B-fp8-tput', new MixTogether());
 
-let r = mmix.create('llama-4-scout-17b-16e-instruct').addText('hi there');
+let r = mmix.addText('hi there');
 r = await r.addText('do you like cats?').message();
 console.log(r);