gptrans 2.2.0 → 2.2.4

package/.agents/skills/modelmix/SKILL.md

@@ -66,10 +66,18 @@ const model = ModelMix.new()
 
 If `sonnet45` fails, it automatically tries `gpt5mini`, then `gemini3flash`.
 
+The equivalent `chain()` syntax accepts `shortcut@<effort>` to override unified effort for one model. `<effort>` must be an integer from `0` to `100`; models without the suffix keep their configured or provider-default effort:
+
+```javascript
+const model = ModelMix.new()
+    .chain('sonnet5@50', 'gpt56luna@100');
+```
+
 ## Available Model Shorthands
 
 - **OpenAI**: `gpt52` `gpt51` `gpt5` `gpt5mini` `gpt5nano` `gpt41` `gpt41mini` `gpt41nano`
-- **Anthropic**: `opus46` `opus45` `sonnet45` `sonnet4` `haiku45` `haiku35` (thinking variants: add `think` suffix)
+- **Anthropic**: `opus46` `opus45` `sonnet5` `sonnet45` `sonnet4` `haiku45` `haiku35` (thinking variants: add `think` suffix)
+- **OpenAI Codex**: `gpt56sol` `gpt56terra` `gpt56luna`
 - **Google**: `gemini3pro` `gemini3flash` `gemini25pro` `gemini25flash`
 - **Grok**: `grok4` `grok41` (thinking variant available)
 - **Perplexity**: `sonar` `sonarPro`
@@ -158,11 +166,11 @@ const description = await model.message();
 const model = ModelMix.new().gpt5mini();
 model.setSystemFromFile('./prompts/system.md');
 model.addTextFromFile('./prompts/task.md');
