gptrans 1.9.8 → 2.0.2

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

@@ -0,0 +1,303 @@
+---
+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.
+---
+
+# ModelMix Library Skill
+
+## Overview
+
+ModelMix is a Node.js library that provides a unified fluent API to interact with multiple AI LLM providers. It handles automatic fallback between models, round-robin load balancing, structured JSON output, streaming, MCP tool integration, rate limiting, and token tracking.
+
+Use this skill when:
+- Integrating one or more AI models into a Node.js project
+- Chaining models with automatic fallback
+- Extracting structured JSON from LLMs
+- Adding MCP tools or custom tools to models
+- Working with templates and file-based prompts
+
+Do NOT use this skill for:
+- Python or non-Node.js projects
+- Direct HTTP calls to LLM APIs (use ModelMix instead)
+
+## Installation
+
+```bash
+npm install modelmix
+```
+
+## Core Concepts
+
+### Import
+
+```javascript
+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
+        roundRobin: false    // false=fallback, true=rotate models
+    }
+});
+```
+
+### Attaching Models (Fluent Chain)
+
+Chain shorthand methods to attach providers. First model is primary; others are fallbacks:
+
+```javascript
+const model = ModelMix.new()
+    .sonnet45()        // primary
+    .gpt5mini()        // fallback 1
+    .gemini3flash()    // fallback 2
+    .addText("Hello!")
+```
+
+If `sonnet45` fails, it automatically tries `gpt5mini`, then `gemini3flash`.
+
+## Available Model Shorthands
+
+- **OpenAI**: `gpt52` `gpt51` `gpt5` `gpt5mini` `gpt5nano` `gpt41` `gpt41mini` `gpt41nano`
+- **Anthropic**: `opus46` `opus45` `sonnet45` `sonnet4` `haiku45` `haiku35` (thinking variants: add `think` suffix)
+- **Google**: `gemini3pro` `gemini3flash` `gemini25pro` `gemini25flash`
+- **Grok**: `grok4` `grok41` (thinking variant available)
+- **Perplexity**: `sonar` `sonarPro`
+- **Groq**: `scout` `maverick`
+- **Together**: `qwen3` `kimiK2`
+- **Multi-provider**: `deepseekR1` `gptOss`
+- **MiniMax**: `minimaxM21`
+- **Fireworks**: `deepseekV32` `GLM47`
+
+Each method is called as `mix.methodName()` and accepts optional `{ options, config }` to override per-model settings.
+
+## Common Tasks
+
+### Get a text response
+
+```javascript
+const answer = await ModelMix.new()
+    .gpt5mini()
+    .addText("What is the capital of France?")
+    .message();
+```
+
+### Get structured JSON
+
+```javascript
+const result = await ModelMix.new()
+    .gpt5mini()
+    .addText("Name and capital of 3 South American countries.")
+    .json(
+        { countries: [{ name: "", capital: "" }] },                    // schema example
+        { countries: [{ name: "country name", capital: "in uppercase" }] }, // descriptions
+        { addNote: true }                                               // options
+    );
+// result.countries → [{ name: "Brazil", capital: "BRASILIA" }, ...]
+```
+
+`json()` signature: `json(schemaExample, schemaDescription?, { addSchema, addExample, addNote }?)`
+
+### Stream a response
+
+```javascript
+await ModelMix.new()
+    .gpt5mini()
+    .addText("Tell me a story.")
+    .stream(({ delta, message }) => {
+        process.stdout.write(delta);
+    });
+```
+
+### Get raw response (tokens, thinking, tool calls)
+
+```javascript
+const raw = await ModelMix.new()
+    .sonnet45think()
+    .addText("Solve this step by step: 2+2*3")
+    .raw();
+// raw.message, raw.think, raw.tokens, raw.toolCalls, raw.response
+```
+
+### Access full response after `message()` or `json()` with `lastRaw`
+
+After calling `message()`, `json()`, `block()`, or `stream()`, use `lastRaw` to access the complete response (tokens, thinking, tool calls, etc.). It has the same structure as `raw()`.
+
+```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 }
+console.log(model.lastRaw.think);    // reasoning content (if available)
+console.log(model.lastRaw.response); // raw API response
+```
+
+### Add images
+
+```javascript
+const model = ModelMix.new().sonnet45();
+model.addImage('./photo.jpg');                         // from file
+model.addImageFromUrl('https://example.com/img.png');  // from URL
+model.addText('Describe this image.');
+const description = await model.message();
+```
+
+### Use templates with placeholders
+
+```javascript
+const model = ModelMix.new().gpt5mini();
+model.setSystemFromFile('./prompts/system.md');
+model.addTextFromFile('./prompts/task.md');
+model.replace({
+    '{role}': 'data analyst',
+    '{language}': 'Spanish'
+});
+model.replaceKeyFromFile('{code}', './src/utils.js');
+console.log(await model.message());
+```
+
+### Round-robin load balancing
+
+```javascript
+const pool = ModelMix.new({ config: { roundRobin: true } })
+    .gpt5mini()
+    .sonnet45()
+    .gemini3flash();
+
+// Each call rotates to the next model
+const r1 = await pool.new().addText("Request 1").message();
+const r2 = await pool.new().addText("Request 2").message();
+```
+
+### MCP integration (external tools)
+
+```javascript
+const model = ModelMix.new({ config: { max_history: 10 } }).gpt5nano();
+model.setSystem('You are an assistant. Today is ' + new Date().toISOString());
+await model.addMCP('@modelcontextprotocol/server-brave-search');
+model.addText('Use Internet: What is the latest news about AI?');
+console.log(await model.message());
+```
+
+Requires `BRAVE_API_KEY` in `.env` for Brave Search MCP.
+
+### Custom local tools (addTool)
+
+```javascript
+const model = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();
+
+model.addTool({
+    name: "get_weather",
+    description: "Get weather for a city",
+    inputSchema: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"]
+    }
+}, async ({ city }) => {
+    return `The weather in ${city} is sunny, 25C`;
+});
+
+model.addText("What's the weather in Tokyo?");
+console.log(await model.message());
+```
+
+### Rate limiting (Bottleneck)
+
+```javascript
+const model = ModelMix.new({
+    config: {
+        bottleneck: {
+            maxConcurrent: 4,
+            minTime: 1000
+        }
+    }
+}).gpt5mini();
+```
+
+### Debug mode
+
+```javascript
+const model = ModelMix.new({
+    config: { debug: 2 }  // 0=silent, 1=minimal, 2=summary, 3=full
+}).gpt5mini();
+```
+
+For full debug output, also set the env: `DEBUG=ModelMix* node script.js`
+
+### Use free-tier models
+
+```javascript
+// These use providers with free quotas (OpenRouter, Groq, Cerebras)
+const model = ModelMix.new()
+    .gptOss()
+    .kimiK2()
+    .deepseekR1()
+    .hermes3()
+    .addText("What is the capital of France?");
+console.log(await model.message());
+```
+
+### Conversation history
+
+```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"
+```
+
+## Agent Usage Rules
+
+- Always check `package.json` for `modelmix` before running `npm install`.
+- Use `ModelMix.new()` static factory to create instances (not `new ModelMix()`).
+- Store API keys in `.env` and load with `dotenv/config` or `process.loadEnvFile()`. Never hardcode keys.
+- Chain models for resilience: primary model first, fallbacks after.
+- When using MCP tools or `addTool()`, set `max_history` to at least 3.
+- Use `.json()` for structured output instead of parsing text manually.
+- Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
+- For thinking models, append `think` to the method name (e.g. `sonnet45think()`).
+- Template placeholders use `{key}` syntax in both system prompts and user messages.
+- The library uses CommonJS internally (`require`) but supports ESM import via `{ ModelMix }`.
+- Available provider Mix classes for custom setups: `MixOpenAI`, `MixAnthropic`, `MixGoogle`, `MixPerplexity`, `MixGroq`, `MixTogether`, `MixGrok`, `MixOpenRouter`, `MixOllama`, `MixLMStudio`, `MixCustom`, `MixCerebras`, `MixFireworks`, `MixMiniMax`.
+
+## API Quick Reference
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `.addText(text)` | `this` | Add user message |
+| `.addTextFromFile(path)` | `this` | Add user message from file |
+| `.setSystem(text)` | `this` | Set system prompt |
+| `.setSystemFromFile(path)` | `this` | Set system prompt from file |
+| `.addImage(path)` | `this` | Add image from file |
+| `.addImageFromUrl(url)` | `this` | Add image from URL or data URI |
+| `.replace({})` | `this` | Set placeholder replacements |
+| `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
+| `.message()` | `Promise<string>` | Get text response |
+| `.json(example, desc?, opts?)` | `Promise<object>` | Get structured JSON |
+| `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |
+| `.lastRaw` | `object \| null` | Full response from last `message()`/`json()`/`block()`/`stream()` call |
+| `.stream(callback)` | `Promise` | Stream response |
+| `.block()` | `Promise<string>` | Extract code block from response |
+| `.addMCP(package)` | `Promise` | Add MCP server tools |
+| `.addTool(def, callback)` | `this` | Register custom local tool |
+| `.addTools([{tool, callback}])` | `this` | Register multiple tools |
+| `.removeTool(name)` | `this` | Remove a tool |
+| `.listTools()` | `{local, mcp}` | List registered tools |
+| `.new()` | `ModelMix` | Clone instance sharing models |
+| `.attach(key, provider)` | `this` | Attach custom provider |
+
+## References
+
+- [GitHub Repository](https://github.com/clasen/ModelMix)

package/README.md

@@ -21,7 +21,10 @@ Whether you're building a multilingual website, a mobile app, or a localization
 ```bash
 npm install gptrans
 ```
-
+> **AI Skill**: You can also add GPTrans as a skill for AI agentic development:
+> ```bash
+> npx skills add https://github.com/clasen/GPTrans --skill gptrans
+> ```
 ### 🌐 Environment Setup
 
 GPTrans uses dotenv for environment configuration. Create a `.env` file in your project root and add your API keys:
@@ -214,6 +217,26 @@ When using multiple models:
 - If the primary model fails (due to API errors, rate limits, etc.), GPTrans automatically falls back to the next model
 - This ensures higher availability and resilience of your translation service
 
+## ✏️ Refining Translations
+
+The `refine()` method lets you improve existing translations by running them through the AI again with a specific instruction. It processes translations in batches (same as the translation flow) and only updates entries that genuinely benefit from the refinement.
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+
+// After translations already exist...
+// Refine with a single instruction
+await gptrans.refine('Use a more natural and colloquial tone');
+
+// Or pass multiple instructions at once (single API pass, saves tokens)
+await gptrans.refine([
+  'Shorten texts where possible without losing meaning',
+  'Use a more colloquial tone'
+]);
+```
+
+> **Note:** The refine method uses the **target translation** as input (not the original source text). If the AI determines a translation is already good, it keeps it unchanged. Passing an array of instructions is preferred over multiple `refine()` calls since it processes everything in a single API pass.
+
 # 🖼️ Image Translation
 
 Intelligent image translation using Google's Gemini AI.

package/demo/case_refine.js

@@ -0,0 +1,61 @@
+import GPTrans from '../index.js';
+
+console.log('🚀 Testing GPTrans Refine\n');
+console.log('='.repeat(70));
+
+async function testRefine() {
+    // Step 1: Create initial translations
+    const gptrans = new GPTrans({
+        from: 'en-US',
+        target: 'es-AR',
+        model: 'sonnet45',
+        name: 'refine_test'
+    });
+
+    const texts = [
+        'You have exceeded the maximum number of attempts',
+        'Your session has expired, please log in again',
+        'The operation was completed successfully',
+        'An unexpected error occurred, please try again later',
+        'Are you sure you want to delete this item?'
+    ];
+
+    console.log('\n📝 Step 1: Creating initial translations...\n');
+    texts.forEach(text => {
+        console.log(`   EN: ${text}`);
+        console.log(`   ES: ${gptrans.t(text)}\n`);
+    });
+
+    await gptrans.preload();
+
+    console.log('='.repeat(70));
+    console.log('\n📝 Step 2: Translations before refine:\n');
+    texts.forEach(text => {
+        console.log(`   EN: ${text}`);
+        console.log(`   ES: ${gptrans.t(text)}\n`);
+    });
+
+    // Step 2: Refine with multiple instructions in a single pass
+    console.log('='.repeat(70));
+    console.log('\n🔄 Step 3: Refining with multiple instructions (single API pass)...\n');
+
+    await gptrans.refine([
+        'Use "vos" instead of "tú" for all second-person references',
+        'Use a more friendly and colloquial tone, less robotic',
+        'Shorten messages where possible without losing clarity'
+    ]);
+
+    console.log('📝 Translations after refine:\n');
+    texts.forEach(text => {
+        console.log(`   EN: ${text}`);
+        console.log(`   ES: ${gptrans.t(text)}\n`);
+    });
+
+    console.log('='.repeat(70));
+    console.log('\n✅ Refine test completed!\n');
+}
+
+testRefine().catch(error => {
+    console.error('\n❌ Error:', error.message);
+    console.error(error.stack);
+});

package/index.js

@@ -11,11 +11,11 @@ class GPTrans {
     static #mmixInstances = new Map();
     static #translationLocks = new Map();
 
-    static mmix(models = 'sonnet45', { debug = false } = {}) {
+    static mmix(models = 'sonnet45', { debug = 0 } = {}) {
         const key = Array.isArray(models) ? models.join(',') : models;
 
         if (!this.#mmixInstances.has(key)) {
-            const mmix = new ModelMix({
+            let instance = ModelMix.new({
                 config: {
                     max_history: 1,
                     debug,
@@ -25,9 +25,6 @@ class GPTrans {
                     }
                 }
             });
-
-            // Chain models dynamically
-            let instance = mmix;
             const modelArray = Array.isArray(models) ? models : [models];
 
             for (const model of modelArray) {
@@ -218,15 +215,15 @@ class GPTrans {
         const textsToTranslate = batch.map(([_, text]) => text).join(`\n${this.divider}\n`);
         try {
             const translations = await this._translate(textsToTranslate, batch, batchReferences, this.preloadBaseLanguage);
-            
+
             // Try different split strategies to be more robust
             let translatedTexts = translations.split(`\n${this.divider}\n`);
-            
+
             // If split doesn't match batch size, try alternative separators
             if (translatedTexts.length !== batch.length) {
                 // Try without newlines around divider
                 translatedTexts = translations.split(this.divider);
-                
+
                 // If still doesn't match, try with just newline
                 if (translatedTexts.length !== batch.length) {
                     translatedTexts = translations.split(/\n{2,}/); // Split by multiple newlines
@@ -234,7 +231,7 @@ class GPTrans {
             }
 
             const contextHash = this._hash(context);
-            
+
             // Validate we have the right number of translations
             if (translatedTexts.length !== batch.length) {
                 console.error(`❌ Translation count mismatch:`);
@@ -242,7 +239,7 @@ class GPTrans {
                 console.error(`   Received: ${translatedTexts.length} translations`);
                 console.error(`   Batch keys: ${batch.map(([key]) => key).join(', ')}`);
                 console.error(`\n📝 Full response from model:\n${translations}\n`);
-                
+
                 // Try to save what we can
                 const minLength = Math.min(translatedTexts.length, batch.length);
                 for (let i = 0; i < minLength; i++) {
@@ -276,18 +273,14 @@ 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}.");
 
-            // Read and process prompt file
-            let promptContent = fs.readFileSync(this.promptFile, 'utf-8');
-
-            // Format references if available
+            // Build references section (includes header when references exist, empty otherwise)
             let referencesText = '';
             if (Object.keys(batchReferences).length > 0 && batch.length > 0) {
-                // Group all references by language first
                 const refsByLang = {};
-                
-                batch.forEach(([key], index) => {
+
+                batch.forEach(([key]) => {
                     if (batchReferences[key]) {
                         Object.entries(batchReferences[key]).forEach(([lang, translation]) => {
                             if (!refsByLang[lang]) {
@@ -297,8 +290,7 @@ class GPTrans {
                         });
                     }
                 });
-                
-                // Format: one language header, then all its translations with bullets
+
                 const refBlocks = Object.entries(refsByLang).map(([lang, translations]) => {
                     try {
                         const langInfo = isoAssoc(lang);
@@ -311,17 +303,8 @@ class GPTrans {
                         return `${header}\n${content}`;
                     }
                 });
-                
-                referencesText = refBlocks.join(`\n\n`);
-            }
 
-            // Remove reference section if no references
-            if (!referencesText) {
-                // Remove the entire "Reference Translations" section
-                promptContent = promptContent.replace(
-                    /## Reference Translations \(for context\)[\s\S]*?(?=\n#|$)/,
-                    ''
-                );
+                referencesText = `## Reference Translations (for context)\nThese are existing translations in other languages that may help you provide a more accurate translation. Use them as reference but do not simply copy them:\n\n${refBlocks.join('\n\n')}`;
             }
 
             // Determine which FROM_ values to use
