@loonylabs/tti-middleware 1.0.0

package/dist/middleware/services/tti/tti.service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * TTI Service
+ *
+ * Main entry point for Text-to-Image generation.
+ * Manages providers and routes requests to the appropriate provider.
+ */
+import { BaseTTIProvider } from './providers';
+import { TTIRequest, TTIResponse, TTIProvider, ModelInfo } from '../../types';
+export declare class TTIService {
+    private providers;
+    private defaultProvider;
+    constructor();
+    /**
+     * Parse a string to TTIProvider enum
+     */
+    private parseProvider;
+    /**
+     * Register a TTI provider
+     */
+    registerProvider(provider: BaseTTIProvider): void;
+    /**
+     * Get a registered provider
+     */
+    getProvider(name: TTIProvider): BaseTTIProvider | undefined;
+    /**
+     * Get all registered providers
+     */
+    getAvailableProviders(): TTIProvider[];
+    /**
+     * Check if a provider is available
+     */
+    isProviderAvailable(provider: TTIProvider): boolean;
+    /**
+     * Get the default provider
+     */
+    getDefaultProvider(): TTIProvider;
+    /**
+     * Set the default provider
+     */
+    setDefaultProvider(provider: TTIProvider): void;
+    /**
+     * List all models available across all registered providers
+     */
+    listAllModels(): Array<{
+        provider: TTIProvider;
+        models: ModelInfo[];
+    }>;
+    /**
+     * Find providers that support a specific capability
+     */
+    findProvidersWithCapability(capability: keyof ModelInfo['capabilities']): Array<{
+        provider: TTIProvider;
+        models: ModelInfo[];
+    }>;
+    /**
+     * Generate an image
+     *
+     * @param request The generation request
+     * @param provider Optional provider to use (defaults to default provider)
+     */
+    generate(request: TTIRequest, provider?: TTIProvider): Promise<TTIResponse>;
+    /**
+     * @deprecated Use generate() instead
+     */
+    generateImage(request: TTIRequest, provider?: TTIProvider | string): Promise<TTIResponse>;
+    /**
+     * @deprecated Use generate() with referenceImages in request instead
+     */
+    generateWithReference(request: TTIRequest, provider?: TTIProvider | string): Promise<TTIResponse>;
+}

