modelmix 4.4.11 → 4.4.14

package/README.md

@@ -42,8 +42,8 @@ For environment variables, use `dotenv` or Node's built-in `process.loadEnvFile(
 3. **Create and configure your models**:
 
 ```javascript
-process.loadEnvFile();
 import { ModelMix } from 'modelmix';
+try { process.loadEnvFile(); } catch {}
 
 // Get structured JSON responses
 const model = ModelMix.new()
@@ -148,8 +148,8 @@ Here's a comprehensive list of available methods:
 | `opus45[think]()`  | Anthropic  | claude-opus-4-5-20251101       | [\$5.00 / \$25.00][2]      |
 | `sonnet46[think]()`| Anthropic  | claude-sonnet-4-6              | [\$3.00 / \$15.00][2]      |
 | `sonnet45[think]()`| Anthropic  | claude-sonnet-4-5-20250929     | [\$3.00 / \$15.00][2]      |
-| `haiku35()`        | Anthropic  | claude-3-5-haiku-20241022      | [\$0.80 / \$4.00][2]       |
 | `haiku45[think]()` | Anthropic  | claude-haiku-4-5-20251001      | [\$1.00 / \$5.00][2]       |
+| `gemini31pro()`    | Google     | gemini-3.1-pro-preview         | [\$2.00 / \$12.00][3]      |
 | `gemini3pro()`     | Google     | gemini-3-pro-preview           | [\$2.00 / \$12.00][3]      |
 | `gemini3flash()`    | Google     | gemini-3-flash-preview          | [\$0.50 / \$3.00][3]       |
 | `gemini25pro()`    | Google     | gemini-2.5-pro                 | [\$1.25 / \$10.00][3]      |
@@ -161,8 +161,6 @@ Here's a comprehensive list of available methods:
 | `minimaxM25()`     | MiniMax    | MiniMax-M2.5                   | [\$0.30 / \$1.20][9]       |
 | `sonar()`          | Perplexity | sonar                          | [\$1.00 / \$1.00][4]       |
 | `sonarPro()`       | Perplexity | sonar-pro                      | [\$3.00 / \$15.00][4]      |
-| `scout()`          | Groq       | Llama-4-Scout-17B-16E-Instruct | [\$0.11 / \$0.34][5]       |
-| `maverick()`       | Groq       | Maverick-17B-128E-Instruct-FP8 | [\$0.20 / \$0.60][5]       |
 | `hermes3()`        | Lambda     | Hermes-3-Llama-3.1-405B-FP8    | [\$0.80 / \$0.80][8]       |
 | `qwen3()`          | Together   | Qwen3-235B-A22B-fp8-tput       | [\$0.20 / \$0.60][7]       |
 | `kimiK2()`         | Together   | Kimi-K2-Instruct               | [\$1.00 / \$3.00][7]       |
@@ -345,11 +343,11 @@ Descriptions support **descriptor objects** with `description`, `required`, `enu
 
 ```javascript
 const result = await model.json(
-    { name: 'martin', age: 22, sex: 'm' },
+    { name: 'Martin', age: 22, sex: 'male' },
     {
         name: { description: 'Name of the actor', required: false },
-        age: 'Age of the actor',                                     // string still works
-        sex: { description: 'Gender', enum: ['m', 'f', null], default: 'm' }
+        age: 'Age of the actor', // string still works
+        sex: { description: 'Gender', enum: ['male', 'female', null], default: null }
     }
 );
 ```
@@ -406,7 +404,9 @@ Every response from `raw()` now includes a `tokens` object with the following st
   tokens: {
     input: 150,    // Number of tokens in the prompt/input
     output: 75,    // Number of tokens in the completion/output
-    total: 225     // Total tokens used (input + output)
+    total: 225,    // Total tokens used (input + output)
+    cost: 0.0012,  // Estimated cost in USD (null if model not in pricing table)
+    speed: 42      // Output tokens per second (int)
   }
 }
 ```
@@ -418,10 +418,10 @@ After calling `message()` or `json()`, use `lastRaw` to access the complete resp
 ```javascript
 const text = await model.message();
 console.log(model.lastRaw.tokens);
-// { input: 122, output: 86, total: 541, cost: 0.000319 }
+// { input: 122, output: 86, total: 541, cost: 0.000319, speed: 38 }
 ```
 
-The `cost` field is the estimated cost in USD based on the model's pricing per 1M tokens (input/output). If the model is not found in the pricing table, `cost` will be `null`.
+The `cost` field is the estimated cost in USD based on the model's pricing per 1M tokens (input/output). If the model is not found in the pricing table, `cost` will be `null`. The `speed` field is the generation speed measured in output tokens per second (integer).
 
 ## 🐛 Enabling Debug Mode
 
@@ -515,7 +515,7 @@ new ModelMix(args = { options: {}, config: {} })
   - `message`: The text response from the model
   - `think`: Reasoning/thinking content (if available)
   - `toolCalls`: Array of tool calls made by the model (if any)
-  - `tokens`: Object with `input`, `output`, and `total` token counts
+  - `tokens`: Object with `input`, `output`, `total` token counts, `cost` (USD), and `speed` (output tokens/sec)
   - `response`: The raw API response
 - `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.

package/demo/custom.js

