@loonylabs/tti-middleware 1.0.0

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

@@ -0,0 +1,98 @@
+/**
+ * Base TTI Provider Abstract Class
+ *
+ * All providers must extend this class and implement the ITTIProvider interface.
+ * Provides common functionality for error handling, logging, and validation.
+ */
+import { TTIProvider, TTIRequest, TTIResponse, TTIErrorCode, ITTIProvider, ModelInfo, RetryOptions, LogLevel } from '../../../types';
+export declare class TTIError extends Error {
+    readonly provider: string;
+    readonly code: TTIErrorCode;
+    readonly cause?: Error | undefined;
+    constructor(provider: string, code: TTIErrorCode, message: string, cause?: Error | undefined);
+    toString(): string;
+}
+export declare class InvalidConfigError extends TTIError {
+    constructor(provider: string, message: string, cause?: Error);
+}
+export declare class QuotaExceededError extends TTIError {
+    constructor(provider: string, message?: string, cause?: Error);
+}
+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);
+}
+export declare class NetworkError extends TTIError {
+    constructor(provider: string, message: string, cause?: Error);
+}
+export declare class CapabilityNotSupportedError extends TTIError {
+    constructor(provider: string, capability: string, model: string, cause?: Error);
+}
+/**
+ * Set the global log level for all TTI providers
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get the current global log level
+ */
+export declare function getLogLevel(): LogLevel;
+export declare abstract class BaseTTIProvider implements ITTIProvider {
+    protected readonly providerName: TTIProvider;
+    constructor(providerName: TTIProvider);
+    abstract getDisplayName(): string;
+    abstract listModels(): ModelInfo[];
+    abstract getDefaultModel(): string;
+    abstract generate(request: TTIRequest): Promise<TTIResponse>;
+    getName(): TTIProvider;
+    /**
+     * Get model info by ID
+     */
+    protected getModelInfo(modelId: string): ModelInfo | undefined;
+    /**
+     * Check if a model supports a specific capability
+     */
+    protected modelSupportsCapability(modelId: string, capability: keyof ModelInfo['capabilities']): boolean;
+    /**
+     * Validate that the request is valid
+     */
+    protected validateRequest(request: TTIRequest): void;
+    /**
+     * Resolve retry configuration from request
+     */
+    protected resolveRetryConfig(request: TTIRequest): Required<RetryOptions> | null;
+    /**
+     * Calculate delay for a specific retry attempt
+     */
+    protected calculateRetryDelay(attempt: number, config: Required<RetryOptions>): number;
+    /**
+     * Sleep for a specified duration
+     */
+    protected sleep(ms: number): Promise<void>;
+    /**
+     * Execute a generation function with retry logic for rate limits
+     */
+    protected executeWithRetry<T>(request: TTIRequest, operation: () => Promise<T>, operationName: string): Promise<T>;
+    /**
+     * Check if an error is a rate limit error (429)
+     */
+    protected isRateLimitError(error: Error): boolean;
+    /**
+     * Convert errors to TTIError instances with proper classification
+     */
+    protected handleError(error: Error, context?: string): TTIError;
+    /**
+     * Log messages with provider context
+     * Respects global log level setting
+     */
+    protected log(level: 'info' | 'warn' | 'error' | 'debug', message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Type guard to check if a request includes reference images
+ */
+export declare function hasReferenceImages(request: TTIRequest): boolean;
+/**
+ * Check if a region is EU-compliant for GDPR purposes
+ */
+export declare function isEURegion(region: string): boolean;

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

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Base TTI Provider Abstract Class
+ *
+ * All providers must extend this class and implement the ITTIProvider interface.
+ * Provides common functionality for error handling, logging, and validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseTTIProvider = exports.CapabilityNotSupportedError = exports.NetworkError = exports.GenerationFailedError = exports.ProviderUnavailableError = exports.QuotaExceededError = exports.InvalidConfigError = exports.TTIError = void 0;
+exports.setLogLevel = setLogLevel;
+exports.getLogLevel = getLogLevel;
+exports.hasReferenceImages = hasReferenceImages;
+exports.isEURegion = isEURegion;
+const types_1 = require("../../../types");
+// ============================================================
+// ERROR CLASSES
+// ============================================================
+class TTIError extends Error {
+    constructor(provider, code, message, cause) {
+        super(message);
+        this.provider = provider;
+        this.code = code;
+        this.cause = cause;
+        this.name = 'TTIError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TTIError);
+        }
+    }
+    toString() {
+        return `[${this.provider}] ${this.code}: ${this.message}${this.cause ? ` (caused by: ${this.cause.message})` : ''}`;
+    }
+}
+exports.TTIError = TTIError;
+class InvalidConfigError extends TTIError {
+    constructor(provider, message, cause) {
+        super(provider, 'INVALID_CONFIG', message, cause);
+        this.name = 'InvalidConfigError';
+    }
+}
+exports.InvalidConfigError = InvalidConfigError;
+class QuotaExceededError extends TTIError {
+    constructor(provider, message, cause) {
+        super(provider, 'QUOTA_EXCEEDED', message || 'Provider quota or rate limit exceeded', cause);
+        this.name = 'QuotaExceededError';
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+class ProviderUnavailableError extends TTIError {
+    constructor(provider, message, cause) {
+        super(provider, 'PROVIDER_UNAVAILABLE', message || 'Provider service is temporarily unavailable', cause);
+        this.name = 'ProviderUnavailableError';
+    }
+}
+exports.ProviderUnavailableError = ProviderUnavailableError;
+class GenerationFailedError extends TTIError {
+    constructor(provider, message, cause) {
+        super(provider, 'GENERATION_FAILED', message, cause);
+        this.name = 'GenerationFailedError';
+    }
+}
+exports.GenerationFailedError = GenerationFailedError;
+class NetworkError extends TTIError {
+    constructor(provider, message, cause) {
+        super(provider, 'NETWORK_ERROR', message, cause);
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;
+class CapabilityNotSupportedError extends TTIError {
+    constructor(provider, capability, model, cause) {
+        super(provider, 'CAPABILITY_NOT_SUPPORTED', `Model '${model}' does not support '${capability}'`, cause);
+        this.name = 'CapabilityNotSupportedError';
+    }
+}
+exports.CapabilityNotSupportedError = CapabilityNotSupportedError;
+// ============================================================
+// BASE PROVIDER CLASS
+// ============================================================
+/**
+ * Global log level for all providers
+ * Set via TTI_LOG_LEVEL environment variable or setLogLevel()
+ */
+let globalLogLevel = process.env.TTI_LOG_LEVEL || 'info';
+/**
+ * Set the global log level for all TTI providers
+ */
+function setLogLevel(level) {
+    globalLogLevel = level;
+}
+/**
+ * Get the current global log level
+ */
+function getLogLevel() {
+    return globalLogLevel;
+}
+class BaseTTIProvider {
+    constructor(providerName) {
+        this.providerName = providerName;
+    }
+    // ============================================================
+    // IMPLEMENTED METHODS
+    // ============================================================
+    getName() {
+        return this.providerName;
+    }
+    /**
+     * Get model info by ID
+     */
+    getModelInfo(modelId) {
+        return this.listModels().find((m) => m.id === modelId);
+    }
+    /**
+     * Check if a model supports a specific capability
+     */
+    modelSupportsCapability(modelId, capability) {
+        const model = this.getModelInfo(modelId);
+        if (!model)
+            return false;
+        return model.capabilities[capability];
+    }
+    /**
+     * Validate that the request is valid
+     */
+    validateRequest(request) {
+        if (!request.prompt || request.prompt.trim().length === 0) {
+            throw new InvalidConfigError(this.providerName, 'Prompt cannot be empty');
+        }
+        // If reference images are provided, validate them
+        if (request.referenceImages && request.referenceImages.length > 0) {
+            const modelId = request.model || this.getDefaultModel();
+            // Check if model supports character consistency
+            if (!this.modelSupportsCapability(modelId, 'characterConsistency')) {
+                throw new CapabilityNotSupportedError(this.providerName, 'characterConsistency', modelId);
+            }
+            // Validate subject description is provided
+            if (!request.subjectDescription || request.subjectDescription.trim().length === 0) {
+                throw new InvalidConfigError(this.providerName, 'subjectDescription is required when using referenceImages');
+            }
+            // Validate reference images have data
+            for (let i = 0; i < request.referenceImages.length; i++) {
+                const ref = request.referenceImages[i];
+                if (!ref.base64 || ref.base64.trim().length === 0) {
+                    throw new InvalidConfigError(this.providerName, `Reference image at index ${i} has empty base64 data`);
+                }
+            }
+        }
+    }
+    // ============================================================
+    // RETRY LOGIC
+    // ============================================================
+    /**
+     * Resolve retry configuration from request
+     */
+    resolveRetryConfig(request) {
+        const retryOption = request.retry;
+        // Explicit disable
+        if (retryOption === false) {
+            return null;
+        }
+        // Default (undefined) or explicit true: use defaults
+        if (retryOption === undefined || retryOption === true) {
+            return { ...types_1.DEFAULT_RETRY_OPTIONS };
+        }
+        // Custom configuration: merge with defaults
+        return {
+            maxRetries: retryOption.maxRetries ?? types_1.DEFAULT_RETRY_OPTIONS.maxRetries,
+            delayMs: retryOption.delayMs ?? types_1.DEFAULT_RETRY_OPTIONS.delayMs,
+            incrementalBackoff: retryOption.incrementalBackoff ?? types_1.DEFAULT_RETRY_OPTIONS.incrementalBackoff,
+        };
+    }
+    /**
+     * Calculate delay for a specific retry attempt
+     */
+    calculateRetryDelay(attempt, config) {
+        if (config.incrementalBackoff) {
+            // Incremental: 1s, 2s, 3s, ...
+            return config.delayMs * attempt;
+        }
+        // Static: always same delay
+        return config.delayMs;
+    }
+    /**
+     * Sleep for a specified duration
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Execute a generation function with retry logic for rate limits
+     */
+    async executeWithRetry(request, operation, operationName) {
+        const retryConfig = this.resolveRetryConfig(request);
+        // No retry configured
+        if (!retryConfig) {
+            return operation();
+        }
+        let lastError = null;
+        const maxAttempts = 1 + retryConfig.maxRetries; // initial + retries
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error;
+                // Check if this is a rate limit error (429)
+                const isRateLimitError = this.isRateLimitError(error);
+                // Only retry on rate limit errors
+                if (!isRateLimitError) {
+                    throw error;
+                }
+                // Check if we have retries left
+                if (attempt < maxAttempts) {
+                    const delay = this.calculateRetryDelay(attempt, retryConfig);
+                    this.log('warn', `Rate limit hit during ${operationName}. Retry ${attempt}/${retryConfig.maxRetries} in ${delay}ms...`, { attempt, maxRetries: retryConfig.maxRetries, delayMs: delay });
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All retries exhausted
+        throw lastError;
+    }
+    /**
+     * Check if an error is a rate limit error (429)
+     */
+    isRateLimitError(error) {
+        const message = error.message.toLowerCase();
+        return (message.includes('429') ||
+            message.includes('rate limit') ||
+            message.includes('quota exceeded') ||
+            message.includes('too many requests') ||
+            message.includes('resource exhausted'));
+    }
+    /**
+     * Convert errors to TTIError instances with proper classification
+     */
+    handleError(error, context) {
+        if (error instanceof TTIError) {
+            return error;
+        }
+        const errorMessage = error.message.toLowerCase();
+        if (errorMessage.includes('401') || errorMessage.includes('403')) {
+            return new InvalidConfigError(this.providerName, `Authentication failed${context ? `: ${context}` : ''}`, error);
+        }
+        if (errorMessage.includes('429')) {
+            return new QuotaExceededError(this.providerName, `Rate limit exceeded${context ? `: ${context}` : ''}`, error);
+        }
+        if (errorMessage.includes('503') ||
+            errorMessage.includes('504') ||
+            errorMessage.includes('502')) {
+            return new ProviderUnavailableError(this.providerName, `Service temporarily unavailable${context ? `: ${context}` : ''}`, error);
+        }
+        if (errorMessage.includes('timeout') ||
+            errorMessage.includes('econnrefused') ||
+            errorMessage.includes('enotfound')) {
+            return new NetworkError(this.providerName, `Network error${context ? `: ${context}` : ''}`, error);
+        }
+        return new GenerationFailedError(this.providerName, `Generation failed${context ? `: ${context}` : ''}: ${error.message}`, error);
+    }
+    /**
+     * Log messages with provider context
+     * Respects global log level setting
+     */
+    log(level, message, meta) {
+        // Check if we should log this level
+        const currentPriority = types_1.LOG_LEVEL_PRIORITY[level];
+        const minPriority = types_1.LOG_LEVEL_PRIORITY[globalLogLevel];
+        if (currentPriority < minPriority) {
+            return; // Skip logging if below minimum level
+        }
+        const timestamp = new Date().toISOString();
+        const prefix = `[${timestamp}] [${this.providerName.toUpperCase()}] [${level.toUpperCase()}]`;
+        if (meta) {
+            console[level](prefix, message, meta);
+        }
+        else {
+            console[level](prefix, message);
+        }
+    }
+}
+exports.BaseTTIProvider = BaseTTIProvider;
+// ============================================================
+// HELPER FUNCTIONS
+// ============================================================
+/**
+ * Type guard to check if a request includes reference images
+ */
+function hasReferenceImages(request) {
+    return (request.referenceImages !== undefined &&
+        Array.isArray(request.referenceImages) &&
+        request.referenceImages.length > 0);
+}
+/**
+ * Check if a region is EU-compliant for GDPR purposes
+ */
+function isEURegion(region) {
+    const euRegions = [
+        'europe-west1',
+        'europe-west2',
+        'europe-west3',
+        'europe-west4',
+        'europe-west9',
+        'europe-north1',
+        'europe-central2',
+    ];
+    return euRegions.includes(region);
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Eden AI TTI Provider
+ *
+ * Aggregator service that provides access to multiple AI providers
+ * through a unified API.
+ *
+ * @see https://www.edenai.co/
+ * @see https://docs.edenai.co/docs/pricing
+ */
+import { TTIRequest, TTIResponse, ModelInfo } from '../../../types';
+import { BaseTTIProvider } from './base-tti-provider';
+interface EdenAIConfig {
+    apiKey: string;
+    apiUrl?: string;
+}
+export declare class EdenAIProvider extends BaseTTIProvider {
+    private config;
+    private readonly apiUrl;
+    constructor(config?: Partial<EdenAIConfig>);
+    getDisplayName(): string;
+    listModels(): ModelInfo[];
+    getDefaultModel(): string;
+    generate(request: TTIRequest): Promise<TTIResponse>;
+    private executeGeneration;
+    private aspectRatioToSize;
+    private processResponse;
+}
+export {};

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

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Eden AI TTI Provider
+ *
+ * Aggregator service that provides access to multiple AI providers
+ * through a unified API.
+ *
+ * @see https://www.edenai.co/
+ * @see https://docs.edenai.co/docs/pricing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdenAIProvider = void 0;
+const types_1 = require("../../../types");
+const base_tti_provider_1 = require("./base-tti-provider");
+// ============================================================
+// MODEL DEFINITIONS
+// ============================================================
+const EDENAI_MODELS = [
+    {
+        id: 'openai',
+        displayName: 'OpenAI DALL-E',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        pricingUrl: 'https://www.edenai.co/pricing',
+    },
+    {
+        id: 'stabilityai',
+        displayName: 'Stability AI',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        pricingUrl: 'https://www.edenai.co/pricing',
+    },
+    {
+        id: 'replicate',
+        displayName: 'Replicate',
+        capabilities: {
+            textToImage: true,
+            characterConsistency: false,
+            imageEditing: false,
+            maxImagesPerRequest: 4,
+        },
+        pricingUrl: 'https://www.edenai.co/pricing',
+    },
+];
+// ============================================================
+// PROVIDER IMPLEMENTATION
+// ============================================================
+class EdenAIProvider extends base_tti_provider_1.BaseTTIProvider {
+    constructor(config) {
+        super(types_1.TTIProvider.EDENAI);
+        this.config = {
+            apiKey: config?.apiKey || process.env.EDENAI_API_KEY || '',
+            apiUrl: config?.apiUrl,
+        };
+        this.apiUrl =
+            this.config.apiUrl || 'https://api.edenai.run/v2/image/generation';
+        if (!this.config.apiKey) {
+            throw new base_tti_provider_1.InvalidConfigError(this.providerName, 'EdenAI API key is required (EDENAI_API_KEY)');
+        }
+        this.log('info', 'Eden AI Provider initialized');
+    }
+    // ============================================================
+    // ITTIProvider IMPLEMENTATION
+    // ============================================================
+    getDisplayName() {
+        return 'Eden AI';
+    }
+    listModels() {
+        return EDENAI_MODELS;
+    }
+    getDefaultModel() {
+        return 'openai';
+    }
+    async generate(request) {
+        this.validateRequest(request);
+        return this.executeWithRetry(request, () => this.executeGeneration(request), 'EdenAI API call');
+    }
+    async executeGeneration(request) {
+        const startTime = Date.now();
+        const modelId = request.model || this.getDefaultModel();
+        const body = {
+            providers: modelId,
+            text: request.prompt,
+            resolution: request.aspectRatio ? this.aspectRatioToSize(request.aspectRatio) : '1024x1024',
+            num_images: request.n || 1,
+        };
+        this.log('debug', 'Generating image with EdenAI', {
+            provider: modelId,
+            size: body.resolution,
+        });
+        try {
+            const response = await fetch(this.apiUrl, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`EdenAI API error (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            this.log('debug', 'Raw EdenAI response', { data: JSON.stringify(data) });
+            const duration = Date.now() - startTime;
+            return this.processResponse(data, modelId, duration);
+        }
+        catch (error) {
+            throw this.handleError(error, 'during EdenAI API call');
+        }
+    }
+    // ============================================================
+    // PRIVATE METHODS
+    // ============================================================
+    aspectRatioToSize(aspectRatio) {
+        const mapping = {
+            '1:1': '1024x1024',
+            '16:9': '1792x1024',
+            '9:16': '1024x1792',
+            '4:3': '1024x768',
+            '3:4': '768x1024',
+        };
+        return mapping[aspectRatio] || '1024x1024';
+    }
+    processResponse(data, provider, duration) {
+        const responseKeys = Object.keys(data);
+        const matchedKey = responseKeys.find((key) => key.startsWith(provider));
+        const providerData = matchedKey ? data[matchedKey] : undefined;
+        if (!providerData) {
+            this.log('error', `Provider data not found for ${provider}. Available keys: ${responseKeys.join(', ')}`);
+            throw new base_tti_provider_1.GenerationFailedError(this.providerName, `No data returned for provider: ${provider}`);
+        }
+        if (providerData.status === 'fail' || providerData.error) {
+            throw new base_tti_provider_1.GenerationFailedError(this.providerName, providerData.error || 'Unknown error from provider');
+        }
+        const items = providerData.items || [];
+        const images = [];
+        for (const item of items) {
+            if (item.image) {
+                images.push({ base64: item.image, contentType: 'image/png' });
+            }
+            else if (item.image_resource_url) {
+                images.push({ url: item.image_resource_url });
+            }
+        }
+        if (images.length === 0) {
+            throw new base_tti_provider_1.GenerationFailedError(this.providerName, 'No images returned in response');
+        }
+        const usage = {
+            imagesGenerated: images.length,
+            modelId: provider,
+        };
+        return {
+            images,
+            metadata: {
+                provider: this.providerName,
+                model: provider,
+                duration,
+            },
+            usage,
+            // Eden AI returns actual cost from provider!
+            billing: providerData.cost
+                ? {
+                    cost: providerData.cost,
+                    currency: 'USD',
+                    source: 'provider',
+                }
+                : undefined,
+        };
+    }
+}
+exports.EdenAIProvider = EdenAIProvider;

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

@@ -0,0 +1,60 @@
+/**
+ * Google Cloud TTI Provider
+ *
+ * Unified provider for Google Cloud's image generation services:
+ * - Imagen 3 (imagegeneration@006) - High quality text-to-image
+ * - Gemini 2.5 Flash Image - Text-to-image with character consistency
+ *
+ * All requests go through Google Cloud (Vertex AI) with proper DPA.
+ * EU-compliant when using EU regions.
+ *
+ * @see https://cloud.google.com/vertex-ai/generative-ai/pricing
+ * @see https://cloud.google.com/terms/data-processing-addendum
+ */
+import { TTIRequest, TTIResponse, ModelInfo, GoogleCloudRegion } from '../../../types';
+import { BaseTTIProvider } from './base-tti-provider';
+interface GoogleCloudConfig {
+    /** Google Cloud Project ID */
+    projectId: string;
+    /** Default region for requests */
+    region: GoogleCloudRegion;
+    /** Path to service account JSON file */
+    keyFilename?: string;
+    /** Service account credentials object (alternative to keyFilename) */
+    credentials?: {
+        client_email: string;
+        private_key: string;
+        project_id?: string;
+    };
+}
+export declare class GoogleCloudTTIProvider extends BaseTTIProvider {
+    private config;
+    private lastUsedRegion;
+    private aiplatformClient;
+    private genaiClient;
+    constructor(config?: Partial<GoogleCloudConfig>);
+    getDisplayName(): string;
+    listModels(): ModelInfo[];
+    getDefaultModel(): string;
+    generate(request: TTIRequest): Promise<TTIResponse>;
+    /**
+     * Get the configured region
+     */
+    getRegion(): GoogleCloudRegion;
+    /**
+     * Check if the configured region is hosted in the EU
+     */
+    isEURegion(): boolean;
+    /**
+     * Get the effective region for a model, considering availability
+     */
+    private getEffectiveRegion;
+    private generateWithImagen;
+    private getAiplatformClient;
+    private processImagenResponse;
+    private generateWithGemini;
+    private getGenaiClient;
+    private buildCharacterConsistencyPrompt;
+    private processGeminiResponse;
+}
+export {};