modelmix 4.4.14 → 4.4.16

package/README.md

@@ -135,9 +135,10 @@ Here's a comprehensive list of available methods:
 
 | Method             | Provider   | Model                          | Price (I/O) per 1 M tokens |
 | ------------------ | ---------- | ------------------------------ | -------------------------- |
+| `gpt54()`          | OpenAI     | gpt-5.4                        | [\$2.50 / \$15.00][1]      |
 | `gpt52()`          | OpenAI     | gpt-5.2                        | [\$1.75 / \$14.00][1]      |
 | `gpt51()`          | OpenAI     | gpt-5.1                        | [\$1.25 / \$10.00][1]      |
-| `gpt5()`           | OpenAI     | gpt-5                          | [\$1.25 / \$10.00][1]      |
+| `gpt53codex()`     | OpenAI     | gpt-5.3-codex                  | [\$1.25 / \$14.00][1]      |
 | `gpt5mini()`       | OpenAI     | gpt-5-mini                     | [\$0.25 / \$2.00][1]       |
 | `gpt5nano()`       | OpenAI     | gpt-5-nano                     | [\$0.05 / \$0.40][1]       |
 | `gpt41()`          | OpenAI     | gpt-4.1                        | [\$2.00 / \$8.00][1]       |

package/demo/gemini.js

@@ -1,5 +1,5 @@
 import { ModelMix, MixGoogle } from '../index.js';
