@l10nmonster/helpers-anthropic 3.0.0-alpha.1

package/README.md

@@ -0,0 +1,106 @@
+# L10nMonster Anthropic Helper
+
+This package provides integration between L10nMonster and Anthropic's Claude models via both direct API and Google Vertex AI.
+
+## Installation
+
+```bash
+npm install @l10nmonster/helpers-anthropic
+```
+
+## Usage
+
+### Direct API Configuration
+
+```javascript
+import { AnthropicAgent } from '@l10nmonster/helpers-anthropic';
+
+const agent = new AnthropicAgent({
+    id: 'claude-translator',
+    model: 'claude-3-5-sonnet-latest',
+    quality: 80,
+    temperature: 0.1,
+    maxTokens: 4096,
+    apiKey: 'your-anthropic-api-key'  // Direct API access
+});
+```
+
+### Vertex AI Configuration
+
+```javascript
+import { AnthropicAgent } from '@l10nmonster/helpers-anthropic';
+
+const agent = new AnthropicAgent({
+    id: 'claude-translator',
+    model: 'claude-3-5-sonnet@20241022',
+    quality: 80,
+    temperature: 0.1,
+    maxTokens: 4096,
+    vertexProject: 'your-gcp-project-id',
+    vertexLocation: 'us-central1'
+});
+```
+
+### Authentication
+
+The AnthropicAgent supports two authentication methods:
+
+#### Direct API
+1. **API Key**: Obtain an API key from [Anthropic Console](https://console.anthropic.com/)
+2. **Set apiKey**: Pass your API key in the configuration
+
+#### Vertex AI
+1. **Service Account**: Set up a service account with Vertex AI permissions
+2. **gcloud CLI**: Run `gcloud auth login` and `gcloud config set project YOUR_PROJECT_ID`
+3. **Environment Variables**: Set `GOOGLE_APPLICATION_CREDENTIALS` to point to your service account key file
+
+### Retry Behavior
+
+The AnthropicAgent uses the native retry mechanism built into both the Anthropic SDK and Anthropic Vertex SDK:
+
+- **Automatic Retries**: Both SDKs automatically handle retries with exponential backoff
+- **Configurable**: Set `maxRetries` in the constructor to control retry attempts (passed directly to both SDKs)
+- **Smart Error Handling**: Automatically retries on network errors, rate limits, and temporary service issues
+- **No Manual Implementation**: Unlike other providers, this uses the SDK's native retry logic for better reliability
+- **Consistent Behavior**: The same `maxRetries` value is used whether you're using direct API or Vertex AI
+
+### Configuration Options
+
+- `model` (required): The Claude model to use
+- `quality` (required): Quality score for translations (0-100)
+- `apiKey`: Your Anthropic API key (for direct API access)
+- `temperature`: Controls randomness (0.0-1.0, default: 0.1)
+- `maxTokens`: Maximum output tokens (default: 4096)
+- `maxRetries`: Maximum number of retries (passed to Anthropic SDK)
+- `vertexProject`: GCP project ID (for Vertex AI, auto-detected if not provided)
+- `vertexLocation`: GCP region (for Vertex AI, default: 'global')
+- `persona`: Custom translator persona (optional)
+- `customSchema`: Custom response schema (optional)
+
+## Testing
+
+Run the test suite using Node.js built-in testing:
+
+```bash
+# From the package directory
+npm test
+
+# From the workspace root
+npm test --workspace=helpers-anthropic
+```
+
+The test suite includes:
+- Unit tests for all major functionality
+- Integration tests with the LLMTranslationProvider inheritance
+- Error handling and edge case scenarios
+- Mock testing without external API calls
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Google Cloud Project with Vertex AI API enabled
+- Proper authentication setup for Google Cloud
+
+## License
+
+MIT 

package/anthropicAgent.js

@@ -0,0 +1,183 @@
+import { AnthropicVertex } from '@anthropic-ai/vertex-sdk';
+import Anthropic from '@anthropic-ai/sdk';
+import { GoogleAuth } from 'google-auth-library';
+
+import { logInfo, logVerbose, logWarn, providers, styleString } from '../core/index.js';
+
+const TRANSLATION_TOOL = {
+    name: 'provide_translations',
+    description: 'Provide translations for the given strings',
+    input_schema: {
+        type: 'object',
+        properties: {
+            translations: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        translation: { type: 'string', description: 'the translated string' },
+                        confidence: { type: 'number', description: 'a confidence score between 0 and 100' },
+                        notes: { type: 'string', description: 'any additional notes about the translation' }
+                    },
+                    required: ['translation', 'confidence', 'notes']
+                }
+            }
+        },
+        required: ['translations']
+    }
+};
+
+/**
+ * @typedef {object} AnthropicAgentOptions
+ * @extends LLMTranslationProviderOptions
+ * @property {string} [apiKey] - The Anthropic API key (if using direct API).
+ * @property {string} [vertexProject] - The VertexAI project ID.
+ * @property {string} [vertexLocation] - The VertexAI datacenter location.
+ * @property {number} [maxTokens] - Maximum number of output tokens (32000 by default)
+ */
+
+/**
+ * Provider for Anthropic Claude LLMs via Vertex AI or direct API.
+ */
+export class AnthropicAgent extends providers.LLMTranslationProvider {
+    #client;
+    #apiKey;
+    #vertexProject;
+    #vertexLocation;
+    #maxTokens;
+    #maxRetries;
+
+    /**
+     * Initializes a new instance of the AnthropicAgent class.
+     * @param {AnthropicAgentOptions} options - Configuration options for the provider.
+     */
+    constructor({ apiKey, vertexProject, vertexLocation, maxTokens, maxRetries, ...options }) {
+        super({...options, maxRetries: 0}); // bypass our own retry logic since Anthropic SDK has built-in support
+        this.#apiKey = apiKey;
+        this.#vertexProject = vertexProject;
+        this.#vertexLocation = vertexLocation ?? 'us-east5';
+        this.#maxTokens = maxTokens ?? 32000;
+        this.#maxRetries = maxRetries ?? 2;
+    }
+
+    // we initialize on first use so that constructor is fast and doesn't fail if auth is missing
+    // also, we need this to be async so that we can await for projectId if it's not provided
+    async lazyInit() {
+        if (this.#client) {
+            return;
+        }
+        if (this.#apiKey) {
+            // Direct Anthropic API
+            this.#client = new Anthropic({
+                apiKey: this.#apiKey,
+                maxRetries: this.#maxRetries,
+                timeout: 15 * 60000, // 15 minutes
+            });
+            logInfo`AnthropicAgent ${this.id} initialized with direct Anthropic API`;
+        } else {
+            if (!this.#vertexProject) {
+                try {
+                    const auth = new GoogleAuth({});
+                    this.#vertexProject = await auth.getProjectId();
+                } catch (e) {
+                    throw new Error(`Couldn't get credentials, did you run 'gcloud auth login'?\n${e.message}`);
+                }
+            }
+            this.#client = new AnthropicVertex({
+                projectId: this.#vertexProject,
+                region: this.#vertexLocation,
+                maxRetries: this.#maxRetries,
+                timeout: 15 * 60000, // 15 minutes
+            });
+            logInfo`AnthropicAgent ${this.id} initialized with Vertex AI platform (${this.#vertexLocation}/${this.#vertexProject})`;
+        }
+    }
+
+    prepareTranslateChunkArgs({ sourceLang, targetLang, xmlTus, instructions }) {
+        const userPrompt = this.buildUserPrompt({ sourceLang, targetLang, xmlTus, instructions });
+        
+        const messages = [
+            {
+                role: 'user',
+                content: userPrompt
+            }
+        ];
+
+        const toolConfig = this.customSchema ? {
+            tools: [{
+                name: 'provide_custom_translations',
+                description: 'Provide translations using custom schema',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        translations: {
+                            type: 'array',
+                            items: this.customSchema
+                        }
+                    },
+                    required: ['translations']
+                }
+            }],
+            tool_choice: { type: 'tool', name: 'provide_custom_translations' }
+        } : {
+            tools: [TRANSLATION_TOOL],
+            tool_choice: { type: 'tool', name: 'provide_translations' }
+        };
+
+        return {
+            model: this.model,
+            max_tokens: this.#maxTokens,
+            temperature: this.temperature,
+            system: this.systemPrompt,
+            messages,
+            ...toolConfig
+        };
+    }
+
+    async generateContent(args) {
+        return await this.#client.messages.create(args);
+    }
+
+    convertTranslationResponse(res) {
+        try {
+            if (res.stop_reason !== 'tool_use') {
+                throw new Error(`Unexpected stop reason: ${res.stop_reason}`);
+            }
+
+            // Find the tool use content
+            const toolUse = res.content.find(content => content.type === 'tool_use');
+            if (!toolUse) {
+                throw new Error('No tool use found in response');
+            }
+
+            const translations = toolUse.input.translations;
+            if (!Array.isArray(translations)) {
+                throw new Error('Invalid translations format');
+            }
+
+            const cost = [
+                (res.usage.input_tokens ?? 0) / translations.length,
+                (res.usage.output_tokens ?? 0) / translations.length,
+                ((res.usage.input_tokens ?? 0) + (res.usage.output_tokens ?? 0)) / translations.length,
+            ];
+
+            return this.processTranslations(translations, cost);
+        } catch (e) {
+            logWarn`Unexpected convertTranslationResponse error: ${e.message}`;
+            return [];
+        }
+    }
+
+    async info() {
+        const info = await super.info();
+        try {
+            await this.lazyInit();
+            // SDK doesn't support listing models or getting model info on Vertex AI
+            const models = ['claude-opus-4-20250514', 'claude-sonnet-4-20250514'];
+            info.description.push(styleString`Supported models: ${models.join(', ')}`);
+        } catch (e) {
+            info.description.push(styleString`Unable to connect to Anthropic server: ${e.cause?.message ?? e.message}`);
+        }
+        return info;
+    }
+}