package/dist/middleware/services/tti/tti.service.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * TTI Service
+ *
+ * Main entry point for Text-to-Image generation.
+ * Manages providers and routes requests to the appropriate provider.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTIService = void 0;
+const providers_1 = require("./providers");
+const types_1 = require("../../types");
+class TTIService {
+    constructor() {
+        this.providers = new Map();
+        this.defaultProvider = types_1.TTIProvider.GOOGLE_CLOUD;
+        // Check for default provider from environment
+        const envDefault = process.env.TTI_DEFAULT_PROVIDER?.toLowerCase();
+        if (envDefault) {
+            const parsed = this.parseProvider(envDefault);
+            if (parsed) {
+                this.defaultProvider = parsed;
+            }
+        }
+    }
+    /**
+     * Parse a string to TTIProvider enum
+     */
+    parseProvider(value) {
+        const normalized = value.toLowerCase().trim();
+        const providerMap = {
+            // Google Cloud
+            'google-cloud': types_1.TTIProvider.GOOGLE_CLOUD,
+            'google_cloud': types_1.TTIProvider.GOOGLE_CLOUD,
+            googlecloud: types_1.TTIProvider.GOOGLE_CLOUD,
+            // Legacy names (backwards compatibility)
+            vertex_ai: types_1.TTIProvider.GOOGLE_CLOUD,
+            vertexai: types_1.TTIProvider.GOOGLE_CLOUD,
+            vertex: types_1.TTIProvider.GOOGLE_CLOUD,
+            gemini: types_1.TTIProvider.GOOGLE_CLOUD,
+            // Eden AI
+            edenai: types_1.TTIProvider.EDENAI,
+            eden_ai: types_1.TTIProvider.EDENAI,
+            // IONOS
+            ionos: types_1.TTIProvider.IONOS,
+        };
+        return providerMap[normalized] || null;
+    }
+    /**
+     * Register a TTI provider
+     */
+    registerProvider(provider) {
+        this.providers.set(provider.getName(), provider);
+        console.log(`[TTIService] Registered provider: ${provider.getDisplayName()}`);
+    }
+    /**
+     * Get a registered provider
+     */
+    getProvider(name) {
+        return this.providers.get(name);
+    }
+    /**
+     * Get all registered providers
+     */
+    getAvailableProviders() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+     * Check if a provider is available
+     */
+    isProviderAvailable(provider) {
+        return this.providers.has(provider);
+    }
+    /**
+     * Get the default provider
+     */
+    getDefaultProvider() {
+        return this.defaultProvider;
+    }
+    /**
+     * Set the default provider
+     */
+    setDefaultProvider(provider) {
+        if (!this.providers.has(provider)) {
+            console.warn(`[TTIService] Provider ${provider} is not registered. Setting as default anyway.`);
+        }
+        this.defaultProvider = provider;
+    }
+    /**
+     * List all models available across all registered providers
+     */
+    listAllModels() {
+        const result = [];
+        for (const [name, provider] of this.providers) {
+            result.push({
+                provider: name,
+                models: provider.listModels(),
+            });
+        }
+        return result;
+    }
+    /**
+     * Find providers that support a specific capability
+     */
+    findProvidersWithCapability(capability) {
+        const result = [];
+        for (const [name, provider] of this.providers) {
+            const supportingModels = provider
+                .listModels()
+                .filter((m) => m.capabilities[capability]);
+            if (supportingModels.length > 0) {
+                result.push({
+                    provider: name,
+                    models: supportingModels,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Generate an image
+     *
+     * @param request The generation request
+     * @param provider Optional provider to use (defaults to default provider)
+     */
+    async generate(request, provider) {
+        const providerKey = provider || this.defaultProvider;
+        const providerInstance = this.providers.get(providerKey);
+        if (!providerInstance) {
+            // Try to find any registered provider as fallback
+            if (this.providers.size > 0) {
+                const entries = Array.from(this.providers.entries());
+                const [fallbackKey, fallbackProvider] = entries[0];
+                console.warn(`[TTIService] Provider ${providerKey} not found. Using fallback: ${fallbackKey}`);
+                return fallbackProvider.generate(request);
+            }
+            throw new providers_1.InvalidConfigError('TTIService', `Provider '${providerKey}' not found and no other providers registered.`);
+        }
+        return providerInstance.generate(request);
+    }
+    // ============================================================
+    // LEGACY METHODS (deprecated, for backwards compatibility)
+    // ============================================================
+    /**
+     * @deprecated Use generate() instead
+     */
+    async generateImage(request, provider) {
+        const providerKey = typeof provider === 'string'
+            ? this.parseProvider(provider) || this.defaultProvider
+            : provider || this.defaultProvider;
+        return this.generate(request, providerKey);
+    }
+    /**
+     * @deprecated Use generate() with referenceImages in request instead
+     */
+    async generateWithReference(request, provider) {
+        const providerKey = typeof provider === 'string'
+            ? this.parseProvider(provider) || this.defaultProvider
+            : provider || this.defaultProvider;
+        return this.generate(request, providerKey);
+    }
+}
+exports.TTIService = TTIService;

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

@@ -0,0 +1,196 @@
+/**
+ * Available TTI Providers
+ * Each provider represents a single backend/contract partner with one DPA
+ */
+export declare enum TTIProvider {
+    /** Google Cloud Platform (Vertex AI) - includes Imagen and Gemini models. RECOMMENDED for EU/GDPR. */
+    GOOGLE_CLOUD = "google-cloud",
+    /** Eden AI - aggregator with multiple underlying models. EXPERIMENTAL - limited testing. */
+    EDENAI = "edenai",
+    /** IONOS Cloud. EXPERIMENTAL - limited testing. */
+    IONOS = "ionos"
+}
+/**
+ * Log levels for provider logging
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Log level priority (higher = more severe)
+ */
+export declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+/**
+ * Capabilities of a specific model
+ */
+export interface TTICapabilities {
+    /** Basic text-to-image generation */
+    textToImage: boolean;
+    /** Character consistency via reference images */
+    characterConsistency: boolean;
+    /** Image editing (inpainting, outpainting) - future */
+    imageEditing: boolean;
+    /** Maximum images per request */
+    maxImagesPerRequest: number;
+}
+/**
+ * Information about a specific model within a provider
+ */
+export interface ModelInfo {
+    /** Internal model ID used in API calls */
+    id: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** What the model can do */
+    capabilities: TTICapabilities;
+    /** Available regions (for providers with regional endpoints) */
+    availableRegions?: string[];
+    /** Link to official pricing page */
+    pricingUrl?: string;
+}
+/**
+ * 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';
+/**
+ * Reference image for character consistency
+ */
+export interface TTIReferenceImage {
+    /** Base64-encoded image data */
+    base64: string;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
+    mimeType?: string;
+}
+/**
+ * Unified TTI generation request
+ * Works for both simple text-to-image and character consistency
+ */
+export interface TTIRequest {
+    /** The text prompt describing what to generate */
+    prompt: string;
+    /** Model ID to use (provider-specific, e.g., 'imagen-3', 'gemini-flash-image') */
+    model?: string;
+    /** Number of images to generate (default: 1) */
+    n?: number;
+    /** Aspect ratio (e.g., '1:1', '16:9', '4:3') */
+    aspectRatio?: string;
+    /**
+     * Reference images for character consistency
+     * If provided, the model will try to maintain visual consistency
+     */
+    referenceImages?: TTIReferenceImage[];
+    /**
+     * Description of the subject in reference images
+     * Required when using referenceImages (e.g., "cute cartoon bear with red hat")
+     */
+    subjectDescription?: string;
+    /** Additional provider-specific options */
+    providerOptions?: Record<string, unknown>;
+    /**
+     * Retry configuration for rate limit errors (429)
+     * - true: use default retry (2 retries, 1s delay)
+     * - false: disable retry
+     * - RetryOptions: custom configuration
+     * Default: true (retry enabled with defaults)
+     */
+    retry?: boolean | RetryOptions;
+}
+/**
+ * Generated image
+ */
+export interface TTIImage {
+    /** URL to the generated image (if available) */
+    url?: string;
+    /** Base64-encoded image data */
+    base64?: string;
+    /** MIME type (e.g., 'image/png', 'image/jpeg') */
+    contentType?: string;
+}
+/**
+ * Usage metrics for a generation request
+ */
+export interface TTIUsage {
+    /** Number of images generated */
+    imagesGenerated: number;
+    /** Size of generated images */
+    imageSize?: string;
+    /** Model used for generation */
+    modelId: string;
+    /** Input tokens (for token-based models) */
+    inputTokens?: number;
+    /** Output tokens (for token-based models) */
+    outputTokens?: number;
+}
+/**
+ * Billing information (only if provider returns it)
+ */
+export interface TTIBilling {
+    /** Cost of the request */
+    cost: number;
+    /** Currency */
+    currency: string;
+    /** Source of the cost information */
+    source: 'provider' | 'estimated';
+}
+/**
+ * Response from a TTI generation request
+ */
+export interface TTIResponse {
+    /** Generated images */
+    images: TTIImage[];
+    /** Request metadata */
+    metadata: {
+        /** Provider that handled the request */
+        provider: string;
+        /** Model used */
+        model: string;
+        /** Region where request was processed (if applicable) */
+        region?: string;
+        /** Request duration in milliseconds */
+        duration: number;
+    };
+    /** Usage metrics */
+    usage: TTIUsage;
+    /** Billing info (only if provider returns actual costs) */
+    billing?: TTIBilling;
+}
+export type TTIErrorCode = 'INVALID_CONFIG' | 'QUOTA_EXCEEDED' | 'PROVIDER_UNAVAILABLE' | 'GENERATION_FAILED' | 'NETWORK_ERROR' | 'UNAUTHORIZED' | 'CAPABILITY_NOT_SUPPORTED';
+/**
+ * Configuration for retry behavior on rate limits (429 errors)
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts (default: 2)
+     * Total attempts = 1 (initial) + maxRetries
+     */
+    maxRetries?: number;
+    /**
+     * Base delay between retries in milliseconds (default: 1000)
+     */
+    delayMs?: number;
+    /**
+     * Use incremental backoff: delay increases by delayMs each retry
+     * false: always wait delayMs (e.g., 1s, 1s, 1s)
+     * true: wait delayMs * attempt (e.g., 1s, 2s, 3s)
+     * Default: false
+     */
+    incrementalBackoff?: boolean;
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_OPTIONS: Required<RetryOptions>;
+/**
+ * Interface that all TTI providers must implement
+ */
+export interface ITTIProvider {
+    /** Get the provider identifier */
+    getName(): TTIProvider;
+    /** Get human-readable display name */
+    getDisplayName(): string;
+    /** List all available models */
+    listModels(): ModelInfo[];
+    /** Get the default model ID */
+    getDefaultModel(): string;
+    /** Generate images from a request */
+    generate(request: TTIRequest): Promise<TTIResponse>;
+}

package/dist/middleware/types/index.js

@@ -0,0 +1,37 @@
+"use strict";
+// ============================================================
+// PROVIDER IDENTIFICATION
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_OPTIONS = exports.LOG_LEVEL_PRIORITY = exports.TTIProvider = void 0;
+/**
+ * Available TTI Providers
+ * Each provider represents a single backend/contract partner with one DPA
+ */
+var TTIProvider;
+(function (TTIProvider) {
+    /** Google Cloud Platform (Vertex AI) - includes Imagen and Gemini models. RECOMMENDED for EU/GDPR. */
+    TTIProvider["GOOGLE_CLOUD"] = "google-cloud";
+    /** Eden AI - aggregator with multiple underlying models. EXPERIMENTAL - limited testing. */
+    TTIProvider["EDENAI"] = "edenai";
+    /** IONOS Cloud. EXPERIMENTAL - limited testing. */
+    TTIProvider["IONOS"] = "ionos";
+})(TTIProvider || (exports.TTIProvider = TTIProvider = {}));
+/**
+ * Log level priority (higher = more severe)
+ */
+exports.LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+/**
+ * Default retry configuration
+ */
+exports.DEFAULT_RETRY_OPTIONS = {
+    maxRetries: 2,
+    delayMs: 1000,
+    incrementalBackoff: false,
+};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@loonylabs/tti-middleware",
+  "version": "1.0.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",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run test:unit",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:unit:watch": "jest --testPathPattern=tests/unit --watch",
+    "test:unit:coverage": "jest --testPathPattern=tests/unit --coverage",
+    "test:integration": "cross-env TTI_INTEGRATION_TESTS=true jest --testPathPattern=tests/integration",
+    "test:ci": "jest --runInBand --ci --coverage --testPathPattern=tests/unit",
+    "test:live": "TTI_INTEGRATION_TESTS=true jest tests/integration/*.integration.test.ts --testTimeout=120000",
+    "test:manual": "ts-node scripts/manual-test-edenai.ts",
+    "test:manual:google-cloud": "ts-node scripts/manual-test-google-cloud.ts",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "keywords": [
+    "tti",
+    "text-to-image",
+    "image-generation",
+    "ai",
+    "vertex-ai",
+    "google-cloud",
+    "gemini",
+    "imagen",
+    "middleware",
+    "provider-agnostic",
+    "typescript",
+    "gdpr",
+    "dsgvo",
+    "character-consistency"
+  ],
+  "author": "loonylabs-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/loonylabs-dev/tti-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loonylabs-dev/tti-middleware/issues"
+  },
+  "homepage": "https://github.com/loonylabs-dev/tti-middleware#readme",
+  "peerDependencies": {
+    "@google-cloud/aiplatform": ">=3.0.0",
+    "@google/genai": ">=0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/aiplatform": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google-cloud/aiplatform": "^3.29.0",
+    "@google/genai": "^0.14.0",
+    "@types/jest": "^29.5.8",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "cross-env": "^10.1.0",
+    "dotenv": "^17.2.3",
+    "eslint": "^8.54.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}