-try { process.loadEnvFile(); } catch {}
+try { process.loadEnvFile(); } catch { }
 
 const mmix = new ModelMix({
     options: {
@@ -12,9 +12,9 @@ const mmix = new ModelMix({
     }
 });
 
-// Using gemini25flash (Gemini 2.5 Flash) with built-in method
+// Using gemini3flash (Gemini 3 Flash) with built-in method
 console.log("\n" + '--------| gemini25flash() |--------');
-const flash = await mmix.gemini25flash()
+const flash = await mmix.gemini3flash()
     .addText('Hi there! Do you like cats?')
     .message();
 
@@ -22,20 +22,23 @@ console.log(flash);
 
 // Using gemini3pro (Gemini 3 Pro) with custom config
 console.log("\n" + '--------| gemini3pro() with JSON response |--------');
-const pro = mmix.new().gemini3pro();
+const pro = mmix.new().gemini31pro();
 
 pro.addText('Give me a fun fact about cats');
-const jsonResponse = await pro.json({ 
+
+const jsonExampleAndSchema = {
     fact: 'A fun fact about cats',
-    category: 'animal behavior' 
-});
+    category: 'animal behavior'
+};
+
+const jsonResponse = await pro.json(jsonExampleAndSchema, jsonExampleAndSchema);
 
 console.log(jsonResponse);
 
 // Using attach method with MixGoogle for custom model
 console.log("\n" + '--------| Custom Gemini with attach() |--------');
-mmix.attach('gemini-2.5-flash', new MixGoogle());
+const customModel = mmix.new().attach('gemini-2.5-flash', new MixGoogle());
 
-const custom = await mmix.addText('Tell me a short joke about cats.').message();
+const custom = await customModel.addText('Tell me a short joke about cats.').message();
 console.log(custom);
 

package/demo/gpt-realtime.js

@@ -0,0 +1,22 @@
+import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
+const mmix = new ModelMix({
+    config: {
+        debug: 3
+    }
+});
+
+console.log('\n--------| gptRealtime() |--------');
+
+const realtime = mmix.gptRealtimeMini({
+    options: {
+        stream: true
+    }
+});
+
+realtime.addText('Explain quantum entanglement in simple terms.');
+const response = await realtime.stream(({ delta }) => {
+    process.stdout.write(delta || '');
+});
+console.log('\n\n[done]\n', response.tokens);

package/demo/{gpt51.js → gpt54.js}

@@ -8,10 +8,10 @@ const mmix = new ModelMix({
     }
 });
 
-console.log("\n" + '--------| gpt51() |--------');
+console.log("\n" + '--------| gpt54() |--------');
 
 const gptArgs = { options: { reasoning_effort: "none", verbosity: "low" } };  
-const gpt = mmix.gpt51(gptArgs);
+const gpt = mmix.gpt54(gptArgs);
 
 gpt.addText("Explain quantum entanglement in simple terms.");
 const response = await gpt.message();

package/index.js

@@ -5,6 +5,7 @@ const { inspect } = require('util');
 const log = require('lemonlog')('ModelMix');
 const Bottleneck = require('bottleneck');
 const path = require('path');
+const WebSocket = require('ws');
 const generateJsonSchema = require('./schema');
 const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
@@ -14,6 +15,11 @@ const { MCPToolsManager } = require('./mcp-tools');
 // Based on provider pricing pages linked in README
 const MODEL_PRICING = {
     // OpenAI
+    'gpt-realtime-mini': [0.60, 2.40],
+    'gpt-realtime': [4.00, 16.00],
+    'gpt-5.4': [2.50, 15.00],
+    'gpt-5.4-pro': [30, 180.00],
+    'gpt-5.3-codex': [1.75, 14.00],
     'gpt-5.2': [1.75, 14.00],
     'gpt-5.2-chat-latest': [1.75, 14.00],
     'gpt-5.1': [1.25, 10.00],
@@ -268,6 +274,21 @@ class ModelMix {
     gpt52({ options = {}, config = {} } = {}) {
         return this.attach('gpt-5.2', new MixOpenAI({ options, config }));
     }
+    gpt54({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-5.4', new MixOpenAIResponses({ options, config }));
+    }
+    gpt54pro({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-5.4-pro', new MixOpenAIResponses({ options, config }));
+    }          
+    gptRealtime({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-realtime', new MixOpenAIWebSocket({ options, config }));
+    }
+    gptRealtimeMini({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-realtime-mini', new MixOpenAIWebSocket({ options, config }));
+    }
+    gpt53codex({ options = {}, config = {} } = {}) {
+        return this.attach('gpt-5.3-codex', new MixOpenAIResponses({ options, config }));
+    }          
     gpt52chat({ options = {}, config = {} } = {}) {
         return this.attach('gpt-5.2-chat-latest', new MixOpenAI({ options, config }));
     }
@@ -1499,6 +1520,339 @@ class MixOpenAI extends MixCustom {
     }
 }
 
+class MixOpenAIResponses extends MixOpenAI {
+    async create({ config = {}, options = {} } = {}) {
+
+        // Keep GPT/o-model option normalization behavior
+        if (options.model?.startsWith('o')) {
+            delete options.max_tokens;
+            delete options.temperature;
+        }
+        if (options.model?.includes('gpt-5')) {
+            if (options.max_tokens) {
+                options.max_completion_tokens = options.max_tokens;
+                delete options.max_tokens;
+            }
+            delete options.temperature;
+        }
+
+        const responsesUrl = this.config.url.replace('/chat/completions', '/responses');
+        const request = MixOpenAIResponses.buildResponsesRequest(options);
+        const response = await axios.post(responsesUrl, request, {
+            headers: this.headers
+        });
+
+        return MixOpenAIResponses.processResponsesResponse(response);
+    }
+
+    static buildResponsesRequest(options = {}) {
+        const request = {
+            model: options.model,
+            input: MixOpenAIResponses.messagesToResponsesInput(options.messages),
+            stream: false
+        };
+
+        if (options.reasoning_effort) request.reasoning = { effort: options.reasoning_effort };
+        if (options.verbosity) request.text = { verbosity: options.verbosity };
+
+        if (typeof options.max_completion_tokens === 'number') {
+            request.max_output_tokens = options.max_completion_tokens;
+        } else if (typeof options.max_tokens === 'number') {
+            request.max_output_tokens = options.max_tokens;
+        }
+
+        if (typeof options.temperature === 'number') request.temperature = options.temperature;
+        if (typeof options.top_p === 'number') request.top_p = options.top_p;
+        if (typeof options.presence_penalty === 'number') request.presence_penalty = options.presence_penalty;
+        if (typeof options.frequency_penalty === 'number') request.frequency_penalty = options.frequency_penalty;
+        if (options.stop !== undefined) request.stop = options.stop;
+        if (typeof options.n === 'number') request.n = options.n;
+        if (options.logit_bias !== undefined) request.logit_bias = options.logit_bias;
+        if (options.user !== undefined) request.user = options.user;
+
+        return request;
+    }
+
+    static processResponsesResponse(response) {
+        const message = MixOpenAIResponses.extractResponsesMessage(response.data);
+        return {
+            message,
+            think: null,
+            toolCalls: [],
+            tokens: MixOpenAIResponses.extractResponsesTokens(response.data),
+            response: response.data
+        };
+    }
+
+    static extractResponsesTokens(data) {
+        if (data.usage) {
+            return {
+                input: data.usage.input_tokens || 0,
+                output: data.usage.output_tokens || 0,
+                total: data.usage.total_tokens || ((data.usage.input_tokens || 0) + (data.usage.output_tokens || 0))
+            };
+        }
+        return {
+            input: 0,
+            output: 0,
+            total: 0
+        };
+    }
+
+    static extractResponsesMessage(data) {
+        if (!Array.isArray(data.output)) return '';
+        return data.output
+            .filter(item => item.type === 'message')
+            .flatMap(item => Array.isArray(item.content) ? item.content : [])
+            .filter(content => content.type === 'output_text' && typeof content.text === 'string')
+            .map(content => content.text)
+            .join('\n')
+            .trim();
+    }
+
+    static messagesToResponsesInput(messages = []) {
+        const mapped = [];
+
+        for (const message of messages) {
+            if (!message || !message.role) continue;
+            if (message.tool_calls || message.role === 'tool') continue;
+
+            let text = '';
+            if (typeof message.content === 'string') {
+                text = message.content;
+            } else if (Array.isArray(message.content)) {
+                text = message.content
+                    .filter(item => item && item.type === 'text' && typeof item.text === 'string')
+                    .map(item => item.text)
+                    .join('\n');
+            }
+
+            if (!text) continue;
+            mapped.push({
+                role: message.role,
+                content: [{ type: 'input_text', text }]
+            });
+        }
+
+        return mapped;
+    }
+}
+
+class MixOpenAIWebSocket extends MixOpenAIResponses {
+    getDefaultConfig(customConfig) {
+        return super.getDefaultConfig({
+            realtimeUrl: 'wss://api.openai.com/v1/realtime',
+            websocketTimeoutMs: 120000,
+            ...customConfig
+        });
+    }
+
+    async create({ config = {}, options = {} } = {}) {
+        if (options.model?.startsWith('o')) {
+            delete options.max_tokens;
+            delete options.temperature;
+        }
+        if (options.model?.includes('gpt-5')) {
+            if (options.max_tokens) {
+                options.max_completion_tokens = options.max_tokens;
+                delete options.max_tokens;
+            }
+            delete options.temperature;
+        }
+
+        const mergedConfig = { ...this.config, ...config };
+        const realtimeUrl = `${mergedConfig.realtimeUrl}?model=${encodeURIComponent(options.model)}`;
+        const timeoutMs = mergedConfig.websocketTimeoutMs || 120000;
+
+        return await new Promise((resolve, reject) => {
+            const ws = new WebSocket(realtimeUrl, {
+                headers: {
+                    authorization: `Bearer ${mergedConfig.apiKey}`
+                }
+            });
+
+            const events = [];
+            let message = '';
+            let settled = false;
+            let finalResponse = null;
+
+            const timeout = setTimeout(() => {
+                if (settled) return;
+                settled = true;
+                ws.close();
+                reject({
+                    message: `Realtime WebSocket timed out after ${timeoutMs}ms`,
+                    statusCode: null,
+                    details: null,
+                    config: mergedConfig,
+                    options
+                });
+            }, timeoutMs);
+
+            const cleanUp = () => clearTimeout(timeout);
+
+            ws.on('open', () => {
+                const session = {
+                    type: 'realtime',
+                    output_modalities: ['text']
+                };
+
+                if (mergedConfig.system) session.instructions = mergedConfig.system;
+                if (Array.isArray(options.tools) && options.tools.length > 0) {
+                    session.tools = options.tools;
+                }
+
+                ws.send(JSON.stringify({ type: 'session.update', session }));
+
+                const items = MixOpenAIWebSocket.messagesToConversationItems(options.messages);
+                for (const item of items) {
+                    ws.send(JSON.stringify({
+                        type: 'conversation.item.create',
+                        item
+                    }));
+                }
+
+                const responseConfig = { output_modalities: ['text'] };
+                if (typeof options.max_completion_tokens === 'number') {
+                    responseConfig.max_output_tokens = Math.min(options.max_completion_tokens, 4096);
+                } else if (typeof options.max_tokens === 'number') {
+                    responseConfig.max_output_tokens = Math.min(options.max_tokens, 4096);
+                }
+                if (Array.isArray(options.tools) && options.tools.length > 0) responseConfig.tools = options.tools;
+
+                ws.send(JSON.stringify({
+                    type: 'response.create',
+                    response: responseConfig
+                }));
+            });
+
+            ws.on('message', raw => {
+                let event;
+                try {
+                    event = JSON.parse(raw.toString());
+                } catch {
+                    return;
+                }
+
+                events.push(event);
+
+                const isTextDeltaEvent = event.type === 'response.text.delta' || event.type === 'response.output_text.delta';
+                if (isTextDeltaEvent) {
+                    const delta = MixOpenAIWebSocket.extractDelta(event);
+                    if (delta) {
+                        message += delta;
+                        if (this.streamCallback) {
+                            this.streamCallback({ response: event, message, delta });
+                        }
+                    }
+                    return;
+                }
+
+                if (event.type === 'response.done') {
+                    finalResponse = event.response || null;
+                    if (!message && finalResponse) {
+                        message = MixOpenAIResponses.extractResponsesMessage(finalResponse);
+                    }
+
+                    if (!settled) {
+                        settled = true;
+                        cleanUp();
+                        ws.close();
+                        resolve({
+                            message: message.trim(),
+                            think: null,
+                            toolCalls: [],
+                            tokens: MixOpenAIResponses.extractResponsesTokens(finalResponse || {}),
+                            response: {
+                                response: finalResponse,
+                                events
+                            }
+                        });
+                    }
+                    return;
+                }
+
+                if (event.type === 'error' && !settled) {
+                    settled = true;
+                    cleanUp();
+                    ws.close();
+                    reject({
+                        message: event.error?.message || 'Realtime WebSocket error',
+                        statusCode: null,
+                        details: event.error || event,
+                        config: mergedConfig,
+                        options
+                    });
+                }
+            });
+
+            ws.on('error', error => {
+                if (settled) return;
+                settled = true;
+                cleanUp();
+                reject({
+                    message: error.message || 'Realtime WebSocket connection error',
+                    statusCode: null,
+                    details: null,
+                    stack: error.stack,
+                    config: mergedConfig,
+                    options
+                });
+            });
+
+            ws.on('close', () => {
+                if (settled) return;
+                settled = true;
+                cleanUp();
+                reject({
+                    message: 'Realtime WebSocket closed before response.done',
+                    statusCode: null,
+                    details: null,
+                    config: mergedConfig,
+                    options
+                });
+            });
+        });
+    }
+
+    static messagesToConversationItems(messages = []) {
+        const items = [];
+
+        for (const message of messages) {
+            if (!message || !message.role) continue;
+            if (message.role === 'tool' || message.tool_calls) continue;
+
+            const role = message.role === 'assistant' ? 'assistant' : (message.role === 'system' ? 'system' : 'user');
+            const content = [];
+
+            if (typeof message.content === 'string') {
+                content.push({
+                    type: role === 'assistant' ? 'text' : 'input_text',
+                    text: message.content
+                });
+            } else if (Array.isArray(message.content)) {
+                for (const item of message.content) {
+                    if (!item || item.type !== 'text' || typeof item.text !== 'string') continue;
+                    content.push({
+                        type: role === 'assistant' ? 'text' : 'input_text',
+                        text: item.text
+                    });
+                }
+            }
+
+            if (content.length === 0) continue;
+            items.push({ type: 'message', role, content });
+        }
+
+        return items;
+    }
+
+    static extractDelta(event) {
+        if (typeof event.delta === 'string') return event.delta;
+        return '';
+    }
+}
+
 class MixOpenRouter extends MixOpenAI {
     getDefaultConfig(customConfig) {
 
@@ -2273,4 +2627,4 @@ class MixGoogle extends MixCustom {
     }
 }
 
-module.exports = { MixCustom, ModelMix, MixAnthropic, MixMiniMax, MixOpenAI, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks };
+module.exports = { MixCustom, ModelMix, MixAnthropic, MixMiniMax, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.4.14",
+  "version": "4.4.16",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -16,7 +16,7 @@
     "openai",
     "anthropic",
     "agent",
-    "grok4",
+    "realtime",
     "gpt",
     "claude",
     "llama",
@@ -47,16 +47,17 @@
   },
   "homepage": "https://github.com/clasen/ModelMix#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.13.5",
     "bottleneck": "^2.19.5",
     "file-type": "^16.5.4",
     "form-data": "^4.0.4",
-    "lemonlog": "^1.2.0"
+    "lemonlog": "^1.2.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "chai": "^5.2.1",
-    "mocha": "^11.3.0",
+    "mocha": "^11.7.5",
     "nock": "^14.0.9",
     "sinon": "^21.0.0"
   },

package/demo/save_the_cat-spanish.md

@@ -1,109 +0,0 @@
-## 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/story.md

@@ -1,15 +0,0 @@
-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.