gptrans 2.1.10 → 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,11 +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';
 
+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
@@ -74,9 +78,10 @@ When creating a new instance of GPTrans, you can customize:
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| `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 | `''` |
@@ -96,7 +101,7 @@ For simplified or universal language codes, you can omit the region specificatio
 ## 🔍 How It Works
 
 1. **First-Time Translation Behavior:** On the first request, Gptrans will return the original text while processing the translation in the background. This ensures your application remains responsive without waiting for API calls.
-2. **Translation Caching:** Once processed, translations are stored in `db/gptrans_<tag>.json`. Subsequent requests for the same text will be served instantly from the cache.
+2. **Translation Caching:** Once processed, translations are stored as `gptrans_<tag>.json` under the required absolute `path`. Subsequent requests for the same text will be served instantly from the cache.
 3. **Smart Batch Processing:** Automatically groups translation requests to optimize API usage and provide better context.
 4. **Dynamic Model Integration:** Easily plug in multiple AI translation providers with the ModelMix library.
 5. **Customizable Prompts:** Load and modify translation prompts (see the `prompt/translate.md` file) to fine-tune the translation output.
@@ -132,6 +137,7 @@ The `instruction` option lets you guide the AI translator's style, tone, or beha
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en',
   target: 'es-AR',
   instruction: 'Use natural and colloquial tone'
@@ -168,7 +174,7 @@ Include translations from other languages as context to improve accuracy and con
 
 ```javascript
 // Use English and Portuguese translations as reference
-const gptrans = new GPTrans({ from: 'es', target: 'fr' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'fr' });
 await gptrans.preload({ 
   references: ['en', 'pt'] 
 });
@@ -182,7 +188,7 @@ Translate from an intermediate language instead of the original:
 
 ```javascript
 // Original is Spanish, but translate FROM English TO Portuguese
-const gptrans = new GPTrans({ from: 'es', target: 'pt' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await gptrans.preload({ 
   baseLanguage: 'en' 
 });
@@ -199,7 +205,7 @@ You can use both options together:
 
 ```javascript
 // Translate from English to German, showing Spanish and Portuguese as reference
-const gptrans = new GPTrans({ from: 'es', target: 'de' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'de' });
 await gptrans.preload({ 
   baseLanguage: 'en',
   references: ['es', 'pt'] 
@@ -215,7 +221,7 @@ await gptrans.preload({
 // English: "The student is very good" (neutral)
 
 // Solution: Translate to Portuguese using English as base
-const ptTranslator = new GPTrans({ from: 'es', target: 'pt' });
+const ptTranslator = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await ptTranslator.preload({ 
   baseLanguage: 'en',     // Use neutral English version
   references: ['es']       // Show original Spanish for context
@@ -236,7 +242,8 @@ GPTrans supports a fallback mechanism for translation models. Instead of providi
 
 ```javascript
 const translator = new GPTrans({
-  model: ['claude46', 'gpt54'],
+  path: dbPath,
+  model: ['sonnet5@50', 'gpt56luna@100'],
   // ... other options
 });
 ```
@@ -244,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
@@ -251,7 +259,7 @@ When using multiple models:
 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' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // After translations already exist...
 // Refine with a single instruction
@@ -306,4 +314,3 @@ Contributions are welcome! Please open an issue or submit a pull request on GitH
 GPTrans is released under the MIT License.
 
 Happy translating! 🌍✨
-

package/demo/case_1.js

@@ -1,6 +1,9 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
 
-const gptrans = new GPTrans({ model: 'sonnet45' });
+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' }));
 
@@ -14,6 +17,7 @@ console.log(gptrans.t('Card'));
 
 // Case 2: Translate from Spanish Spain to Spanish Argentina
 const es2ar = new GPTrans({
+    path: dbPath,
     from: 'es-ES',
     target: 'es-AR',
     model: 'sonnet46'
@@ -25,10 +29,10 @@ console.log(es2ar.setContext().t('Tienes fuego?'));
 
 // Case 3
 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,7 +1,12 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
+
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 try {
     const gptrans = new GPTrans({
+        path: dbPath,
         target: 'it',
     });
 
@@ -17,4 +22,4 @@ try {
     console.log(gptrans.t('Card'));
 } catch (e) {
     console.error(e);
-}
+}

package/demo/case_3.js

@@ -1,7 +1,12 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
+
+const dbPath = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 try {
     const gptrans = new GPTrans({
+        path: dbPath,
         target: 'ar',
         from: 'es',
     });
@@ -9,4 +14,4 @@ try {
     console.log(gptrans.t('Cargando...'));
 } catch (e) {
     console.error(e);
-}
+}

package/demo/case_4.js

@@ -1,14 +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 = join(import.meta.dirname, '../db');
+try { process.loadEnvFile(join(import.meta.dirname, '.env')); } catch { }
 
 // Initialize translator
 const model = new GPTrans({
-    model: ['sonnet46', 'gpt54'],
+    path: dbPath,
+    model: ['sonnet50', 'gpt56luna@80'],
     from: 'es',  // Assuming the source file is in Spanish
     target: 'en',
 });
@@ -17,11 +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,8 +1,13 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
+
+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
 
 const gptrans = new GPTrans({
+    path: dbPath,
     from: 'es',
     target: 'en',
 });
@@ -25,6 +30,7 @@ console.log('  Gentilicio:', gptrans.replaceFrom.FROM_DENONYM);        // 'Spani
 console.log('\n📌 Ejemplo con variantes regionales:');
 
 const gptrans2 = new GPTrans({
+    path: dbPath,
     from: 'en-GB',
     target: 'pt-BR',
 });

package/demo/case_parallelism.js

@@ -1,15 +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);
-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');
@@ -43,6 +37,7 @@ async function testParallelTranslations() {
         texts.map(async (text, index) => {
             // Todas las instancias comparten el MISMO NOMBRE
             const gptrans = new GPTrans({ 
+                path: dbPath,
                 from: sourceLang, 
                 target: targetLang,
                 model: 'sonnet45',

package/demo/case_references.js

@@ -1,15 +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);
-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));
@@ -19,6 +13,7 @@ async function testReferences() {
     
     // First, create translations in English and Portuguese
     const enTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'en',
         model: 'sonnet45',
@@ -27,6 +22,7 @@ async function testReferences() {
     });
     
     const ptTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'pt',
         model: 'sonnet45',
@@ -63,6 +59,7 @@ async function testReferences() {
     
     // Now translate to French using English as reference
     const frTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'fr',
         model: 'sonnet45',
@@ -86,6 +83,7 @@ async function testReferences() {
     
     // Translate from English to Italian (using English as base instead of Spanish)
     const itTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'it',
         model: 'sonnet45',
@@ -110,6 +108,7 @@ async function testReferences() {
     
     // Translate to German with multiple references
     const deTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'de',
         model: 'sonnet45',

package/demo/case_refine.js

@@ -1,4 +1,8 @@
 import GPTrans from '../index.js';
+import { join } from 'path';
+
+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));
@@ -6,6 +10,7 @@ console.log('='.repeat(70));
 async function testRefine() {
     // Step 1: Create initial translations
     const gptrans = new GPTrans({
+        path: dbPath,
         from: 'en-US',
         target: 'es-AR',
         model: 'sonnet45',

package/demo/example-image-translation.js

@@ -2,15 +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(import.meta.dirname, 'db'),
             from: 'en-US',
             target: 'es'
         });
@@ -23,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);
@@ -38,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);
@@ -53,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);
@@ -81,4 +78,3 @@ async function main() {
 }
 
 main();
-