-model.replace({
-    '{role}': 'data analyst',
-    '{language}': 'Spanish'
+model.assign({
+    role: 'data analyst',
+    language: 'Spanish'
 });
-model.replaceKeyFromFile('{code}', './src/utils.js');
+model.assignKeyFromFile('code', './src/utils.js');
 console.log(await model.message());
 ```
 
@@ -268,7 +276,7 @@ const reply = await chat.message();  // "Martin"
 - Use `.json()` for structured output instead of parsing text manually.
 - Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
 - For thinking models, append `think` to the method name (e.g. `sonnet45think()`).
-- Template placeholders use `{key}` syntax in both system prompts and user messages.
+- Template placeholders use EJS syntax such as `<%- key %>` in 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`.
 
@@ -282,8 +290,9 @@ const reply = await chat.message();  // "Martin"
 | `.setSystemFromFile(path)` | `this` | Set system prompt from file |
 | `.addImage(path)` | `this` | Add image from file |
 | `.addImageFromUrl(url)` | `this` | Add image from URL or data URI |
-| `.replace({})` | `this` | Set placeholder replacements |
-| `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
+| `.assign({})` | `this` | Assign EJS template data |
+| `.assignKeyFromFile(key, path)` | `this` | Assign rendered file content to one template key |
+| `.chain(...models)` | `this` | Attach ordered shortcuts; each may use `@<effort>` from `0` to `100` |
 | `.message()` | `Promise<string>` | Get text response |
 | `.json(example, desc?, opts?)` | `Promise<object>` | Get structured JSON |
 | `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |

package/README.md

@@ -30,7 +30,7 @@ npm install gptrans
 
 ### 🌐 Environment Setup
 
-On Node.js 20.6+, GPTrans loads a `.env` from the current working directory via `process.loadEnvFile()` when you construct `GPTrans` (missing or invalid files are ignored). Create a `.env` in your project root and add your API keys:
+GPTrans reads provider credentials from `process.env` and does not load `.env` files itself. If you use a `.env` file, load it in your application before constructing `GPTrans`. Create the file in your project root and add your API keys:
 
 ```env
 OPENAI_API_KEY=your_openai_api_key
@@ -44,13 +44,15 @@ Here's a simple example to get you started:
 
 ```javascript
 import GPTrans from 'gptrans';
+import { join } from 'node:path';
+import { loadEnvFile } from 'node:process';
 
-const dbPath = new URL('./db', import.meta.url).pathname;
+loadEnvFile(join(import.meta.dirname, '.env'));
+const dbPath = join(import.meta.dirname, 'db');
 const gptrans = new GPTrans({
   path: dbPath,
   from: 'en-US',
-  target: 'es-AR',
-  model: 'sonnet45'
+  target: 'es-AR'
 });
 
 // Translate text with parameter substitution
@@ -79,7 +81,7 @@ When creating a new instance of GPTrans, you can customize:
 | `path` | Absolute directory path for the DeepBase translation cache | Required |
 | `from` | Source language locale (BCP 47) | `en-US` |
 | `target` | Target language locale (BCP 47) | `es` |
-| `model` | Translation model key or array of models for fallback | `sonnet45` `gpt41` |
+| `model` | ModelMix shortcut or array for an ordered fallback chain; append `@<effort>` (`0`–`100`) to override one model | `['sonnet5@50', 'gpt56luna@100']` |
 | `batchThreshold` | Maximum number of characters to accumulate before triggering batch processing | `1500` |
 | `debounceTimeout` | Time in milliseconds to wait before processing translations | `500` |
 | `instruction` | Additional instruction for the translator (e.g., tone, style). Does not affect the cache key | `''` |
@@ -241,7 +243,7 @@ GPTrans supports a fallback mechanism for translation models. Instead of providi
 ```javascript
 const translator = new GPTrans({
   path: dbPath,
-  model: ['claude46', 'gpt54'],
+  model: ['sonnet5@50', 'gpt56luna@100'],
   // ... other options
 });
 ```
@@ -249,6 +251,7 @@ const translator = new GPTrans({
 When using multiple models:
 - The first model in the array is used as the primary translation service
 - If the primary model fails (due to API errors, rate limits, etc.), GPTrans automatically falls back to the next model
+- Use `model@<effort>` with an integer from `0` to `100` to set ModelMix's unified effort for that model only. By default, `sonnet5` uses effort `50`; if it fails, `gpt56luna` uses effort `100`. Models without the suffix keep their configured or provider-default effort.
 - This ensures higher availability and resilience of your translation service
 
 ## ✏️ Refining Translations

package/demo/case_1.js

@@ -1,6 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 const gptrans = new GPTrans({ path: dbPath, model: 'sonnet45' });
 
 console.log(gptrans.t('Hello, {name}!', { name: 'Anya' }));
@@ -30,7 +32,7 @@ const ar2es = new GPTrans({
     path: dbPath,
     from: 'es-AR',
     target: 'es-ES',
-    model: 'gpt41'
+    model: 'gpt56terra@20'
 });
 
 console.log(ar2es.t('¿Tenés fuego?'));

package/demo/case_2.js

@@ -1,6 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 try {
     const gptrans = new GPTrans({

package/demo/case_3.js

@@ -1,6 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 try {
     const gptrans = new GPTrans({

package/demo/case_4.js

@@ -1,16 +1,14 @@
 import GPTrans from '../index.js';
-import { dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { promises as fs } from 'fs';
 
-// Get current file directory
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 // Initialize translator
 const model = new GPTrans({
     path: dbPath,
-    model: ['sonnet46', 'gpt54'],
+    model: ['sonnet50', 'gpt56luna@80'],
     from: 'es',  // Assuming the source file is in Spanish
     target: 'en',
 });
@@ -19,10 +17,9 @@ const model = new GPTrans({
 await model.preload();
 
 // Read and translate the file
-const filePath = `${__dirname}/georgia_incident.md`;
+const filePath = join(import.meta.dirname, 'georgia_incident.md');
 const content = await fs.readFile(filePath, 'utf-8');
 
 // Translate the content
 const translatedContent = model.t(content);
 console.log(translatedContent);
-

package/demo/case_language_info.js

@@ -1,6 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 // Ejemplo: Cómo obtener la información completa del idioma
 

package/demo/case_parallelism.js

@@ -1,16 +1,9 @@
 import GPTrans from '../index.js';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { join } from 'path';
 
 // Cargar .env desde la carpeta demo
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const dbPath = new URL('../db', import.meta.url).pathname;
-try {
-    process.loadEnvFile(join(__dirname, '.env'));
-} catch {
-    /* optional .env missing or unreadable */
-}
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 console.log('🚀 Prueba de Paralelismo en GPTrans');
 console.log('⚠️  Múltiples instancias con MISMO NOMBRE y MISMO PAR DE IDIOMAS\n');

package/demo/case_references.js

@@ -1,16 +1,9 @@
 import GPTrans from '../index.js';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { join } from 'path';
 
 // Load .env from demo folder
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const dbPath = new URL('../db', import.meta.url).pathname;
-try {
-    process.loadEnvFile(join(__dirname, '.env'));
-} catch {
-    /* optional .env missing or unreadable */
-}
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 console.log('🚀 Testing GPTrans with Reference Translations\n');
 console.log('='.repeat(70));

package/demo/case_refine.js

@@ -1,6 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const dbPath = new URL('../db', import.meta.url).pathname;
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 console.log('🚀 Testing GPTrans Refine\n');
 console.log('='.repeat(70));

package/demo/example-image-translation.js

@@ -2,16 +2,12 @@
 import GPTrans from '../index.js';
 import path from 'path';
 import fs from 'fs';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
 
 async function main() {
     try {
         // Initialize GPTrans with Spanish as target
         const gptrans = new GPTrans({
-            path: path.join(__dirname, 'db'),
+            path: path.join(import.meta.dirname, 'db'),
             from: 'en-US',
             target: 'es'
         });
@@ -24,7 +20,7 @@ async function main() {
         console.log('   Input: en/image.jpg');
         console.log('   Expected output: es/image.jpg (sibling folder)\n');
 
-        const imageInLangFolder = path.join(__dirname, 'en', 'camera_4126.jpg');
+        const imageInLangFolder = path.join(import.meta.dirname, 'en', 'camera_4126.jpg');
         if (fs.existsSync(imageInLangFolder)) {
             const result1 = await gptrans.img(imageInLangFolder);
             console.log('   Result:', result1);
@@ -39,7 +35,7 @@ async function main() {
         // console.log('   Input: ./image.jpg');
         // console.log('   Expected output: ./es/image.jpg (subfolder)\n');
 
-        // const imageInRoot = path.join(__dirname, 'camera_4126.jpg');
+        // const imageInRoot = path.join(import.meta.dirname, 'camera_4126.jpg');
         // if (fs.existsSync(imageInRoot)) {
         //     const result2 = await gptrans.img(imageInRoot);
         //     console.log('   Result:', result2);
@@ -54,7 +50,7 @@ async function main() {
         // console.log('   Input: images/photo.jpg');
         // console.log('   Expected output: images/es/photo.jpg (subfolder)\n');
 
-        // const imageInCustomFolder = path.join(__dirname, 'images', 'photo.jpg');
+        // const imageInCustomFolder = path.join(import.meta.dirname, 'images', 'photo.jpg');
         // if (fs.existsSync(imageInCustomFolder)) {
         //     const result3 = await gptrans.img(imageInCustomFolder);
         //     console.log('   Result:', result3);

package/index.js

@@ -7,15 +7,20 @@ import { GeminiGenerator } from 'genmix';
 import fs from 'fs';
 import pathModule from 'path';
 
+const TRANSLATE_PROMPT_FILE = pathModule.join(import.meta.dirname, 'prompt', 'translate.md');
+const REFINE_PROMPT_FILE = pathModule.join(import.meta.dirname, 'prompt', 'refine.md');
+const DEFAULT_MODEL_CHAIN = Object.freeze(['sonnet5@50', 'gpt56luna@100']);
+
 class GPTrans {
     static #mmixInstances = new Map();
     static #translationLocks = new Map();
 
-    static mmix(models = 'sonnet45', { debug = 0 } = {}) {
-        const key = Array.isArray(models) ? models.join(',') : models;
+    static mmix(models = DEFAULT_MODEL_CHAIN, { debug = 0 } = {}) {
+        const modelChain = Array.isArray(models) ? models : [models];
+        const key = modelChain.join(',');
 
         if (!this.#mmixInstances.has(key)) {
-            let instance = ModelMix.new({
+            const instance = ModelMix.new({
                 config: {
                     debug,
                     bottleneck: {
@@ -23,18 +28,7 @@ class GPTrans {
                         maxConcurrent: 1
                     }
                 }
-            });
-            const modelArray = Array.isArray(models) ? models : [models];
-
-            for (const model of modelArray) {
-                if (typeof instance[model] !== 'function') {
-                    throw new Error(
-                        `Model "${model}" is not available. Please check the model name. ` +
-                        `Available models include: gpt51, gpt52, sonnet46, sonnet45, opus46, haiku45, etc.`
-                    );
-                }
-                instance = instance[model]();
-            }
+            }).chain(...modelChain);
 
             this.#mmixInstances.set(key, instance);
         }
@@ -63,7 +57,7 @@ class GPTrans {
         return isLanguageAvailable(langCode);
     }
 
-    constructor({ from = 'en-US', target = 'es', model = 'sonnet46', batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', instruction = '', freeze = false, debug = false, path: dbPath } = {}) {
+    constructor({ from = 'en-US', target = 'es', model = DEFAULT_MODEL_CHAIN, batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', instruction = '', freeze = false, debug = false, path: dbPath } = {}) {
 
         if (typeof dbPath !== 'string' || !pathModule.isAbsolute(dbPath)) {
             throw new TypeError('GPTrans requires an absolute "path" option.');
@@ -72,12 +66,6 @@ class GPTrans {
         target = this.normalizeBCP47(target);
         from = this.normalizeBCP47(from);
 
-        try {
-            process.loadEnvFile();
-        } catch {
-            /* optional .env missing or unreadable */
-        }
-
         const namePrefix = name ? '_' + name : '';
         this.dbPath = dbPath;
         this.instanceName = name;
@@ -100,7 +88,7 @@ class GPTrans {
         this.isProcessingBatch = false; // Track if a batch is currently being processed
         this.modelMixOptions = { debug };
         this.modelKey = model;
-        this.promptFile = promptFile ?? new URL('./prompt/translate.md', import.meta.url).pathname;
+        this.promptFile = promptFile ? pathModule.resolve(promptFile) : TRANSLATE_PROMPT_FILE;
         this.context = context;
         this.instruction = instruction;
         this.freeze = freeze;
@@ -335,7 +323,7 @@ class GPTrans {
         try {
             const model = GPTrans.mmix(this.modelKey, this.modelMixOptions);
 
-            model.setSystem("You are an expert translator specialized in literary translation between {FROM_LANG} and {TARGET_DENONYM} {TARGET_LANG}.");
+            model.setSystem("You are an expert translator specialized in literary translation between <%- FROM_LANG %> and <%- TARGET_DENONYM %> <%- TARGET_LANG %>.");
 
             // Build references section (includes header when references exist, empty otherwise)
             let referencesText = '';
@@ -379,21 +367,21 @@ class GPTrans {
                 }
             }
 
-            // Use ModelMix templates: addTextFromFile + replace + block
+            // Use ModelMix templates: addTextFromFile + assign + block
             model.addTextFromFile(this.promptFile);
-            model.replace({
-                '{INPUT}': text,
-                '{CONTEXT}': this.context,
-                '{INSTRUCTION}': this.instruction,
-                '{REFERENCES}': referencesText,
-                '{TARGET_ISO}': this.replaceTarget.TARGET_ISO,
-                '{TARGET_LANG}': this.replaceTarget.TARGET_LANG,
-                '{TARGET_COUNTRY}': this.replaceTarget.TARGET_COUNTRY,
-                '{TARGET_DENONYM}': this.replaceTarget.TARGET_DENONYM,
-                '{FROM_ISO}': fromReplace.FROM_ISO,
-                '{FROM_LANG}': fromReplace.FROM_LANG,
-                '{FROM_COUNTRY}': fromReplace.FROM_COUNTRY,
-                '{FROM_DENONYM}': fromReplace.FROM_DENONYM,
+            model.assign({
+                INPUT: text,
+                CONTEXT: this.context,
+                INSTRUCTION: this.instruction,
+                REFERENCES: referencesText,
+                TARGET_ISO: this.replaceTarget.TARGET_ISO,
+                TARGET_LANG: this.replaceTarget.TARGET_LANG,
+                TARGET_COUNTRY: this.replaceTarget.TARGET_COUNTRY,
+                TARGET_DENONYM: this.replaceTarget.TARGET_DENONYM,
+                FROM_ISO: fromReplace.FROM_ISO,
+                FROM_LANG: fromReplace.FROM_LANG,
+                FROM_COUNTRY: fromReplace.FROM_COUNTRY,
+                FROM_DENONYM: fromReplace.FROM_DENONYM,
             });
 
             return await model.block({ addSystemExtra: false });
@@ -557,7 +545,7 @@ class GPTrans {
         }
 
         const finalInstruction = instructions.length > 1 ? `- ${merged}` : merged;
-        const refinePromptFile = promptFile ?? new URL('./prompt/refine.md', import.meta.url).pathname;
+        const refinePromptFile = promptFile ? pathModule.resolve(promptFile) : REFINE_PROMPT_FILE;
 
         // Collect all existing translations grouped by contextHash
         const allBatches = [];
@@ -652,22 +640,22 @@ class GPTrans {
         try {
             const model = GPTrans.mmix(this.modelKey, this.modelMixOptions);
 
-            model.setSystem("You are an expert translator and editor specialized in refining {TARGET_DENONYM} {TARGET_LANG} translations.");
+            model.setSystem("You are an expert translator and editor specialized in refining <%- TARGET_DENONYM %> <%- TARGET_LANG %> translations.");
 
-            // Use ModelMix templates: addTextFromFile + replace + block
+            // Use ModelMix templates: addTextFromFile + assign + block
             model.addTextFromFile(refinePromptFile);
-            model.replace({
-                '{INPUT}': text,
-                '{INSTRUCTION}': instruction,
-                '{CONTEXT}': this.context,
-                '{TARGET_ISO}': this.replaceTarget.TARGET_ISO,
-                '{TARGET_LANG}': this.replaceTarget.TARGET_LANG,
-                '{TARGET_COUNTRY}': this.replaceTarget.TARGET_COUNTRY,
-                '{TARGET_DENONYM}': this.replaceTarget.TARGET_DENONYM,
-                '{FROM_ISO}': this.replaceFrom.FROM_ISO,
-                '{FROM_LANG}': this.replaceFrom.FROM_LANG,
-                '{FROM_COUNTRY}': this.replaceFrom.FROM_COUNTRY,
-                '{FROM_DENONYM}': this.replaceFrom.FROM_DENONYM,
+            model.assign({
+                INPUT: text,
+                INSTRUCTION: instruction,
+                CONTEXT: this.context,
+                TARGET_ISO: this.replaceTarget.TARGET_ISO,
+                TARGET_LANG: this.replaceTarget.TARGET_LANG,
+                TARGET_COUNTRY: this.replaceTarget.TARGET_COUNTRY,
+                TARGET_DENONYM: this.replaceTarget.TARGET_DENONYM,
+                FROM_ISO: this.replaceFrom.FROM_ISO,
+                FROM_LANG: this.replaceFrom.FROM_LANG,
+                FROM_COUNTRY: this.replaceFrom.FROM_COUNTRY,
+                FROM_DENONYM: this.replaceFrom.FROM_DENONYM,
             });
 
             return await model.block({ addSystemExtra: false });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "2.2.0",
+  "version": "2.2.4",
   "description": "🚆 GPTrans - The smarter AI-powered way to translate.",
   "keywords": [
     "translate",
@@ -32,13 +32,13 @@
   },
   "homepage": "https://github.com/clasen/GPTrans#readme",
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=20.12.0"
   },
   "dependencies": {
     "deepbase": "^3.9.0",
     "deepbase-json": "3.9.0",
     "genmix": "^1.2.5",
-    "modelmix": "^4.6.5",
+    "modelmix": "^5.1.6",
     "string-hash": "^1.1.3"
   },
   "scripts": {

package/pnpm-workspace.yaml

@@ -4,6 +4,7 @@ minimumReleaseAgeExclude:
   - genmix@1.2.5
   - deepbase-json@3.9.0
   - deepbase@3.9.0
+  - modelmix@5.1.6
 overrides:
   sharp: "^0.35.0"
   "@hono/node-server": "^2.0.5"

package/prompt/refine.md

@@ -1,12 +1,12 @@
 # Goal
-Refine existing translations in {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) based on the following instruction.
+Refine existing translations in <%- TARGET_ISO %> (<%- TARGET_DENONYM %> <%- TARGET_LANG %>) based on the following instruction.
 
 ## Refinement Instruction
-{INSTRUCTION}
+<%- INSTRUCTION %>
 
 ## Current Translations to Evaluate
 ```
-{INPUT}
+<%- INPUT %>
 ```
 
 # Return Format
@@ -23,4 +23,4 @@ Refine existing translations in {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) ba
    - **Consistency:** Maintain consistent terminology across all translations in the batch.
 
 # Context
-{CONTEXT}
+<%- CONTEXT %>

package/prompt/translate.md

@@ -1,13 +1,13 @@
 # Goal
-Translation from {FROM_ISO} to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) with cultural adaptations.
-{INSTRUCTION}
+Translation from <%- FROM_ISO %> to <%- TARGET_ISO %> (<%- TARGET_DENONYM %> <%- TARGET_LANG %>) with cultural adaptations.
+<%- INSTRUCTION %>
 
 ## Text to translate
 ```
-{INPUT}
+<%- INPUT %>
 ```
 
-{REFERENCES}
+<%- REFERENCES %>
 
 # Return Format
    - The input may contain multiple texts separated by `------`. Translate each one independently and return them in the same order, separated by `------`. The number of segments in your output must exactly match the number of segments in the input.
@@ -15,13 +15,13 @@ Translation from {FROM_ISO} to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) wit
    - Do not include alternative translations, only provide the best translation.
 
 # Warnings
-   - **Context:** I will provide you with a text in {FROM_DENONYM} {FROM_LANG}. The goal is to translate it to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) while maintaining the essence, style, intention, and tone of the original.
+   - **Context:** I will provide you with a text in <%- FROM_DENONYM %> <%- FROM_LANG %>. The goal is to translate it to <%- TARGET_ISO %> (<%- TARGET_DENONYM %> <%- TARGET_LANG %>) while maintaining the essence, style, intention, and tone of the original.
    - **Proper names:** Do not translate proper names (people, places, brands, etc.) unless they have an officially recognized translation in the target language.
-   - **Cultural references:** Adapt or explain references that are not familiar in {TARGET_DENONYM} culture, whenever necessary.
+   - **Cultural references:** Adapt or explain references that are not familiar in <%- TARGET_DENONYM %> culture, whenever necessary.
    - **Wordplay and humor:** When it's impossible to directly translate wordplay, find a resource that recreates the playful effect.
    - **Idioms:** Do not introduce new idioms or expressions that are not present in the original text.
    - **Variables:** Do not translate content between curly braces. These are system variables and must remain exactly the same.
 
 
 # Context
-{CONTEXT}
+<%- CONTEXT %>

package/skills/gptrans/SKILL.md

@@ -81,13 +81,13 @@ You can manually edit translation files to override specific entries.
 
 ```javascript
 import GPTrans from 'gptrans';
+import path from 'node:path';
 
-const dbPath = new URL('./db', import.meta.url).pathname;
+const dbPath = path.join(import.meta.dirname, 'db');
 const gptrans = new GPTrans({
   path: dbPath,
   from: 'en-US',
-  target: 'es-AR',
-  model: 'sonnet45'
+  target: 'es-AR'
 });
 
 // Translate text — returns original on first call, cached translation after
@@ -106,7 +106,7 @@ console.log(gptrans.setContext().t('Welcome back'));
 | --- | --- | --- | --- |
 | `from` | `string` | `'en-US'` | Source language (BCP 47) |
 | `target` | `string` | `'es'` | Target language (BCP 47) |
-| `model` | `string \| string[]` | `'sonnet45'` | Model key or array for fallback chain |
+| `model` | `string \| string[]` | `['sonnet5@50', 'gpt56luna@100']` | ModelMix shortcut or ordered fallback chain; supports `@<effort>` from `0` to `100` |
 | `batchThreshold` | `number` | `1500` | Max characters before triggering batch |
 | `debounceTimeout` | `number` | `500` | Milliseconds to wait before processing |
 | `freeze` | `boolean` | `false` | Prevent new translations from being queued |
@@ -134,10 +134,12 @@ const gptrans = new GPTrans({
   path: dbPath,
   from: 'en',
   target: 'fr',
-  model: ['sonnet45', 'gpt41']  // falls back to gpt41 if sonnet45 fails
+  model: ['sonnet5@50', 'gpt56luna@100']
 });
 ```
 
+Use `model@<effort>` with an integer from `0` to `100` to override the unified effort for one model. The default chain uses `sonnet5` at effort `50`, then falls back to `gpt56luna` at effort `100`.
+
 ### Pre-translate all pending texts
 
 ```javascript
@@ -268,8 +270,7 @@ await gptrans.purge();
 const es2ar = new GPTrans({
   path: dbPath,
   from: 'es-ES',
-  target: 'es-AR',
-  model: 'sonnet45'
+  target: 'es-AR'
 });
 
 console.log(es2ar.t('Eres muy bueno'));
@@ -295,7 +296,7 @@ if (GPTrans.isLanguageAvailable('pt-BR')) {
 - Use `setContext()` for gender-aware or domain-specific translations. Context is captured per-batch and auto-resets when changed.
 - Use the `instruction` constructor option for style/tone guidance (e.g., "Use a more natural tone"). Unlike `context`, `instruction` does NOT affect the cache key — different instructions for the same text overwrite the same translation entry.
 - Prefer passing an array of instructions to `refine()` over multiple calls — it processes everything in a single API pass.
-- Use model arrays (`model: ['sonnet45', 'gpt41']`) for production resilience with automatic fallback.
+- Use model arrays (`model: ['sonnet5@50', 'gpt56luna@100']`) for production resilience with automatic fallback. The optional `@<effort>` suffix accepts integers from `0` to `100` and applies only to that model.
 - Translation caches live in `db/gptrans_<locale>.json`. These files can be manually edited to override specific translations.
 - The `name` constructor option isolates cache files (`db/gptrans_<name>_<locale>.json`), useful for multiple independent translation contexts in the same project.
 - When translating images, ensure `GEMINI_API_KEY` is set. The `img()` method auto-creates sibling language folders.

package/test/gptrans.tAsync.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { access, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import GPTrans from '../index.js';
@@ -161,6 +161,87 @@ test('constructor requires an absolute database path', () => {
     assert.throws(() => new GPTrans({ path: './db' }), /requires an absolute "path" option/);
 });
 
+test('the default model chain uses the configured efforts and renders the EJS prompt', async () => {
+    const previousAnthropicKey = process.env.ANTHROPIC_API_KEY;
+    const previousOpenAiKey = process.env.OPENAI_API_KEY;
+    process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+    process.env.OPENAI_API_KEY = 'test-openai-key';
+
+    try {
+        const model = GPTrans.mmix();
+        assert.deepEqual(
+            model.models.map(({ key }) => key),
+            ['claude-sonnet-5', 'gpt-5.6-luna']
+        );
+        assert.equal(model.models[0].provider.config.effort, 50);
+        assert.equal(model.models[1].provider.config.effort, 100);
+
+        const gp = new GPTrans({ path: tmpdir(), freeze: true, name: 'modelmix-render' });
+        assert.deepEqual(gp.modelKey, ['sonnet5@50', 'gpt56luna@100']);
+        model.addTextFromFile(gp.promptFile);
+        model.assign({
+            INPUT: 'Hello',
+            CONTEXT: 'Greeting',
+            INSTRUCTION: 'Be friendly',
+            REFERENCES: '',
+            TARGET_ISO: 'es',
+            TARGET_LANG: 'Spanish',
+            TARGET_COUNTRY: 'Spain',
+            TARGET_DENONYM: 'Spanish',
+            FROM_ISO: 'en-US',
+            FROM_LANG: 'English',
+            FROM_COUNTRY: 'United States',
+            FROM_DENONYM: 'American'
+        });
+        const messages = await model.prepareMessages();
+        const renderedPrompt = messages[0].content[0].text;
+        assert.match(renderedPrompt, /Translation from en-US to es/);
+        assert.match(renderedPrompt, /```\nHello\n```/);
+        assert.doesNotMatch(renderedPrompt, /<%-\s*[A-Z_]+\s*%>/);
+    } finally {
+        if (previousAnthropicKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+        else process.env.ANTHROPIC_API_KEY = previousAnthropicKey;
+        if (previousOpenAiKey === undefined) delete process.env.OPENAI_API_KEY;
+        else process.env.OPENAI_API_KEY = previousOpenAiKey;
+    }
+});
+
+test('_translate uses assign() with the absolute built-in prompt path', async () => {
+    const gp = createTestInstance();
+    const originalMmix = GPTrans.mmix;
+    const calls = {};
+    const model = {
+        setSystem(value) {
+            calls.system = value;
+        },
+        addTextFromFile(value) {
+            calls.promptFile = value;
+        },
+        assign(value) {
+            calls.templateData = value;
+        },
+        async block(options) {
+            calls.blockOptions = options;
+            return 'Hola';
+        }
+    };
+    GPTrans.mmix = () => model;
+
+    try {
+        assert.equal(await gp._translate('Hello'), 'Hola');
+        assert.equal(path.isAbsolute(calls.promptFile), true);
+        assert.equal(path.basename(calls.promptFile), 'translate.md');
+        await access(calls.promptFile);
+        assert.equal(calls.templateData.INPUT, 'Hello');
+        assert.equal(calls.templateData.FROM_ISO, 'en-US');
+        assert.equal(calls.templateData.TARGET_ISO, 'es');
+        assert.match(calls.system, /<%- FROM_LANG %>/);
+        assert.deepEqual(calls.blockOptions, { addSystemExtra: false });
+    } finally {
+        GPTrans.mmix = originalMmix;
+    }
+});
+
 test('DeepBase 3.9 cache is available to synchronous translations', async () => {
     const directory = await mkdtemp(path.join(tmpdir(), 'gptrans-deepbase-'));
     const originalMmix = GPTrans.mmix;
@@ -193,6 +274,17 @@ test('DeepBase 3.9 cache is available to synchronous translations', async () =>
 
         assert.equal(gp.dbFrom.getSync('', sourceKey), sourceText);
         assert.equal(gp.dbTarget.getSync(contextHash, sourceKey), 'Nuevo texto fuente');
+
+        let refinePromptFile;
+        gp._processRefineBatch = async (entries, instruction, promptFile) => {
+            assert.equal(entries.length, 2);
+            assert.equal(instruction, 'Use a formal tone');
+            refinePromptFile = promptFile;
+        };
+        await gp.refine('Use a formal tone');
+        assert.equal(path.isAbsolute(refinePromptFile), true);
+        assert.equal(path.basename(refinePromptFile), 'refine.md');
+        await access(refinePromptFile);
     } finally {
         GPTrans.mmix = originalMmix;
         if (gp.debounceTimer) {

package/test-image-translation.js

@@ -1,10 +1,6 @@
 import GPTrans from './index.js';
 import path from 'path';
 import fs from 'fs';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
 
 async function testImageTranslation() {
     try {
@@ -12,14 +8,14 @@ async function testImageTranslation() {
 
         // Initialize GPTrans with Portuguese as target language
         const gptrans = new GPTrans({
-            path: path.join(__dirname, 'db'),
+            path: path.join(import.meta.dirname, 'db'),
             from: 'en-US',
             target: 'pt-BR',
             model: 'sonnet45'
         });
 
         // Test image path (you'll need to provide an actual image)
-        const testImagePath = path.join(__dirname, 'test-image.jpg');
+        const testImagePath = path.join(import.meta.dirname, 'test-image.jpg');
 
         // Check if test image exists
         if (!fs.existsSync(testImagePath)) {