package/example.js

@@ -0,0 +1,65 @@
+import { AnthropicAgent } from './index.js';
+
+// Example L10nMonster configuration using AnthropicAgent
+export const exampleConfig = {
+    translationProviders: [
+        // Direct API configuration
+        {
+            id: 'claude-direct-api',
+            provider: AnthropicAgent,
+            options: {
+                model: 'claude-3-5-sonnet-latest',
+                quality: 90,
+                temperature: 0.1,
+                maxTokens: 4096,
+                maxRetries: 3,                    // Passed to Anthropic SDK for native retry handling
+                apiKey: process.env.ANTHROPIC_API_KEY, // Set your API key
+                persona: 'You are a professional translator specializing in technical documentation and user interfaces.',
+            }
+        },
+        // Vertex AI configuration
+        {
+            id: 'claude-vertex-sonnet',
+            provider: AnthropicAgent,
+            options: {
+                model: 'claude-3-5-sonnet@20241022',
+                quality: 85,
+                temperature: 0.1,
+                maxTokens: 4096,
+                // vertexProject: 'your-gcp-project-id', // Optional, auto-detected
+                vertexLocation: 'us-central1',
+                persona: 'You are a professional translator specializing in technical documentation and user interfaces.',
+            }
+        },
+        {
+            id: 'claude-vertex-haiku',
+            provider: AnthropicAgent,
+            options: {
+                model: 'claude-3-5-haiku@20241022',
+                quality: 80,
+                temperature: 0.1,
+                maxTokens: 2048,
+                vertexLocation: 'us-central1',
+                persona: 'You are a fast and efficient translator focused on accuracy and consistency.',
+            }
+        }
+    ],
+    
+    // Example translation jobs configuration
+    jobs: [
+        {
+            id: 'ui-translation',
+            translationProvider: 'claude-direct-api',
+            instructions: 'Translate user interface strings. Keep labels concise and maintain consistent terminology.',
+        },
+        {
+            id: 'content-translation',
+            translationProvider: 'claude-vertex-haiku',
+            instructions: 'Translate general content while maintaining the original tone and style.',
+        }
+    ]
+};
+
+// Example usage
+console.log('AnthropicAgent configuration example loaded');
+console.log('Available providers:', exampleConfig.translationProviders.map(p => p.id)); 

package/index.js

@@ -0,0 +1 @@
+export { AnthropicAgent } from './anthropicAgent.js'; 

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@l10nmonster/helpers-anthropic",
+  "version": "3.0.0-alpha.1",
+  "description": "Anthropic Claude LLM provider for l10nmonster using Vertex AI",
+  "type": "module",
+  "main": "anthropicAgent.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@anthropic-ai/vertex-sdk": "latest",
+    "@anthropic-ai/sdk": "latest",
+    "google-auth-library": "^10"
+  },
+  "peerDependencies": {
+            "@l10nmonster/core": "file:../core"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}