@@ -334,30 +317,23 @@ class GPTrans {
                 }
             }
 
-            // Apply replacements to prompt
-            promptContent = promptContent
-                .replace(/INPUT/g, text)
-                .replace(/CONTEXT/g, this.context)
-                .replace(/REFERENCES/g, referencesText);
-
-            // Apply language-specific replacements
-            Object.entries(this.replaceTarget).forEach(([key, value]) => {
-                promptContent = promptContent.replace(new RegExp(key, 'g'), value);
+            // Use ModelMix templates: addTextFromFile + replace + block
+            model.addTextFromFile(this.promptFile);
+            model.replace({
+                '{INPUT}': text,
+                '{CONTEXT}': this.context,
+                '{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,
             });
-            Object.entries(fromReplace).forEach(([key, value]) => {
-                promptContent = promptContent.replace(new RegExp(key, 'g'), value);
-            });
-
-            model.addText(promptContent);
-
-            const response = await model.message();
 
-            // Extract content from code block if present
-            const codeBlockRegex = /```(?:\w*\n)?([\s\S]*?)```/;
-            const match = response.match(codeBlockRegex);
-            const translatedText = match ? match[1].trim() : response.trim();
-
-            return translatedText;
+            return await model.block({ addSystemExtra: false });
 
         } finally {
             // Always release the lock
@@ -431,14 +407,14 @@ class GPTrans {
 
         // Track which keys need translation
         const keysNeedingTranslation = [];
-        
+
         for (const [context, pairs] of this.dbFrom.entries()) {
             // Skip the _context metadata
             if (context === '_context') continue;
-            
+
             this.setContext(context);
             const contextHash = this._hash(context);
-            
+
             for (const [key, text] of Object.entries(pairs)) {
                 // Check if translation already exists
                 if (!this.dbTarget.get(contextHash, key)) {
@@ -462,7 +438,7 @@ class GPTrans {
             const checkInterval = setInterval(() => {
                 // Check if there are still pending translations or batch being processed
                 const hasPending = this.pendingTranslations.size > 0 || this.isProcessingBatch;
-                
+
                 // Check if all needed translations are now complete
                 let allTranslated = true;
                 for (const { contextHash, key } of keysNeedingTranslation) {
@@ -471,7 +447,7 @@ class GPTrans {
                         break;
                     }
                 }
-                
+
                 if (allTranslated && !hasPending) {
                     clearInterval(checkInterval);
                     resolve();
@@ -507,6 +483,140 @@ class GPTrans {
         return this;
     }
 
+    async refine(instruction, { promptFile = null } = {}) {
+        // Accept string or array of instructions
+        const instructions = Array.isArray(instruction) ? instruction : [instruction];
+        const merged = instructions.filter(i => i && i.trim()).join('\n- ');
+
+        if (!merged) {
+            throw new Error('Refinement instruction is required');
+        }
+
+        const finalInstruction = instructions.length > 1 ? `- ${merged}` : merged;
+        const refinePromptFile = promptFile ?? new URL('./prompt/refine.md', import.meta.url).pathname;
+
+        // Collect all existing translations grouped by contextHash
+        const allBatches = [];
+        let currentBatch = [];
+        let currentCharCount = 0;
+
+        for (const [contextHash, pairs] of this.dbTarget.entries()) {
+            for (const [key, translation] of Object.entries(pairs)) {
+                const entryCharCount = translation.length;
+
+                // If adding this entry exceeds threshold, flush current batch
+                if (currentBatch.length > 0 && currentCharCount + entryCharCount >= this.batchThreshold) {
+                    allBatches.push({ entries: currentBatch, contextHash });
+                    currentBatch = [];
+                    currentCharCount = 0;
+                }
+
+                currentBatch.push({ key, translation, contextHash });
+                currentCharCount += entryCharCount;
+            }
+        }
+
+        // Push remaining entries
+        if (currentBatch.length > 0) {
+            allBatches.push({ entries: currentBatch, contextHash: currentBatch[0].contextHash });
+        }
+
+        if (allBatches.length === 0) {
+            return this;
+        }
+
+        // Process each batch sequentially (respecting rate limits via locks)
+        for (const batch of allBatches) {
+            await this._processRefineBatch(batch.entries, finalInstruction, refinePromptFile);
+        }
+
+        return this;
+    }
+
+    async _processRefineBatch(entries, instruction, refinePromptFile) {
+        const charCount = entries.reduce((sum, e) => sum + e.translation.length, 0);
+        this.modelConfig.options.max_tokens = charCount + 1000;
+        const minTime = Math.floor((60000 / (8000 / charCount)) * 1.4);
+        GPTrans.mmix(this.modelKey, this.modelMixOptions).limiter.updateSettings({ minTime });
+
+        const textsToRefine = entries.map(e => e.translation).join(`\n${this.divider}\n`);
+
+        try {
+            const refined = await this._refineTranslate(textsToRefine, instruction, refinePromptFile);
+
+            // Split with same strategy as _processBatch
+            let refinedTexts = refined.split(`\n${this.divider}\n`);
+
+            if (refinedTexts.length !== entries.length) {
+                refinedTexts = refined.split(this.divider);
+
+                if (refinedTexts.length !== entries.length) {
+                    refinedTexts = refined.split(/\n{2,}/);
+                }
+            }
+
+            if (refinedTexts.length !== entries.length) {
+                console.error(`❌ Refine count mismatch:`);
+                console.error(`   Expected: ${entries.length} translations`);
+                console.error(`   Received: ${refinedTexts.length} translations`);
+                console.error(`\n📝 Full response from model:\n${refined}\n`);
+
+                // Save what we can
+                const minLength = Math.min(refinedTexts.length, entries.length);
+                for (let i = 0; i < minLength; i++) {
+                    if (refinedTexts[i] && refinedTexts[i].trim()) {
+                        this.dbTarget.set(entries[i].contextHash, entries[i].key, refinedTexts[i].trim());
+                    }
+                }
+                return;
+            }
+
+            entries.forEach((entry, index) => {
+                const refinedText = refinedTexts[index]?.trim();
+                if (!refinedText) {
+                    console.error(`❌ No refined text for ${entry.key} at index ${index}`);
+                    return;
+                }
+                this.dbTarget.set(entry.contextHash, entry.key, refinedText);
+            });
+
+        } catch (e) {
+            console.error('❌ Error in _processRefineBatch:', e.message);
+            console.error(e.stack);
+        }
+    }
+
+    async _refineTranslate(text, instruction, refinePromptFile) {
+        const releaseLock = await GPTrans.#acquireTranslationLock(this.modelKey);
+
+        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.");
+
+            // Use ModelMix templates: addTextFromFile + replace + 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,
+            });
+
+            return await model.block({ addSystemExtra: false });
+
+        } finally {
+            releaseLock();
+        }
+    }
+
     async img(imagePath, options = {}) {
         const {
             quality = '1K',
@@ -586,7 +696,7 @@ class GPTrans {
             // Save translated image - preserve original file format
             const filename = path.basename(targetPath, path.extname(targetPath));
             const formatOptions = generator.getReferenceMetadata();
-            
+
             // Apply default quality settings for JPEG images
             if (formatOptions && (formatOptions.format === 'jpeg' || formatOptions.format === 'jpg')) {
                 // Apply custom quality if specified, otherwise use defaults
@@ -595,7 +705,7 @@ class GPTrans {
                 formatOptions.chromaSubsampling = '4:4:4';  // Better color quality
                 formatOptions.optimiseCoding = true;  // Lossless size reduction
             }
-            
+
             await generator.save({ directory: targetDir, filename, formatOptions });
         } else {
             throw new Error('No translated image was generated');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "1.9.8",
+  "version": "2.0.2",
   "description": "🚆 GPTrans - The smarter AI-powered way to translate.",
   "keywords": [
     "translate",
@@ -15,6 +15,9 @@
     "translation",
     "translator",
     "magic",
+    "agentic",
+    "skill",
+    "image",
     "clasen"
   ],
   "repository": {
@@ -37,7 +40,7 @@
     "dotenv": "^16.4.7",
     "form-data": "^4.0.4",
     "genmix": "^1.0.4",
-    "modelmix": "^4.2.8",
+    "modelmix": "^4.3.6",
     "string-hash": "^1.1.3"
   }
 }

package/prompt/refine.md

@@ -0,0 +1,26 @@
+# Goal
+Refine existing translations in {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) based on the following instruction.
+
+## Refinement Instruction
+{INSTRUCTION}
+
+## Current Translations to Evaluate
+```
+{INPUT}
+```
+
+# Return Format
+   - Provide the refined translations within a code block using ```.
+   - Return each translation separated by `------` (same divider as the input).
+   - If a translation is already good and does not need improvement, return it exactly as-is.
+   - Do not add, remove, or reorder translations. The output must have the exact same number of entries as the input.
+
+# Warnings
+   - **Preserve meaning:** The refined translation must preserve the original meaning. Only improve style, naturalness, or clarity as instructed.
+   - **Minimal changes:** Only modify translations that genuinely benefit from the refinement instruction. If the current translation is already good, keep it unchanged.
+   - **Proper names:** Do not translate proper names (people, places, brands, etc.) unless they have an officially recognized translation in the target language.
+   - **Variables:** Do not translate content between curly braces. These are system variables and must remain exactly the same.
+   - **Consistency:** Maintain consistent terminology across all translations in the batch.
+
+# Context
+{CONTEXT}

package/prompt/translate.md

@@ -1,28 +1,25 @@
 # Goal
-Translation from FROM_ISO to TARGET_ISO (TARGET_DENONYM TARGET_LANG) with cultural adaptations.
+Translation from {FROM_ISO} to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) with cultural adaptations.
 
 ## Text to translate
 ```
-INPUT
+{INPUT}
 ```
 
-## Reference Translations (for context)
-These are existing translations in other languages that may help you provide a more accurate translation. Use them as reference but do not simply copy them:
-
-REFERENCES
+{REFERENCES}
 
 # Return Format
    - Provide the final translation within a code block using ```.
    - 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 {variable}. These are system variables and must remain exactly the same.
+   - **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

@@ -0,0 +1,306 @@
+---
+name: gptrans
+description: Instructions for using the GPTrans Node.js library for AI-powered translations with smart batching, caching, context-aware translations, refinement, and image translation. Use when adding i18n/localization to a Node.js project, translating text or images between languages, or managing multilingual content.
+version: 1.0.0
+tags: [nodejs, translation, i18n, localization, ai, gpt, multilingual]
+---
+
+# GPTrans Library Skill
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Basic Usage](#basic-usage)
+- [Common Tasks](#common-tasks)
+- [Agent Usage Rules](#agent-usage-rules)
+- [API Quick Reference](#api-quick-reference)
+- [References](#references)
+
+## Overview
+
+GPTrans is a Node.js library that provides AI-powered translations with smart batching, caching, and context awareness. It uses LLMs (via ModelMix) to produce high-quality, culturally-adapted translations while minimizing API calls through intelligent debouncing and batch processing.
+
+Use this skill when:
+- Adding internationalization (i18n) or localization to a Node.js application
+- Translating text content between languages using AI
+- Translating images between languages (via Gemini)
+- Managing multilingual content with caching and manual correction support
+- Building tools that need context-aware translations (gender, tone, domain)
+- Pre-translating or bulk-translating content with `preload()`
+- Refining existing translations with specific style instructions
+
+Do NOT use this skill for:
+- Python or non-Node.js projects
+- Simple key-value i18n (use `i18next` or similar instead)
+- Projects that don't need AI-quality translations
+
+## Installation
+
+```bash
+npm install gptrans
+```
+
+### Environment Setup
+
+GPTrans requires API keys for the underlying LLM providers. Create a `.env` file:
+
+```env
+OPENAI_API_KEY=your_openai_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+GEMINI_API_KEY=your_gemini_api_key  # only for image translation
+```
+
+### Dependencies
+
+GPTrans uses [ModelMix](https://github.com/clasen/ModelMix) internally for LLM calls. It is installed automatically as a dependency.
+
+## Core Concepts
+
+### How It Works
+
+1. **First call to `t()`**: Returns the original text immediately. The translation is queued in the background.
+2. **Batching**: Queued translations are grouped by character count (`batchThreshold`) and debounce timer (`debounceTimeout`) to optimize API usage and provide better context to the LLM.
+3. **Caching**: Completed translations are stored in `db/gptrans_<locale>.json`. Subsequent calls return instantly from cache.
+4. **Second call to `t()`**: Returns the cached translation.
+
+### Language Tags
+
+GPTrans uses BCP 47 language tags: `en-US`, `es-AR`, `pt-BR`, `fr`, `de`, etc. Region can be omitted for universal variants (e.g., `es` for generic Spanish).
+
+### Translation Cache Files
+
+Translations are stored as JSON in `db/` directory:
+- `db/gptrans_<target>.json` — cached translations for target locale
+- `db/gptrans_from_<source>.json` — source text registry
+
+You can manually edit translation files to override specific entries.
+
+## Basic Usage
+
+```javascript
+import GPTrans from 'gptrans';
+
+const gptrans = new GPTrans({
+  from: 'en-US',
+  target: 'es-AR',
+  model: 'sonnet45'
+});
+
+// Translate text — returns original on first call, cached translation after
+console.log(gptrans.t('Hello, {name}!', { name: 'John' }));
+
+// Context-aware translation (e.g., gender)
+console.log(gptrans.setContext('Message is for a woman').t('You are very good'));
+
+// Context auto-clears — pass empty to reset
+console.log(gptrans.setContext().t('Welcome back'));
+```
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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 |
+| `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 |
+| `name` | `string` | `''` | Instance name (isolates cache files) |
+| `context` | `string` | `''` | Default context for translations |
+| `promptFile` | `string` | `null` | Custom prompt file path (overrides built-in) |
+| `debug` | `boolean` | `false` | Enable debug output |
+
+## Common Tasks
+
+### Translate text with parameter substitution
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
+// First call: "Hello, Martin!" (original)
+// After caching: "Hola, Martin!" (translated)
+```
+
+### Use model fallback for resilience
+
+```javascript
+const gptrans = new GPTrans({
+  from: 'en',
+  target: 'fr',
+  model: ['sonnet45', 'gpt41']  // falls back to gpt41 if sonnet45 fails
+});
+```
+
+### Pre-translate all pending texts
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es' });
+
+// Register texts
+gptrans.t('Welcome');
+gptrans.t('Sign in');
+gptrans.t('Sign out');
+
+// Wait for all translations to complete
+await gptrans.preload();
+
+// Now all calls return cached translations
+console.log(gptrans.t('Welcome'));  // "Bienvenido"
+```
+
+### Pre-translate with reference languages
+
+Use existing translations in other languages as context for better accuracy:
+
+```javascript
+const gptrans = new GPTrans({ from: 'es', target: 'fr' });
+await gptrans.preload({
+  references: ['en', 'pt']  // AI sees English and Portuguese as reference
+});
+```
+
+### Pre-translate using an alternate base language
+
+Translate from an intermediate language instead of the original (useful for gender-neutral intermediaries):
+
+```javascript
+const gptrans = new GPTrans({ from: 'es', target: 'pt' });
+await gptrans.preload({
+  baseLanguage: 'en',       // translate FROM English instead of Spanish
+  references: ['es']        // show original Spanish for context
+});
+```
+
+### Set context for gender-aware translations
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+
+// Context applies to next translation(s) in the batch
+console.log(gptrans.setContext('The user is female').t('You are welcome'));
+
+// Reset context
+console.log(gptrans.setContext().t('Thank you'));
+```
+
+### Refine existing translations
+
+Improve cached translations with specific instructions:
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+
+// Single instruction
+await gptrans.refine('Use a more colloquial tone');
+
+// Multiple instructions (single API pass — preferred)
+await gptrans.refine([
+  'Use "vos" instead of "tu"',
+  'Shorten texts where possible without losing meaning',
+  'Use a more friendly and natural tone'
+]);
+
+// Custom refine prompt
+await gptrans.refine('More formal', { promptFile: './my-refine-prompt.md' });
+```
+
+### Translate an image
+
+Requires `GEMINI_API_KEY`. Auto-detects language folders for output path:
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es' });
+
+// en/banner.jpg → es/banner.jpg (auto sibling folder)
+const translatedPath = await gptrans.img('en/banner.jpg');
+
+// With options
+const result = await gptrans.img('en/hero.jpg', {
+  quality: '1K',
+  jpegQuality: 92,
+  prompt: 'Translate all visible text to Spanish. Keep layout and style.'
+});
+```
+
+### Freeze mode (prevent new translations)
+
+```javascript
+const gptrans = new GPTrans({ from: 'en', target: 'es', freeze: true });
+
+// Returns original text, logs "[key] text" — nothing queued
+console.log(gptrans.t('New text'));
+
+// Toggle at runtime
+gptrans.setFreeze(false);
+```
+
+### Purge orphaned translations
+
+Remove cached translations whose source text no longer exists:
+
+```javascript
+await gptrans.purge();
+```
+
+### Translate between regional variants
+
+```javascript
+// Spain Spanish → Argentina Spanish
+const es2ar = new GPTrans({
+  from: 'es-ES',
+  target: 'es-AR',
+  model: 'sonnet45'
+});
+
+console.log(es2ar.t('Eres muy bueno'));
+```
+
+### Check language availability
+
+```javascript
+import GPTrans from 'gptrans';
+
+if (GPTrans.isLanguageAvailable('pt-BR')) {
+  // Language is supported
+}
+```
+
+## Agent Usage Rules
+
+- Always check `package.json` for `gptrans` before running `npm install`.
+- Store API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`) in `.env`. Never hardcode keys.
+- Use BCP 47 language tags for `from` and `target` (e.g., `en-US`, `es-AR`, `pt-BR`, or just `es`).
+- The `t()` method is synchronous and non-blocking. It returns the original text on first call and the cached translation on subsequent calls. Do NOT `await` it.
+- To ensure translations are complete before using them, call `await gptrans.preload()` after registering texts with `t()`.
+- Use `setContext()` for gender-aware or domain-specific translations. Context is captured per-batch and auto-resets when changed.
+- 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.
+- 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.
+- Do NOT use `freeze: true` during initial translation — it prevents all new translations from being queued.
+- Variables in curly braces (`{name}`, `{count}`) in source text are preserved through translation. Parameter substitution happens at `t()` call time.
+
+## API Quick Reference
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `new GPTrans(options)` | `GPTrans` | Create instance with `from`, `target`, `model`, etc. |
+| `.t(text, params?)` | `string` | Translate text (sync). Returns cached or original. |
+| `.get(key, text)` | `string \| undefined` | Get translation by key, queue if missing. |
+| `.setContext(context?)` | `this` | Set context for next batch (gender, tone, etc.). |
+| `.setFreeze(freeze?)` | `this` | Enable/disable freeze mode at runtime. |
+| `await .preload(options?)` | `this` | Pre-translate all pending texts. Options: `{ references, baseLanguage }`. |
+| `await .refine(instruction, options?)` | `this` | Refine existing translations. Accepts string or array. |
+| `await .img(path, options?)` | `string` | Translate image text. Returns output path. |
+| `await .purge()` | `this` | Remove orphaned translations from cache. |
+| `GPTrans.isLanguageAvailable(code)` | `boolean` | Check if a language code is supported. |
+
+## References
+
+- [GitHub Repository](https://github.com/clasen/GPTrans)
+- [npm Package](https://www.npmjs.com/package/gptrans)
+- [ModelMix (underlying LLM library)](https://github.com/clasen/ModelMix)