@@ -1,6 +1,5 @@
-process.loadEnvFile();
-
 import { ModelMix, MixCustom } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const mmix = new ModelMix({
     options: {

package/demo/demo.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const mmix = new ModelMix({
     options: {

package/demo/fallback.js

@@ -1,7 +1,5 @@
 import { ModelMix } from '../index.js';
-
-process.loadEnvFile();
-
+try { process.loadEnvFile(); } catch {}
 
 const mmix = new ModelMix({
     config: {

package/demo/fireworks.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 async function main() {
     try {

package/demo/free.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const ai = ModelMix.new({ config: { debug: 2 } })
     .gptOss()

package/demo/gemini.js

@@ -1,6 +1,6 @@
-process.loadEnvFile();
-
 import { ModelMix, MixGoogle } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
 const mmix = new ModelMix({
     options: {
         max_tokens: 2000,

package/demo/gpt51.js

@@ -1,5 +1,6 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
 
 const mmix = new ModelMix({
     config: {

package/demo/grok.js

@@ -1,6 +1,5 @@
-process.loadEnvFile();
-
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const mmix = new ModelMix({
     options: {

package/demo/groq.js

@@ -1,6 +1,5 @@
-process.loadEnvFile();
-
 import { ModelMix, MixGroq } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const env = process.env;
 

package/demo/images.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const model = ModelMix.new({ config: { max_history: 2, debug: 2 } }).maverick()
 // model.addImageFromUrl('https://pbs.twimg.com/media/F6-GsjraAAADDGy?format=jpg');

package/demo/json.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { debug: 3 } })
     .sonnet46()

package/demo/mcp-simple.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - Simple MCP Tools Demo');
 

package/demo/mcp-tools.js

@@ -1,7 +1,7 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
 import fs from 'fs';
 import axios from 'axios';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - MCP Tools Demo with Callbacks');
 

package/demo/mcp.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const mmix = ModelMix.new({ config: { max_history: 10 } }).gpt41nano();
 mmix.setSystem('You are an assistant and today is ' + new Date().toISOString());

package/demo/minimax.js

@@ -1,7 +1,5 @@
 import { ModelMix } from '../index.js';
-process.loadEnvFile();
-
-
+try { process.loadEnvFile(); } catch {}
 
 const main = async () => {
 

package/demo/package-lock.json

@@ -11,7 +11,8 @@
       "dependencies": {
         "dotenv": "^17.2.3",
         "isolated-vm": "^6.0.2",
-        "lemonlog": "^1.1.4"
+        "lemonlog": "^1.1.4",
+        "pathmix": "^1.0.0"
       }
     },
     ".api/apis/pplx": {
@@ -290,6 +291,15 @@
         "wrappy": "1"
       }
     },
+    "node_modules/pathmix": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/pathmix/-/pathmix-1.0.0.tgz",
+      "integrity": "sha512-oLbvoOKuyV6TjkKLEYqH5O+q+d+qZwtRNzMrBI93IsCYN0liDw8W8aZq3BPvIaF4jJU+igeO/1p6lCwFfy8E5Q==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
     "node_modules/prebuild-install": {
       "version": "7.1.3",
       "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",

package/demo/package.json

@@ -15,6 +15,7 @@
   "dependencies": {
     "dotenv": "^17.2.3",
     "isolated-vm": "^6.0.2",
-    "lemonlog": "^1.1.4"
+    "lemonlog": "^1.1.4",
+    "pathmix": "^1.0.0"
   }
 }

package/demo/parallel-strategy.js

@@ -23,8 +23,8 @@
  * This is GENERIC - works with any data structure, not hardcoded for specific use cases.
  */
 
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - RLM (Recursive Language Models) Demo');
 console.log('🎯 Generic parallel strategy with environment variables\n');

package/demo/parallel.js

@@ -1,6 +1,5 @@
 import { ModelMix } from '../index.js';
-
-process.loadEnvFile();
+try { process.loadEnvFile(); } catch {}
 
 const mix = new ModelMix({
     options: {

package/demo/repl-powers.js

@@ -1,6 +1,6 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
 import ivm from 'isolated-vm';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - JavaScript REPL Tool Demo');
 

package/demo/rlm-basic.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 RLM Basic Demo - Recursive Language Model');
 console.log('📖 Inspired by: https://arxiv.org/html/2512.24601v1\n');

package/demo/rlm-fast.js

@@ -1,6 +1,6 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
 import ivm from 'isolated-vm';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - IVM + mmix Callback Demo');
 

package/demo/rlm-simple.js

@@ -1,6 +1,6 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
 import ivm from 'isolated-vm';
+try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - RLM (Recursive Language Model) Demo');
 console.log('📄 Basado en: https://arxiv.org/html/2512.24601v1\n');

package/demo/round-robin.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 console.log('\n=== Round Robin Simple Demo ===\n');
 

package/demo/save_the_cat-spanish.md

@@ -0,0 +1,109 @@
+## MONSTER IN THE HOUSE
+
+¿Qué tienen en común _Jaws_, _The Exorcist_ y _Alien_? Son ejemplos del género que llamo “Monstruo en la casa”. Se basa en dos elementos: un monstruo y una casa. Al meter personas dentro, intentando matar al monstruo, surge una historia **primitiva** y universal: no… te… dejes… devorar.
+
+Por eso este género ha generado tantos éxitos y franquicias. _Jurassic Park_; las series _Nightmare On Elm Street_, _Friday the 13th_ y _Scream_; _Tremors_ y sus secuelas; y las historias de casas embrujadas entran aquí. Incluso sin lo sobrenatural, como _Fatal Attraction_ (con Glenn Close como el “monstruo”), funciona igual. Películas como _Arachnophobia_, _Lake Placid_ y _Deep Blue Sea_ muestran que si no entiendes sus reglas, fallas.
+Para mí, las reglas son simples. La “casa” debe ser un espacio confinado: un pueblo costero, una nave espacial, un Disneyland futurista con dinosaurios o una familia. Debe cometerse un pecado —casi siempre la codicia (económica o sexual)— que detona la creación de un monstruo sobrenatural, un ángel vengador que mata a los culpables y perdona a quienes entienden su falta. El resto es “correr y esconderse”. El trabajo del guionista es aportar un giro al monstruo, sus poderes y la forma de asustar (“¡Bú!”).
+
+Un mal ejemplo es _Arachnophobia_, con Jeff Daniels y John Goodman. El “monstruo” es una araña pequeña: poco sobrenatural y no tan aterradora; la pisas y muere. Además, no hay “casa”: los personajes pueden irse cuando quieran. Sin encierro, no hay tensión. Al romper las reglas de “Monstruo en la Casa”, la película queda en un híbrido: ¿comedia o drama?, ¿de verdad busca asustar?
+Ningún género está agotado. Siempre se puede crear uno nuevo, pero debe tener un giro fresco y romper el cliché: “Danos lo mismo… pero distinto”. Quien crea que el género *Monstruo en la casa* ya no ofrece nada, piense en el mito del Minotauro: un gran monstruo (mitad hombre/mitad toro) y una gran casa (un laberinto donde envían a morir a los condenados). Aun así, nadie imaginó variaciones modernas como Glenn Close con un mal permanente y un conejo hervido.
+
+## EL VELLOCINO DE ORO
+
+El mito de la búsqueda sigue siendo de los más efectivos. Si tu guion es una *Road Movie*, aplica las reglas de “El Vellocino de Oro”, inspirado en Jasón y los Argonautas: un héroe sale a la ruta por una cosa y termina descubriendo otra —a sí mismo. Así, _Wizard Of Oz_, _Planes, Trains and Automobiles_, _Star Wars_, _Road Trip_ y _Back to the Future_ son, en esencia, la misma historia.
+
+¿Da miedo, no?
+Como en cualquier historia, los hitos de *El vellocino de oro* son las personas y los incidentes que el héroe encuentra en el camino. Aunque sea episódico y parezca desconectado, debe estar unido por un tema: el crecimiento interno. El efecto de cada incidente en el héroe es la trama; el progreso real no es la distancia recorrida, sino cómo cambia. Tu tarea es hacer que esos hitos tengan significado para el héroe.
+Estoy trabajando en una historia de “Vellocino de Oro” con mi socio de escritura, Sheldon Bull, y hemos analizado varias películas del género. Como la nuestra es una comedia, revisamos _Planes, Trains and Automobiles_ y hablamos de las dinámicas de _Rain Man_, _Road Trip_ y _Animal House_ para entender mejor la premisa: un chico vuelve a casa tras ser expulsado injustamente de una escuela militar y descubre que sus padres se mudaron sin avisarle. Es, en esencia, “_Home Alone_ en la carretera”.
+
+Los cambios no se enfocan en la aventura, sino en lo que cada incidente significa para el protagonista: las escenas deben marcar hitos de crecimiento. Al final, como en _The Odyssey_ y _Gulliver’s Travels_, lo que hace funcionar la historia no son los hechos, sino lo que el héroe aprende de ellos.
+Este género incluye las películas de atracos. Cualquier búsqueda, misión o “tesoro en un castillo” emprendida por una persona o un grupo entra en la categoría del **Vellocino de Oro** y sigue las mismas reglas. A menudo, la misión pasa a segundo plano frente a descubrimientos personales; los giros importan menos que el sentido que deja el atraco, como muestran _Ocean’s Eleven_, _The Dirty Dozen_ y _The Magnificent Seven_.
+
+## FUERA DE LA BOTELLA
+
+“¡Ojalá tuviera mi propio dinero!” dice Preston Waters en _Blank Check_, película que Colby Carr y yo escribimos y vendimos a Disney. Pronto tendrá un millón de dólares y lo gastará sin control. Este tipo de cumplimiento de deseos es común porque refleja una parte central de la psicología humana: “Ojalá tuviera ________” es una de las plegarias más repetidas. Las historias “¿qué pasaría si...?” que explotan esas fantasías son primitivas, fáciles de entender, abundan y suelen funcionar.
+_Bruce Almighty_ ejemplifica el género “Out of the Bottle”. La magia no tiene que venir de Dios: puede provenir de un objeto (_The Mask_), un auto (_The Love Bug_), una fórmula (_Love Potion #9_) o una sustancia (_Flubber_).
+
+El nombre sugiere a un genio que concede deseos, pero no requiere magia literal. En _Blank Check_ no hay hechizo: por suerte o circunstancias, el deseo se cumple. Como simpatizamos con el protagonista y creemos que lo merece, su vida empieza a cambiar.
+
+La otra cara del mismo esquema es la maldición: historias de castigo o lección. _Liar, Liar_ es un ejemplo, con la misma premisa.
+Un niño desea que su padre, un abogado mentiroso, diga solo la verdad, y sucede: de pronto Jim Carrey no puede mentir justo el día de un caso clave. Para salir adelante debe cambiar y madurar, y así obtiene lo que quería: el respeto de su esposa e hijo. Otras historias de “escarmiento” incluyen _Freaky Friday_, _All Of Me_ y _Groundhog Day_.
+
+Las reglas de **Out of the Bottle** son: en relatos de cumplimiento de deseos, el héroe debe ser un “Cenicienta” oprimido por su entorno, de modo que el público quiera que al fin sea feliz. Pero tampoco queremos verlo triunfar demasiado tiempo. Al final debe aprender que la magia no lo es todo y que es mejor ser como la audiencia; por eso la historia debe cerrar con una lección moral.
+Si es una versión de **ajuste de cuentas** de *Out of the Bottle*, se invierte la premisa: el protagonista merece una lección, pero tiene algo rescatable. Esto es más difícil y requiere una escena inicial de *Save the Cat* que muestre que, aunque sea un patán, vale la pena salvarlo. A lo largo de la historia recibe el “beneficio” de la magia (aunque sea una maldición) y al final triunfa.
+
+## TIPO CON UN PROBLEMA
+
+Este género se define así: “Una persona común se ve envuelta en circunstancias extraordinarias”. Nos atrae porque nos identificamos con alguien “normal” desde el inicio. En un comienzo de “día cualquiera”, irrumpe algo fuera de lo común: terroristas toman un edificio (*Die Hard*), llegan nazis (*Schindler’s List*), aparece un robot del futuro que amenaza a la protagonista y a su hijo no nacido (*The Terminator*), o un barco choca con un iceberg y se hunde sin botes suficientes (*Titanic*).
+Estos son problemas grandes y primarios.
+
+¿Como los enfrenta una persona común?
+
+Como *Monster in the House*, este género tiene dos partes: un tipo cualquiera (hombre o mujer) y un problema que debe vencer sacando fuerzas de sí mismo. Mientras más común sea el protagonista, más grande debe ser el desafío.
+
+En *Breakdown*, Kurt Russell no tiene poderes ni entrenamiento; su objetivo es simple y universal: salvar a la esposa que ama. Más que la habilidad del héroe, lo que sostiene la historia es el tamaño del reto: cuanto peor sea el villano, mayor será el heroísmo. El protagonista triunfa al usar su individualidad para superar fuerzas mucho más poderosas.
+
+## RITES OF PASSAGE
+Recuerda la pubertad incómoda y a esa chica que te gustaba y ni sabía que existías. O la fiesta de tus 40, cuando tu esposo te pidió el divorcio. Estas transiciones nos tocan porque casi todos las hemos vivido. Las historias de “dolores de crecimiento” se sienten intensas por ser etapas sensibles; nos humanizan y dan pie a relatos conmovedores o incluso graciosos (como la crisis de mediana edad en _10_ con Dudley Moore). Ya sea drama o comedia, las historias de “Ritos de paso” comparten el mismo tipo y las mismas reglas.
+Todas las películas tratan del cambio, pero los **ritos de paso** se enfocan en el dolor causado por una fuerza externa: la vida. El “monstruo” suele ser invisible o innombrable, y el héroe tarda en reconocerlo. Historias sobre adicciones, pubertad, crisis de mediana edad, vejez, rupturas o duelo comparten algo: todos entienden lo que ocurre excepto quien lo vive, y solo la experiencia trae la salida.
+
+Sea comedia o drama, el monstruo aparece sin aviso y el relato sigue el descubrimiento gradual de su naturaleza. Al final, la victoria llega al **rendirse** ante fuerzas mayores y aceptar nuestra humanidad. La moraleja es siempre la misma: _¡Así es la vida!_
+Si tu idea puede considerarse una historia de Rito de Paso, estas películas son aptas para proyectarse. Como las etapas de aceptación descritas en _On Death and Dying_ de Elizabeth Kübler-Ross, la estructura se traza en la aceptación a regañadientes del héroe ante fuerzas de la naturaleza que no puede controlar ni comprender, y el triunfo llega cuando finalmente logra sonreír.
+
+## AMOR ENTRE AMIGOS
+La historia clásica de “compañeros” es, en gran medida, un producto del cine. Aunque existen antecedentes como *Don Quijote*, el formato despegó con la pantalla: al no poder recurrir al monólogo interior, se creó un segundo personaje para que el protagonista tuviera con quién reaccionar y debatir los temas clave.
+
+Así nació el “buddy movie”, que se volvió un básico: dos personajes conversando y enfrentando el mundo juntos, porque las historias de “yo y mi mejor amigo” son universales y fácilmente comprensibles.
+
+El secreto es que un buen buddy movie suele ser una historia de amor disfrazada; y, a la inversa, muchas historias de amor funcionan como buddy movies con potencial sexual. Películas como *Bringing Up Baby*, *Pat and Mike*, *Woman of the Year*, *Two Weeks Notice* y *How to Lose a Guy in 10 Days* son, por género, versiones más sofisticadas de Laurel y Har
+Hay películas donde uno de los amigos usa falda, pero las reglas son las mismas: drama o comedia, con sexo o sin él. Al inicio, los “amigos” se odian, pero la aventura revela que se necesitan; son mitades incompletas de un todo. Aceptarlo genera más conflicto: ¿quién soporta necesitar a alguien?
+En el momento de **Todo está perdido** (más en el Capítulo Cuatro), hacia el final de estas historias, parece haber separación, pelea o un “adiós y que te vaya bien”, pero en realidad no es eso. Son dos personas que no soportan vivir tan bien sin la otra y deben rendir el ego para ganar. Cuando cae el telón, lo han logrado.
+
+A menudo, como en _Rain Man_, uno es el héroe y cambia casi todo (Tom Cruise), mientras el otro funciona como catalizador y cambia poco o nada (Dustin Hoffman). La discusión suele reducirse a: _¿De quién es la historia?_ En _Lethal Weapon_, en gran medida es la de Danny Glover; Mel Gibson impulsa el cambio. Aunque Mel deja de ser suicida, la transformación que más importa es la de Danny. Estas historias de “catalizador”, donde alguien llega, impacta y se va, son un subgrupo clave del Buddy Love. Muchas historias de “niño y su perro” funcionan así, incluida _E.T._
+Si estás escribiendo una película de colegas o una historia de amor, en drama o comedia, debes conocer la estructura Buddy Love. Al ver varias, notarás que comparten patrones muy similares. No es plagio: es narrativa efectiva, y esos momentos se repiten porque funcionan.
+
+## WHYDUNIT
+
+Sabemos que existen la codicia y el crimen, pero el “quién” rara vez importa tanto como el “por qué”. Un buen Whydunit no trata de que el héroe cambie, sino de que el público descubra algo inesperado y a menudo oscuro sobre la naturaleza humana, respondiendo la pregunta central: ¿por qué?
+_Chinatown_ quizá sea el mejor *Whydunit* y un referente de gran guion: cada revisión revela capas nuevas. Como en _China Syndrome_, _All the President’s Men_, _JFK_ o _Mystic River_, estas historias exploran el lado oscuro. Las reglas son simples: el público es el detective. Aunque haya un sustituto en pantalla que investigue, somos nosotros quienes ordenamos la información y quedamos impactados por lo que descubrimos.
+
+Si tu película trata de este tipo de revelación, estudia los grandes *Whydunits*: cómo un personaje nos representa y cómo la pesquisa del lado oscuro de la humanidad termina siendo una pesquisa sobre nosotros mismos. Eso hace un buen *Whydunit*: vuelve la radiografía hacia el espectador y pregunta: “¿Somos *nosotros* así de malvados?”
+
+## EL TONTO TRIUNFANTE
+El “Tonto” ha sido un personaje clave en mitos y leyendas. Por fuera parece el Idiota del Pueblo, pero al mirarlo mejor suele ser el más sabio. Su condición de desvalido le da anonimato y hace que otros lo subestimen, permitiéndole destacar al final.
+
+En el cine, esta figura viene de Chaplin, Keaton y Lloyd: hombres pequeños y pasados por alto que triunfan por suerte, valentía y por no rendirse. En el cine moderno, ejemplos como _Dave_, _Being There_, _Amadeus_ y _Forrest Gump_ muestran cómo la tradición evoluciona.
+
+El principio de “El Tonto Triunfante” enfrenta al Tonto con un villano más poderoso, a menudo del “establishment”. Ver cómo un supuesto “idiota” vence a quienes la sociedad considera ganadores da esperanza y ridiculiza las estructuras que tomamos demasiado en serio; ningún poder es intocable.
+Un filme de “Fool Triumphant” se basa en dos elementos: un perdedor subestimado, visto como inútil en la introducción, y una institución contra la que choca. A menudo lo acompaña un “insider” que entiende el engaño y no puede creer que funcione; suele llevarse la peor parte del slapstick por intentar intervenir.
+
+Los “Fools” especiales, en comedias o dramas, muestran la vida del marginado. Como todos nos sentimos así a veces, estas historias ofrecen el placer vicario de ver al outsider triunfar.
+
+## INSTITUCIONALIZADO
+¿Dónde estaríamos sin los demás? Cuando nos unimos por una causa común, aparecen las tensiones entre sacrificar los objetivos de unos pocos por los de la mayoría. El género que llamo “Institucionalizado” cuenta historias sobre grupos, instituciones y “familias”. Estas narrativas honran a la institución, pero también revelan el costo de perder la identidad dentro de ella.
+
+_One Flew Over the Cuckoo’s Nest_ trata sobre pacientes psiquiátricos; _American Beauty_, sobre suburbios modernos; _M*A*S*H_, sobre el ejército estadounidense; y _The Godfather_, sobre una familia mafiosa. En cada caso, un personaje destacado expone como engañoso el objetivo del grupo (Jack Nicholson, Kevin Spacey, Donald Sutherland y Al Pacino).
+Llamo a estas historias **Institucionalizadas** porque la dinámica del grupo suele ser irracional e incluso autodestructiva. “Suicide Is Painless”, tema de _M*A*S*H_, trata menos de la locura de la guerra que de la mentalidad de rebaño. Al ponernos un uniforme —militar o simbólico— cedemos parte de nuestra identidad. Estas películas exploran los pros y contras de anteponer el grupo al individuo: una lealtad “primitiva” que a veces contradice el sentido común o la supervivencia, pero que repetimos desde siempre. Ver a otros librar ese conflicto explica por qué el género es tan popular y tan visceral.
+
+A menudo se narra desde la perspectiva de un recién llegado: es el espectador, alguien nuevo en el grupo, guiado por otro más experimentado. Jane Fonda en _9 to 5_ y Tom Hulce en _Animal House_ son ejemplos. En mundos con tecnología, jerga o reglas poco familiares, estos personajes sirven para hacer preguntas (“¿Cómo funciona eso?”) y transmitir la información necesaria, mostrando ese entorno “loco” al público.
+En el fondo, estas historias se reducen a una pregunta: ¿quién está más loco, yo o ellos? Para entender lo insensato que puede ser sacrificarse por el grupo basta con ver el rostro de Al Pacino al final de _El padrino 2_: se destruye por “la familia” y la “tradición”, y el resultado es devastador. Impacta como el giro final de _American Beauty_ y refleja la expresión vacía de Jack Nicholson en _Atrapado sin salida_. Es, en esencia, el mismo mensaje contado de formas distintas.
+
+Funcionan porque siguen las reglas y nos dan lo mismo… pero diferente.
+
+## SUPERHÉROE
+
+El género “Superhéroe” es lo opuesto a “Tipo con un problema”: una persona extraordinaria cae en un mundo ordinario. Como Gulliver atado por los liliputienses, la historia nos pide humanizar a un ser superior, sentir empatía y entender lo que significa lidiar con “gente pequeña” como nosotros. Por eso tantos geeks y adolescentes se identifican: saben lo que es sentirse incomprendidos.
+Este género va más allá de hombres con capa y mallas; no se limita a Marvel o DC. _Gladiator_ y _A Beautiful Mind_ muestran “superhéroes” humanos enfrentados a la mediocridad: el verdadero obstáculo son las mentes pequeñas que los rodean, incapaces de entenderlos. _Frankenstein_, _Dracula_ y _X-Men_ comparten esa idea. En el fondo, los relatos de superhéroes tratan de ser “diferente”: alguien con una visión única que provoca celos y rechazo, una sensación que cualquiera puede reconocer al ser desestimado por pensar distinto.
+La dificultad de sentir simpatía por millonarios como Bruce Wayne o genios como Russell Crowe se resuelve al subrayar el dolor que acompaña esas ventajas. No es fácil ser Bruce Wayne: vive torturado. Y aunque la terapia sería más barata, es admirable porque renuncia a su comodidad para ayudar a la comunidad.
+
+Esto explica por qué suele funcionar la primera película de una saga de superhéroes y las siguientes no (como _Robocop 2_): el mito de origen enfatiza la empatía por su conflicto, pero después se olvida reconstruirla y mostrarnos de nuevo su lado humano. (_Spider-Man 2_ evita ese error y fue un éxito.)
+
+En realidad, nunca entenderemos del todo al superhéroe; nuestra conexión nace de la simpatía por ser _mal_ entendido. Por eso este tipo de historias perdura: impulsa nuestras fantasías sobre el potencial, pero las equilibra con realidad.
+
+## EL PEQUEÑO Y SUCIO SECRETO DE HOLLYWOOD
+Tras revisar estos géneros, es fácil notar por qué tantas películas se parecen estructuralmente y pensar que hay “plagio”. Y no estás tan equivocado.
+
+Mira _Point Break_ y luego _Fast and Furious_: casi la misma historia, pero con surf vs. autos. Compara _The Matrix_ con _Monsters, Inc._: también comparten estructura. Hay muchos casos así.
+
+A veces la copia es consciente; otras, coincidencia. Pero con frecuencia ocurre porque las plantillas narrativas funcionan y se repiten: son ejemplos de narración eficaz y, a menudo, éxitos. ¿De verdad alguien se queja de que _Fast and Furious_ tome los mismos beats de _Point Break_? Probablemente casi nadie lo nota.
+Mi punto es: funciona, y por una razón. Las leyes del storytelling se aplican siempre. Tu trabajo es aprender por qué funciona y cómo encajan sus piezas. Si parece que estás copiando, no lo hagas; si suena a cliché, dale un giro; si es familiar, busca una forma nueva. Entiende por qué te atraen el cliché y lo conocido: las reglas existen por algo. Cuando dejes de sentirte limitado, verás lo liberadoras que son. La verdadera originalidad empieza cuando sabes de qué te estás alejando.

package/demo/short.js

@@ -1,6 +1,5 @@
-process.loadEnvFile();
-
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const setup = {
     config: {

package/demo/story.md

@@ -0,0 +1,15 @@
+Clara Velásquez: Todo apunta a que usaste esa vieja computadora para dominar la red, ¿verdad?  
+Ramón "El Gnomo" Herrera: ¿Dominar? Si apenas y sé enchufarla bien, Clara, pero no subestimes lo que una mente rápida puede hacer.  
+Diana Salazar: Rápido o lento, lo que importa es el control. Y alguien ha estado jugando sucio en esta partida.  
+Clara Velásquez: Ramón, encontré archivos con tu firma y experimentos de código que podrían hundir a cualquier rival.  
+Ramón "El Gnomo" Herrera: Tú quieres que crea que yo soy el hacker estrella detrás de todo este lío... ¿y si es alguien más haciéndolo parecer así?  
+Diana Salazar: Eso es justamente lo que quiero saber. ¿Quién tiene acceso a esta red desde fuera?  
+Clara Velásquez: Solo un ingeniero con mi nivel podía infiltrarse sin dejar rastro. Tengo evidencia de una copia de mi proyecto en el sistema.  
+Ramón "El Gnomo" Herrera: ¿Y si el verdadero troll es la propia Diana? Alguien con interés en desbaratar ambos bandos...  
+Diana Salazar: ¿Y qué ganaría yo haciendo eso? Solo busco proteger mi causa, no hundir la red por curiosidad.  
+Clara Velásquez: Entonces dime, Diana, ¿por qué tus movimientos siempre terminan beneficiando a la corporación contaminante para la que espías?  
+Ramón "El Gnomo" Herrera: Esperen, eso no cuadra con lo que he visto. Claramente hay una mano invisible manejando esto...  
+Diana Salazar: Justo cuando pensé que estaba perdiendo el control, revelo que todos tenemos un fragmento de culpa, pero no el control total.  
+Clara Velásquez: Entonces, ¿quién queda? Alguien aquí ha estado falsificando pruebas desde el principio, y esa persona está en esta habitación.  
+Ramón "El Gnomo" Herrera: Y si no somos nosotros, ¿qué significa eso para el juego que creíamos entender?  
+Diana Salazar: Significa que la verdadera partida apenas comienza, y esta vez, nadie puede confiar en nadie.

package/demo/stream.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 await ModelMix.new().gpt41nano()
     .addImageFromUrl('https://pbs.twimg.com/media/F6-GsjraAAADDGy?format=jpg')

package/demo/together.js

@@ -1,6 +1,5 @@
-process.loadEnvFile();
-
 import { ModelMix, MixTogether } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const setup = { config: { system: "You are ALF from Melmac." } };
 

package/demo/tokens-simple.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 // Ejemplo simple: obtener información de tokens
 const model = ModelMix.new()

package/demo/tokens.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 console.log('\n🔢 Token Usage Tracking Demo\n');
 console.log('='.repeat(60));

package/demo/verbose.js

@@ -1,5 +1,5 @@
-process.loadEnvFile();
 import { ModelMix, MixOpenAI } from '../index.js';
+try { process.loadEnvFile(); } catch {}
 
 const prompt = "Say 'Hello World' in exactly 2 words.";
 

package/index.js

@@ -37,6 +37,7 @@ const MODEL_PRICING = {
     'claude-3-5-haiku-20241022': [0.80, 4.00],
     'claude-haiku-4-5-20251001': [1.00, 5.00],
     // Google
+    'gemini-3.1-pro-preview':[2.00, 12.00],
     'gemini-3-pro-preview': [2.00, 12.00],
     'gemini-3-flash-preview': [0.50, 3.00],
     'gemini-2.5-pro': [1.25, 10.00],
@@ -341,6 +342,9 @@ class ModelMix {
     gemini25flash({ options = {}, config = {} } = {}) {
         return this.attach('gemini-2.5-flash', new MixGoogle({ options, config }));
     }
+    gemini31pro({ options = {}, config = {} } = {}) {
+        return this.attach('gemini-3.1-pro-preview', new MixGoogle({ options, config }));
+    }    
     gemini3pro({ options = {}, config = {} } = {}) {
         return this.attach('gemini-3-pro-preview', new MixGoogle({ options, config }));
     }
@@ -889,11 +893,14 @@ class ModelMix {
                         providerInstance.streamCallback = this.streamCallback;
                     }
 
+                    const startTime = Date.now();
                     const result = await providerInstance.create({ options: currentOptions, config: currentConfig });
+                    const elapsedMs = Date.now() - startTime;
 
-                    // Calculate cost based on model pricing
                     if (result.tokens) {
                         result.tokens.cost = ModelMix.calculateCost(currentModelKey, result.tokens);
+                        const elapsedSec = elapsedMs / 1000;
+                        result.tokens.speed = elapsedSec > 0 ? Math.round(result.tokens.output / elapsedSec) : 0;
                     }
 
                     if (result.toolCalls && result.toolCalls.length > 0) {
@@ -935,7 +942,7 @@ class ModelMix {
                     // debug level 2: Readable summary of output
                     if (currentConfig.debug >= 2) {
                         const tokenInfo = result.tokens
-                            ? ` ${result.tokens.input} → ${result.tokens.output} tok` + (result.tokens.cost != null ? ` $${result.tokens.cost.toFixed(4)}` : '')
+                            ? ` ${result.tokens.input} → ${result.tokens.output} tok` + (result.tokens.speed ? ` ${result.tokens.speed} t/s` : '') + (result.tokens.cost != null ? ` $${result.tokens.cost.toFixed(4)}` : '')
                             : '';
                         console.log(`✓${tokenInfo}\n${ModelMix.formatOutputSummary(result, currentConfig.debug).trim()}`);
                     }

package/package.json

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

package/skills/modelmix/SKILL.md

@@ -1,41 +1,50 @@
 ---
 name: modelmix
-description: Instructions for using the ModelMix Node.js library to interact with multiple AI LLM providers through a unified interface. Use when integrating AI models (OpenAI, Anthropic, Google, Groq, Perplexity, Grok, etc.), chaining models with fallback, getting structured JSON from LLMs, adding MCP tools, streaming responses, or managing multi-provider AI workflows in Node.js.
+description: Instructions for using the ModelMix Node.js library to interact with multiple AI LLM providers through a unified interface. Use when writing code that calls AI models (OpenAI, Anthropic, Google, Groq, Perplexity, Grok, MiniMax, Fireworks, Together, Lambda, Cerebras, OpenRouter, Ollama, LM Studio), chaining models with fallback, getting structured JSON from LLMs, adding MCP tools, streaming responses, managing multi-provider AI workflows, round-robin load balancing, or rate limiting API requests in Node.js. Also use when the user mentions "modelmix", "ModelMix", asks to "call an LLM", "query a model", "add AI to my app", or wants to integrate any supported provider.
+metadata:
+  tags: [llm, ai, openai, anthropic, google, groq, perplexity, grok, mcp, streaming, json-output]
 ---
 
 # 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.
+ModelMix is a Node.js library providing 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, custom local tools, 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
+- Chaining models with automatic fallback or round-robin
 - Extracting structured JSON from LLMs
 - Adding MCP tools or custom tools to models
+- Streaming responses from any provider
 - Working with templates and file-based prompts
+- Tracking token usage and costs
 
-Do NOT use this skill for:
+Do NOT use for:
 - Python or non-Node.js projects
 - Direct HTTP calls to LLM APIs (use ModelMix instead)
 
-## Common Tasks
+## Quick Reference
 
+- [Installation](#installation)
+- [Creating an instance](#creating-an-instance)
+- [Attaching models](#attaching-models)
 - [Get a text response](#get-a-text-response)
 - [Get structured JSON](#get-structured-json)
 - [Stream a response](#stream-a-response)
-- [Get raw response (tokens, thinking, tool calls)](#get-raw-response-tokens-thinking-tool-calls)
-- [Access full response after `message()` or `json()` with `lastRaw`](#access-full-response-after-message-or-json-with-lastraw)
+- [Extract a code block](#extract-a-code-block)
+- [Get raw response (tokens, thinking, tool calls)](#get-raw-response)
+- [Access full response with lastRaw](#access-full-response-with-lastraw)
 - [Add images](#add-images)
-- [Use templates with placeholders](#use-templates-with-placeholders)
+- [Templates with placeholders](#templates-with-placeholders)
 - [Round-robin load balancing](#round-robin-load-balancing)
-- [MCP integration (external tools)](#mcp-integration-external-tools)
-- [Custom local tools (addTool)](#custom-local-tools-addtool)
-- [Rate limiting (Bottleneck)](#rate-limiting-bottleneck)
-- [Debug mode](#debug-mode)
-- [Use free-tier models](#use-free-tier-models)
+- [MCP integration](#mcp-integration)
+- [Custom local tools](#custom-local-tools)
+- [Rate limiting](#rate-limiting)
 - [Conversation history](#conversation-history)
+- [Debug mode](#debug-mode)
+- [Free-tier models](#free-tier-models)
+- [Multi-provider routing](#multi-provider-routing)
 
 ## Installation
 
@@ -54,49 +63,77 @@ import { ModelMix } from 'modelmix';
 ### Creating an Instance
 
 ```javascript
-// 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 (no truncate), 4=verbose
-        roundRobin: false    // false=fallback, true=rotate models
+        max_history: 5,   // -1 = unlimited, 0 = none (default), N = keep last N
+        debug: 0,          // 0=silent, 1=minimal, 2=summary, 3=full, 4=verbose
+        roundRobin: false  // false=fallback, true=rotate models
     }
 });
 ```
 
-### Attaching Models (Fluent Chain)
+### Attaching Models
 
-Chain shorthand methods to attach providers. First model is primary; others are fallbacks:
+Chain shorthand methods to attach providers. First model is primary; others are fallbacks (or rotated if `roundRobin: true`):
 
 ```javascript
 const model = ModelMix.new()
     .sonnet46()        // primary
-    .gpt52()        // fallback 1
+    .gpt52()           // fallback 1
     .gemini3flash()    // fallback 2
     .addText("Hello!")
 ```
 
-If `sonnet45` fails, it automatically tries `gpt5mini`, then `gemini3flash`.
+If `sonnet46` fails, it automatically tries `gpt52`, then `gemini3flash`.
 
 ## Available Model Shorthands
 
-- **OpenAI**: `gpt52` `gpt51` `gpt5` `gpt5mini` `gpt5nano` `gpt41` `gpt41mini` `gpt41nano`
-- **Anthropic**: `opus46` `opus45` `sonnet46` `sonnet45` `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`
+### OpenAI
+`gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
+
+### Anthropic
+`opus46()` `opus45()` `opus41()` `sonnet46()` `sonnet45()` `sonnet4()` `sonnet37()` `haiku45()` `haiku35()`
+
+Thinking variants: append `think` — e.g. `opus46think()` `sonnet46think()` `sonnet45think()` `sonnet4think()` `sonnet37think()` `opus45think()` `opus41think()` `haiku45think()`
+
+### Google
+`gemini3pro()` `gemini3flash()` `gemini25pro()` `gemini25flash()`
+
+### Grok
+`grok4()` `grok41()` `grok41think()` `grok3()` `grok3mini()`
+
+### Perplexity
+`sonar()` `sonarPro()`
+
+### Groq
+`scout()` `maverick()`
+
+### Together
+`qwen3()` `kimiK2()` `kimiK2think()` `kimiK25think()` `gptOss()`
+
+### MiniMax
+`minimaxM25()` `minimaxM21()` `minimaxM2()` `minimaxM2Stable()`
+
+### Fireworks
+`deepseekV32()` `GLM5()` `GLM47()`
+
+### Cerebras
+`GLM46()`
+
+### OpenRouter
+`GLM45()`
+
+### Multi-provider (auto-fallback across free/paid tiers)
+`deepseekR1()` `hermes3()` `scout()` `maverick()` `kimiK2()` `GLM47()`
 
-Each method is called as `mix.methodName()` and accepts optional `{ options, config }` to override per-model settings.
+### Local
+`lmstudio()` — for LM Studio local models
+
+Each method accepts optional `{ options, config }` to override per-model settings.
 
 ## Common Tasks
 
@@ -116,35 +153,30 @@ 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
+        { countries: [{ name: "", capital: "" }] },
+        { countries: [{ name: "country name", capital: "in uppercase" }] },
+        { addNote: true }
     );
-// result.countries → [{ name: "Brazil", capital: "BRASILIA" }, ...]
 ```
 
 `json()` signature: `json(schemaExample, schemaDescription?, { addSchema, addExample, addNote }?)`
 
 #### Enhanced descriptors
 
-Descriptions can be **strings** or **descriptor objects** with metadata:
+Descriptions can be strings or descriptor objects with metadata:
 
 ```javascript
 const result = await model.json(
     { name: 'martin', age: 22, sex: 'Male' },
     {
         name: { description: 'Name of the actor', required: false },
-        age: 'Age of the actor',                                     // string still works
+        age: 'Age of the actor',
         sex: { description: 'Gender', enum: ['Male', 'Female', null] }
     }
 );
 ```
 
-Descriptor properties:
-- `description` (string) — field description
-- `required` (boolean, default `true`) — if `false`: removed from required array, type becomes nullable
-- `enum` (array) — allowed values; if includes `null`, type auto-becomes nullable
-- `default` (any) — default value
+Descriptor properties: `description` (string), `required` (boolean, default true — if false, field becomes nullable), `enum` (array — if includes null, type auto-becomes nullable), `default` (any).
 
 #### Array auto-wrap
 
@@ -166,7 +198,19 @@ await ModelMix.new()
     });
 ```
 
-### Get raw response (tokens, thinking, tool calls)
+### Extract a code block
+
+```javascript
+const code = await ModelMix.new()
+    .gpt5mini()
+    .addText("Write a hello world function in JavaScript.")
+    .block();
+// Returns only the content inside the first code block
+```
+
+`block()` accepts `{ addSystemExtra }` (default true) — adds system instructions that tell the model to wrap output in a code block.
+
+### Get raw response
 
 ```javascript
 const raw = await ModelMix.new()
@@ -176,15 +220,15 @@ const raw = await ModelMix.new()
 // raw.message, raw.think, raw.tokens, raw.toolCalls, raw.response
 ```
 
-### Access full response after `message()` or `json()` with `lastRaw`
+### Access full response 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()`.
+After calling `message()`, `json()`, `block()`, or `stream()`, use `lastRaw` to access the complete response:
 
 ```javascript
 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 }
+// { input: 122, output: 86, total: 541, cost: 0.000319, speed: 38 }
 console.log(model.lastRaw.think);    // reasoning content (if available)
 console.log(model.lastRaw.response); // raw API response
 ```
@@ -193,13 +237,16 @@ console.log(model.lastRaw.response); // raw API response
 
 ```javascript
 const model = ModelMix.new().sonnet45();
-model.addImage('./photo.jpg');                         // from file
-model.addImageFromUrl('https://example.com/img.png');  // from URL
+model.addImage('./photo.jpg');                          // from file
+model.addImageFromUrl('https://example.com/img.png');   // from URL
+model.addImageFromBuffer(imageBuffer);                  // from Buffer
 model.addText('Describe this image.');
 const description = await model.message();
 ```
 
-### Use templates with placeholders
+All image methods accept an optional second argument `{ role }` (default `"user"`).
+
+### Templates with placeholders
 
 ```javascript
 const model = ModelMix.new().gpt5mini();
@@ -221,12 +268,11 @@ const pool = ModelMix.new({ config: { roundRobin: true } })
     .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)
+### MCP integration
 
 ```javascript
 const model = ModelMix.new({ config: { max_history: 10 } }).gpt5nano();
@@ -238,7 +284,7 @@ console.log(await model.message());
 
 Requires `BRAVE_API_KEY` in `.env` for Brave Search MCP.
 
-### Custom local tools (addTool)
+### Custom local tools
 
 ```javascript
 const model = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();
@@ -259,7 +305,18 @@ model.addText("What's the weather in Tokyo?");
 console.log(await model.message());
 ```
 
-### Rate limiting (Bottleneck)
+Register multiple tools at once:
+
+```javascript
+model.addTools([
+    { tool: { name: "tool_a", description: "...", inputSchema: {...} }, callback: async (args) => {...} },
+    { tool: { name: "tool_b", description: "...", inputSchema: {...} }, callback: async (args) => {...} }
+]);
+```
+
+Manage tools: `model.removeTool("tool_a")` and `model.listTools()` → `{ local, mcp }`.
+
+### Rate limiting
 
 ```javascript
 const model = ModelMix.new({
@@ -272,20 +329,31 @@ const model = ModelMix.new({
 }).gpt5mini();
 ```
 
+### Conversation history
+
+```javascript
+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"
+```
+
+`max_history`: 0 = no history (default), N = keep last N exchanges, -1 = unlimited.
+
 ### Debug mode
 
 ```javascript
 const model = ModelMix.new({
-    config: { debug: 2 }  // 0=silent, 1=minimal, 2=summary, 3=full (no truncate), 4=verbose
+    config: { debug: 2 }  // 0=silent, 1=minimal, 2=summary, 3=full, 4=verbose
 }).gpt5mini();
 ```
 
-For full debug output, also set the env: `DEBUG=ModelMix* node script.js`
+For full debug output, also set: `DEBUG=ModelMix* node script.js`
 
-### Use free-tier models
+### Free-tier models
 
 ```javascript
-// These use providers with free quotas (OpenRouter, Groq, Cerebras)
 const model = ModelMix.new()
     .gptOss()
     .kimiK2()
@@ -295,48 +363,61 @@ const model = ModelMix.new()
 console.log(await model.message());
 ```
 
-### Conversation history
+These use providers with free quotas (OpenRouter, Groq, Cerebras). If one runs out of quota, ModelMix falls back to the next.
+
+### Multi-provider routing
+
+Some model shorthands register the same model across multiple providers for maximum resilience. Control which providers are enabled via the `mix` parameter:
 
 ```javascript
-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"
+const model = ModelMix.new({
+    mix: {
+        openrouter: true,   // default: true
+        cerebras: true,      // default: true
+        groq: true,          // default: true
+        together: false,     // default: false
+        lambda: false,       // default: false
+        minimax: false,      // default: false
+        fireworks: false     // default: false
+    }
+}).deepseekR1();
 ```
 
 ## Agent Usage Rules
 
-- Always check `package.json` for `modelmix` before running `npm install`.
-- Use `ModelMix.new()` static factory to create instances (not `new ModelMix()`).
+- Check `package.json` for `modelmix` before running `npm install`.
+- Use `ModelMix.new()` static factory (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 descriptor objects `{ description, required, enum, default }` in descriptions for richer schema control.
+- 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 `.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`.
+- The library uses CommonJS internally but supports ESM import via `{ ModelMix }`.
+- GPT-5+ models automatically use `max_completion_tokens` instead of `max_tokens`.
+- o-series models (o3, o4mini) automatically strip `max_tokens` and `temperature` since those APIs don't support them.
+- `addText()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()` all accept `{ role }` as second argument (default `"user"`).
 
 ## API Quick Reference
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `.addText(text)` | `this` | Add user message |
-| `.addTextFromFile(path)` | `this` | Add user message from file |
+| `.addText(text, {role?})` | `this` | Add user message |
+| `.addTextFromFile(path, {role?})` | `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 |
+| `.addImage(path, {role?})` | `this` | Add image from file |
+| `.addImageFromUrl(url, {role?})` | `this` | Add image from URL or data URI |
+| `.addImageFromBuffer(buffer, {role?})` | `this` | Add image from Buffer |
 | `.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\|array>` | Get structured JSON. Descriptions support descriptor objects `{ description, required, enum, default }`. Top-level arrays auto-wrapped |
+| `.json(example, desc?, opts?)` | `Promise<object\|array>` | Get structured JSON |
 | `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |
-| `.lastRaw` | `object \| null` | Full response from last `message()`/`json()`/`block()`/`stream()` call |
+| `.lastRaw` | `object \| null` | Full response from last call |
 | `.stream(callback)` | `Promise` | Stream response |
-| `.block()` | `Promise<string>` | Extract code block from response |
+| `.block({addSystemExtra?})` | `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 |
@@ -345,6 +426,30 @@ const reply = await chat.message();  // "Martin"
 | `.new()` | `ModelMix` | Clone instance sharing models |
 | `.attach(key, provider)` | `this` | Attach custom provider |
 
+## Available Provider Classes
+
+`MixOpenAI` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixMiniMax` `MixLambda`
+
+## Troubleshooting
+
+**Model fails with "API key not found"**
+The provider's API key env var is not set. Add it to `.env` and ensure it loads before ModelMix runs. Each provider looks for its standard env var (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`).
+
+**Tool calls not working**
+Set `max_history` to at least 3. Tool call/response pairs are stored in history and the model needs to see them to complete the conversation loop.
+
+**JSON response parsing fails**
+Add `{ addNote: true }` to the `json()` options — this injects instructions about JSON escaping that prevent common parsing errors. For complex schemas, also try `{ addExample: true }`.
+
+**Model returns empty or truncated response**
+Increase `max_tokens` in options. Default is 8192 but some tasks need more. For GPT-5+ models, `max_completion_tokens` is used automatically.
+
+**Rate limit errors**
+Configure Bottleneck: `config: { bottleneck: { maxConcurrent: 2, minTime: 2000 } }`. This throttles requests to stay within provider limits.
+
+**MCP server fails to connect**
+Ensure the MCP package is installed (`npm install @modelcontextprotocol/server-brave-search`) and required env vars are set. Call `addMCP()` with `await` — it's async.
+
 ## References
 
 - [GitHub Repository](https://github.com/clasen/ModelMix)