@loonylabs/tti-middleware 1.4.0 → 1.5.0

package/.env.example

@@ -16,7 +16,7 @@ TTI_DEFAULT_PROVIDER=google-cloud
 # Google Cloud (Vertex AI) - RECOMMENDED FOR EU/GDPR
 # ============================================================
 # DPA: https://cloud.google.com/terms/data-processing-addendum
-# Models: imagen-3, gemini-flash-image (character consistency)
+# Models: imagen-3, imagen-4 (+ fast/ultra), gemini-flash-image, gemini-pro-image
 
 # Project ID (required)
 GOOGLE_CLOUD_PROJECT=your-google-cloud-project-id

package/README.md

@@ -2,7 +2,7 @@
 
 # TTI Middleware
 
-*Provider-agnostic Text-to-Image middleware with **GDPR compliance** and **character consistency** support. Currently supports Google Cloud (Imagen 3, Gemini Flash Image), Eden AI, and IONOS. Features EU data residency via Vertex AI, automatic region fallback, retry logic, and comprehensive error handling.*
+*Provider-agnostic Text-to-Image middleware with **GDPR compliance** and **character consistency** support. Currently supports Google Cloud (Imagen 3, Imagen 4, Gemini Flash Image, Gemini 3 Pro Image), Eden AI, and IONOS. Features EU data residency via Vertex AI, automatic region fallback, retry logic, and comprehensive error handling.*
 
 <!-- Horizontal Badge Navigation Bar -->
 [![npm version](https://img.shields.io/npm/v/@loonylabs/tti-middleware.svg?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@loonylabs/tti-middleware)
@@ -40,7 +40,7 @@
 ## Features
 
 - **Multi-Provider Architecture**: Unified API for all TTI providers
-  - **Google Cloud** (Recommended): Imagen 3 & Gemini Flash Image with EU data residency
+  - **Google Cloud** (Recommended): Imagen 3, Imagen 4, Gemini Flash Image & Gemini 3 Pro Image with EU data residency
   - **Eden AI**: Aggregator with access to OpenAI, Stability AI, Replicate (experimental)
   - **IONOS**: German cloud provider with OpenAI-compatible API (experimental)
 - **Character Consistency**: Generate consistent characters across multiple images (perfect for children's book illustrations)
@@ -204,12 +204,18 @@ IONOS_API_URL=https://api.ionos.cloud/ai/v1
 
 ### Google Cloud (Recommended)
 
-| Model | ID | Character Consistency | EU Regions |
-|-------|-----|----------------------|------------|
-| **Imagen 3** | `imagen-3` | No | All EU regions |
-| **Gemini Flash Image** | `gemini-flash-image` | **Yes** | europe-west1, europe-west4, europe-north1 |
+| Model | ID | Character Consistency | EU Regions | Max Images |
+|-------|-----|----------------------|------------|------------|
+| **Imagen 3** | `imagen-3` | No | All EU regions | 4 |
+| **Imagen 4** | `imagen-4` | No | All EU regions | 4 |
+| **Imagen 4 Fast** | `imagen-4-fast` | No | All EU regions | 4 |
+| **Imagen 4 Ultra** | `imagen-4-ultra` | No | All EU regions | 4 |
+| **Gemini Flash Image** | `gemini-flash-image` | **Yes** | europe-west1, europe-west4, europe-north1 | 1 |
+| **Gemini 3 Pro Image** | `gemini-pro-image` | No | `global` endpoint (auto-routed) | 1 |
 
-**Important:** `gemini-flash-image` is **NOT available** in `europe-west3` (Frankfurt)!
+**Important:**
+- `gemini-flash-image` is **NOT available** in `europe-west3` (Frankfurt) - auto-fallback to EU alternative
+- `gemini-pro-image` requires the **`global` Vertex AI endpoint** - the middleware handles this automatically
 
 ### Eden AI (Experimental)
 
@@ -227,13 +233,13 @@ IONOS_API_URL=https://api.ionos.cloud/ai/v1
 
 ### Google Cloud Region Availability
 
-| Region | Location | Imagen 3 | Gemini Flash Image |
-|--------|----------|----------|-------------------|
-| `europe-west1` | Belgium | Yes | Yes |
-| `europe-west3` | Frankfurt | Yes | **No** |
-| `europe-west4` | Netherlands | Yes | **Yes (Recommended)** |
-| `europe-north1` | Finland | Yes | Yes |
-| `europe-west9` | Paris | Yes | No |
+| Region | Location | Imagen 3 | Imagen 4 | Gemini Flash Image | Gemini Pro Image |
+|--------|----------|----------|----------|-------------------|-----------------|
+| `europe-west1` | Belgium | Yes | Yes | Yes | `global` endpoint |
+| `europe-west3` | Frankfurt | Yes | Yes | **No** | `global` endpoint |
+| `europe-west4` | Netherlands | Yes | Yes | **Yes (Recommended)** | `global` endpoint |
+| `europe-north1` | Finland | Yes | Yes | Yes | `global` endpoint |
+| `europe-west9` | Paris | Yes | Yes | No | `global` endpoint |
 
 ## Character Consistency
 
@@ -354,7 +360,7 @@ class TTIService {
 ```typescript
 interface TTIRequest {
   prompt: string;
-  model?: string;           // 'imagen-3', 'gemini-flash-image', etc.
+  model?: string;           // 'imagen-3', 'imagen-4', 'gemini-flash-image', 'gemini-pro-image', etc.
   n?: number;               // Number of images (default: 1)
   aspectRatio?: string;     // '1:1', '16:9', '4:3', etc.
 

package/dist/middleware/services/tti/providers/base-tti-provider.d.ts

@@ -22,7 +22,8 @@ export declare class ProviderUnavailableError extends TTIError {
     constructor(provider: string, message?: string, cause?: Error);
 }
 export declare class GenerationFailedError extends TTIError {
-    constructor(provider: string, message: string, cause?: Error);
+    readonly modelResponse?: string;
+    constructor(provider: string, message: string, cause?: Error, modelResponse?: string);
 }
 export declare class NetworkError extends TTIError {
     constructor(provider: string, message: string, cause?: Error);

package/dist/middleware/services/tti/providers/base-tti-provider.js

@@ -55,9 +55,10 @@ class ProviderUnavailableError extends TTIError {
 }
 exports.ProviderUnavailableError = ProviderUnavailableError;
 class GenerationFailedError extends TTIError {
-    constructor(provider, message, cause) {
+    constructor(provider, message, cause, modelResponse) {
         super(provider, 'GENERATION_FAILED', message, cause);
         this.name = 'GenerationFailedError';
+        this.modelResponse = modelResponse;
     }
 }
 exports.GenerationFailedError = GenerationFailedError;

package/dist/middleware/services/tti/providers/google-cloud-provider.d.ts

@@ -3,7 +3,11 @@
  *
  * Unified provider for Google Cloud's image generation services:
  * - Imagen 3 (imagegeneration@006) - High quality text-to-image
+ * - Imagen 4 (imagen-4.0-generate-001) - Next-gen text-to-image with enhanced quality
+ * - Imagen 4 Fast (imagen-4.0-fast-generate-001) - Faster inference variant
+ * - Imagen 4 Ultra (imagen-4.0-ultra-generate-001) - Highest quality variant
  * - Gemini 2.5 Flash Image - Text-to-image with character consistency
+ * - Gemini 3 Pro Image (gemini-3-pro-image-preview) - 4K, text rendering
  *
  * All requests go through Google Cloud (Vertex AI) with proper DPA.
  * EU-compliant when using EU regions.
@@ -31,7 +35,7 @@ export declare class GoogleCloudTTIProvider extends BaseTTIProvider {
     private config;
     private lastUsedRegion;
     private aiplatformClient;
-    private genaiClient;
+    private genaiClients;
     constructor(config?: Partial<GoogleCloudConfig>);
     getDisplayName(): string;
     listModels(): ModelInfo[];

package/dist/middleware/services/tti/providers/google-cloud-provider.js

@@ -4,7 +4,11 @@
  *
  * Unified provider for Google Cloud's image generation services:
  * - Imagen 3 (imagegeneration@006) - High quality text-to-image
+ * - Imagen 4 (imagen-4.0-generate-001) - Next-gen text-to-image with enhanced quality
+ * - Imagen 4 Fast (imagen-4.0-fast-generate-001) - Faster inference variant
+ * - Imagen 4 Ultra (imagen-4.0-ultra-generate-001) - Highest quality variant
  * - Gemini 2.5 Flash Image - Text-to-image with character consistency
+ * - Gemini 3 Pro Image (gemini-3-pro-image-preview) - 4K, text rendering
  *
  * All requests go through Google Cloud (Vertex AI) with proper DPA.
  * EU-compliant when using EU regions.
@@ -53,7 +57,23 @@ const debug_tti_utils_1 = require("../utils/debug-tti.utils");
 // ============================================================
 // MODEL DEFINITIONS
 // ============================================================
+// Imagen 4 is available in most EU regions
+const IMAGEN_4_REGIONS = [
+    'europe-west1',
+    'europe-west2',
+    'europe-west3',
+    'europe-west4',
+    'europe-west6',
+    'europe-west8',
+    'europe-west9',
+    'europe-north1',
+    'europe-central2',
+    'europe-southwest1',
+    'us-central1',
+    'us-east4',
+];
 const GOOGLE_CLOUD_MODELS = [
+    // ── Imagen models (Vertex AI predict API) ──────────────────
     {
         id: 'imagen-3',
         displayName: 'Imagen 3',
@@ -74,6 +94,43 @@ const GOOGLE_CLOUD_MODELS = [
         ],
         pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
     },
+    {
+        id: 'imagen-4',
+        displayName: 'Imagen 4',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        availableRegions: IMAGEN_4_REGIONS,
+        pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
+    },
+    {
+        id: 'imagen-4-fast',
+        displayName: 'Imagen 4 Fast',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        availableRegions: IMAGEN_4_REGIONS,
+        pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
+    },
+    {
+        id: 'imagen-4-ultra',
+        displayName: 'Imagen 4 Ultra',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        availableRegions: IMAGEN_4_REGIONS,
+        pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
+    },
+    // ── Gemini models (Vertex AI generateContent API) ──────────
     {
         id: 'gemini-flash-image',
         displayName: 'Gemini 2.5 Flash Image',
@@ -93,12 +150,31 @@ const GOOGLE_CLOUD_MODELS = [
         ],
         pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
     },
+    {
+        id: 'gemini-pro-image',
+        displayName: 'Gemini 3 Pro Image',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false, // Not documented for this model
+            imageEditing: false,
+            maxImagesPerRequest: 1,
+        },
+        // Requires global endpoint - regional endpoints return 404
+        availableRegions: ['global'],
+        pricingUrl: 'https://cloud.google.com/vertex-ai/generative-ai/pricing',
+    },
 ];
-// Internal model IDs used in API calls
+// Internal model IDs used in Vertex AI API calls
 const MODEL_ID_MAP = {
     'imagen-3': 'imagegeneration@006',
+    'imagen-4': 'imagen-4.0-generate-001',
+    'imagen-4-fast': 'imagen-4.0-fast-generate-001',
+    'imagen-4-ultra': 'imagen-4.0-ultra-generate-001',
     'gemini-flash-image': 'gemini-2.5-flash-image',
+    'gemini-pro-image': 'gemini-3-pro-image-preview',
 };
+// Models that use the Gemini generateContent API (vs Imagen predict API)
+const GEMINI_API_MODELS = new Set(['gemini-flash-image', 'gemini-pro-image']);
 // ============================================================
 // PROVIDER IMPLEMENTATION
 // ============================================================
@@ -109,7 +185,7 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         // Lazy-loaded SDK clients
         this.aiplatformClient = null;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.genaiClient = null;
+        this.genaiClients = new Map();
         const projectId = config?.projectId ||
             process.env.GOOGLE_CLOUD_PROJECT ||
             process.env.GCLOUD_PROJECT ||
@@ -170,17 +246,13 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
             hasReferenceImages: (0, base_tti_provider_1.hasReferenceImages)(request),
         });
         try {
-            // Route to appropriate implementation with retry support
+            // Route to appropriate API based on model type
             let response;
-            switch (modelId) {
-                case 'imagen-3':
-                    response = await this.executeWithRetry(request, () => this.generateWithImagen(request, effectiveRegion), 'Imagen API call');
-                    break;
-                case 'gemini-flash-image':
-                    response = await this.executeWithRetry(request, () => this.generateWithGemini(request, effectiveRegion), 'Gemini API call');
-                    break;
-                default:
-                    throw new base_tti_provider_1.InvalidConfigError(this.providerName, `Unknown model: ${modelId}`);
+            if (GEMINI_API_MODELS.has(modelId)) {
+                response = await this.executeWithRetry(request, () => this.generateWithGemini(request, modelId, effectiveRegion), 'Gemini API call');
+            }
+            else {
+                response = await this.executeWithRetry(request, () => this.generateWithImagen(request, modelId, effectiveRegion), 'Imagen API call');
             }
             // Log successful response
             if (debugInfo) {
@@ -224,6 +296,11 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         if (!modelInfo?.availableRegions) {
             return this.config.region;
         }
+        // Model requires global endpoint (e.g. preview models)
+        if (modelInfo.availableRegions.length === 1 && modelInfo.availableRegions[0] === 'global') {
+            this.log('info', `Model ${modelId} requires global endpoint`, { configuredRegion: this.config.region, effectiveRegion: 'global' });
+            return 'global';
+        }
         // Check if configured region supports this model
         if (modelInfo.availableRegions.includes(this.config.region)) {
             return this.config.region;
@@ -241,11 +318,11 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         return fallback;
     }
     // ============================================================
-    // PRIVATE: IMAGEN 3 IMPLEMENTATION
+    // PRIVATE: IMAGEN IMPLEMENTATION
     // ============================================================
-    async generateWithImagen(request, region) {
+    async generateWithImagen(request, modelId, region) {
         const startTime = Date.now();
-        const internalModelId = MODEL_ID_MAP['imagen-3'];
+        const internalModelId = MODEL_ID_MAP[modelId];
         this.lastUsedRegion = region;
         try {
             const { client, helpers } = await this.getAiplatformClient();
@@ -284,7 +361,7 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
             if (!response.predictions || response.predictions.length === 0) {
                 throw new base_tti_provider_1.GenerationFailedError(this.providerName, 'No images returned from Imagen API');
             }
-            return this.processImagenResponse(response.predictions, helpers, duration);
+            return this.processImagenResponse(response.predictions, helpers, modelId, duration);
         }
         catch (error) {
             if (error instanceof base_tti_provider_1.InvalidConfigError || error instanceof base_tti_provider_1.GenerationFailedError) {
@@ -323,7 +400,7 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
             helpers: helpers,
         };
     }
-    processImagenResponse(predictions, helpers, duration) {
+    processImagenResponse(predictions, helpers, modelId, duration) {
         const images = [];
         for (const prediction of predictions) {
             const predictionObj = helpers.fromValue(prediction);
@@ -339,13 +416,13 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         }
         const usage = {
             imagesGenerated: images.length,
-            modelId: 'imagen-3',
+            modelId,
         };
         return {
             images,
             metadata: {
                 provider: this.providerName,
-                model: 'imagen-3',
+                model: modelId,
                 region: this.lastUsedRegion || this.config.region,
                 duration,
             },
@@ -353,11 +430,11 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         };
     }
     // ============================================================
-    // PRIVATE: GEMINI FLASH IMAGE IMPLEMENTATION
+    // PRIVATE: GEMINI IMAGE IMPLEMENTATION
     // ============================================================
-    async generateWithGemini(request, region) {
+    async generateWithGemini(request, modelId, region) {
         const startTime = Date.now();
-        const internalModelId = MODEL_ID_MAP['gemini-flash-image'];
+        const internalModelId = MODEL_ID_MAP[modelId];
         this.lastUsedRegion = region;
         try {
             const client = await this.getGenaiClient(region);
@@ -420,7 +497,7 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                 duration,
                 hasCandidates: !!(response?.candidates || response?.response),
             });
-            return this.processGeminiResponse(response, duration);
+            return this.processGeminiResponse(response, modelId, duration);
         }
         catch (error) {
             if (error instanceof base_tti_provider_1.InvalidConfigError || error instanceof base_tti_provider_1.GenerationFailedError) {
@@ -431,19 +508,16 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async getGenaiClient(region) {
-        // Recreate client if region changed
-        if (!this.genaiClient) {
+        // Vertex AI client (one per region, since region is baked into the client)
+        if (!this.genaiClients.has(region)) {
             try {
                 const { GoogleGenAI } = await Promise.resolve().then(() => __importStar(require('@google/genai')));
-                // Set environment variables for Vertex AI backend
-                process.env.GOOGLE_GENAI_USE_VERTEXAI = 'true';
-                process.env.GOOGLE_CLOUD_PROJECT = this.config.projectId;
-                process.env.GOOGLE_CLOUD_LOCATION = region;
-                this.genaiClient = new GoogleGenAI({
+                const client = new GoogleGenAI({
                     vertexai: true,
                     project: this.config.projectId,
                     location: region,
                 });
+                this.genaiClients.set(region, client);
                 this.log('debug', 'Initialized @google/genai with Vertex AI backend', {
                     project: this.config.projectId,
                     location: region,
@@ -453,10 +527,11 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                 throw new base_tti_provider_1.InvalidConfigError(this.providerName, `Failed to load @google/genai. Install it with: npm install @google/genai`, error);
             }
         }
+        const client = this.genaiClients.get(region);
         return {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             generateContent: async (params) => {
-                return this.genaiClient.models.generateContent(params);
+                return client.models.generateContent(params);
             },
         };
     }
@@ -467,7 +542,7 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
 IMPORTANT: Maintain exact visual consistency with the subject in the reference - same style, colors, proportions, and distinctive features. The subject should be immediately recognizable as the same one from the reference.`;
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    processGeminiResponse(response, duration) {
+    processGeminiResponse(response, modelId, duration) {
         const images = [];
         const candidates = response?.candidates || response?.response?.candidates;
         if (!candidates || candidates.length === 0) {
@@ -486,9 +561,12 @@ IMPORTANT: Maintain exact visual consistency with the subject in the reference -
         }
         if (images.length === 0) {
             const firstParts = candidates[0]?.content?.parts || [];
+            const fullTexts = [];
             const partTypes = firstParts.map((p) => {
-                if (p.text)
-                    return `text(${p.text.substring(0, 50)}...)`;
+                if (p.text) {
+                    fullTexts.push(p.text);
+                    return `text(${p.text.substring(0, 200)}${p.text.length > 200 ? '...' : ''})`;
+                }
                 if (p.inlineData)
                     return `inlineData(${p.inlineData.mimeType})`;
                 return 'unknown';
@@ -496,19 +574,21 @@ IMPORTANT: Maintain exact visual consistency with the subject in the reference -
             this.log('error', 'No images in Gemini response', {
                 candidateCount: candidates.length,
                 partTypes,
+                ...(fullTexts.length > 0 && { modelResponse: fullTexts.join('\n') }),
             });
+            const fullModelResponse = fullTexts.length > 0 ? fullTexts.join('\n') : undefined;
             throw new base_tti_provider_1.GenerationFailedError(this.providerName, `No images in response. Model returned: ${partTypes.join(', ')}. ` +
-                'Make sure responseModalities includes IMAGE.');
+                'Make sure responseModalities includes IMAGE.', undefined, fullModelResponse);
         }
         const usage = {
             imagesGenerated: images.length,
-            modelId: 'gemini-flash-image',
+            modelId,
         };
         return {
             images,
             metadata: {
                 provider: this.providerName,
-                model: 'gemini-flash-image',
+                model: modelId,
                 region: this.lastUsedRegion || this.config.region,
                 duration,
             },

package/dist/middleware/services/tti/utils/debug-tti.utils.d.ts

@@ -45,6 +45,7 @@ export interface TTIDebugInfo {
         message: string;
         code?: string;
         details?: unknown;
+        modelResponse?: string;
     };
 }
 /**
@@ -145,6 +146,7 @@ export declare class TTIDebugger {
     static updateWithError(debugInfo: TTIDebugInfo, error: Error & {
         code?: string;
         cause?: unknown;
+        modelResponse?: string;
     }): TTIDebugInfo;
 }
 export default TTIDebugger;

package/dist/middleware/services/tti/utils/debug-tti.utils.js

@@ -297,6 +297,9 @@ class TTIDebugger {
             if (debugInfo.error.code) {
                 sections.push(`- **Code**: ${debugInfo.error.code}`);
             }
+            if (debugInfo.error.modelResponse) {
+                sections.push(`- **Model Response**: ${debugInfo.error.modelResponse}`);
+            }
             if (debugInfo.error.details) {
                 sections.push('- **Details**:');
                 sections.push('```json');
@@ -401,6 +404,7 @@ class TTIDebugger {
                 message: error.message,
                 code: error.code,
                 details: error.cause,
+                modelResponse: error.modelResponse,
             },
         };
     }

package/dist/middleware/types/index.d.ts

@@ -50,7 +50,7 @@ export interface ModelInfo {
  * Google Cloud regions
  * EU regions are GDPR-compliant
  */
-export type GoogleCloudRegion = 'europe-west1' | 'europe-west2' | 'europe-west3' | 'europe-west4' | 'europe-west9' | 'us-central1' | 'us-east4';
+export type GoogleCloudRegion = 'global' | 'europe-west1' | 'europe-west2' | 'europe-west3' | 'europe-west4' | 'europe-west9' | 'us-central1' | 'us-east4';
 /**
  * Reference image for character consistency
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loonylabs/tti-middleware",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Provider-agnostic Text-to-Image middleware with GDPR compliance. Supports Google Cloud (Imagen, Gemini), Eden AI, and IONOS.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",