@loonylabs/tti-middleware 1.0.0 → 1.1.0

package/README.md

@@ -48,6 +48,7 @@
 - **Retry Logic**: Automatic retry for rate limits (429) with configurable backoff
 - **TypeScript First**: Full type safety with comprehensive interfaces
 - **Logging Control**: Configurable log levels via environment or API
+- **Debug Logging**: Markdown file logging for debugging prompts and responses
 - **Error Handling**: Typed error classes for precise error handling
 
 ## Quick Start
@@ -103,7 +104,7 @@ const character = await service.generate({
   model: 'gemini-flash-image', // Only this model supports character consistency!
 });
 
-// 2. Generate new scenes with the same character
+// 2. Generate new scenes with the same character (Structured Mode)
 const scene = await service.generate({
   prompt: 'dancing happily in the rain, jumping in puddles',
   model: 'gemini-flash-image',
@@ -113,6 +114,17 @@ const scene = await service.generate({
   }],
   subjectDescription: 'cute cartoon bear with red hat and blue scarf',
 });
+
+// 3. Or use Index-Based Mode for multiple characters
+const multiCharScene = await service.generate({
+  prompt: 'The FIRST reference image character meets the SECOND reference image character',
+  model: 'gemini-flash-image',
+  referenceImages: [
+    { base64: character1.images[0].base64!, mimeType: 'image/png' },
+    { base64: character2.images[0].base64!, mimeType: 'image/png' },
+  ],
+  // subjectDescription omitted = Index-Based Mode
+});
 ```
 
 **Important:** Character consistency is only supported by `gemini-flash-image` model!
@@ -225,7 +237,11 @@ IONOS_API_URL=https://api.ionos.cloud/ai/v1
 
 ## Character Consistency
 
-Generate consistent characters across multiple images - perfect for children's book illustrations:
+Generate consistent characters across multiple images - perfect for children's book illustrations.
+
+### Mode 1: Structured Mode (Single Character)
+
+Best for scenes with a single consistent character:
 
 ```typescript
 // Step 1: Create a character
@@ -242,15 +258,47 @@ for (const scene of scenes) {
     prompt: scene,
     model: 'gemini-flash-image',
     referenceImages: [{ base64: bear.images[0].base64!, mimeType: 'image/png' }],
-    subjectDescription: 'cute cartoon bear with red hat',
+    subjectDescription: 'cute cartoon bear with red hat',  // Required in structured mode
   });
   // Save result...
 }
 ```
 
-**Requirements:**
-- Model must be `gemini-flash-image`
-- `subjectDescription` is required when using `referenceImages`
+### Mode 2: Index-Based Mode (Multiple Characters)
+
+Best for scenes with multiple distinct characters. Reference images directly in your prompt by their position:
+
+```typescript
+// Load two different character references
+const cowboy1 = await loadImage('cowboy1.png');
+const cowboy2 = await loadImage('cowboy2.png');
+
+// Reference each image by index in the prompt
+const duelScene = await service.generate({
+  prompt: `Generate a cinematic wide shot of a western duel.
+    - The character on the LEFT should look exactly like the person in the FIRST reference image.
+    - The character on the RIGHT should look exactly like the person in the SECOND reference image.
+    They are standing in a dusty street at high noon.`,
+  model: 'gemini-flash-image',
+  referenceImages: [
+    { base64: cowboy1, mimeType: 'image/png' },
+    { base64: cowboy2, mimeType: 'image/png' },
+  ],
+  // subjectDescription intentionally omitted for index-based mode
+  aspectRatio: '16:9',
+});
+```
+
+**Reference keywords:** Use "FIRST reference image", "SECOND reference image" or "Image 1", "Image 2" etc.
+
+### Requirements
+
+| Mode | `subjectDescription` | Use Case |
+|------|---------------------|----------|
+| **Structured** | Required | Single character across scenes |
+| **Index-Based** | Omitted | Multiple characters in one scene |
+
+- Model must be `gemini-flash-image` (only model supporting character consistency)
 
 ## GDPR / Compliance
 
@@ -405,6 +453,42 @@ Available levels: `debug`, `info`, `warn`, `error`, `silent`
 
 </details>
 
+<details>
+<summary><strong>Debug Logging (Markdown Files)</strong></summary>
+
+Log all TTI requests and responses to markdown files for debugging:
+
+```typescript
+import { TTIDebugger } from '@loonylabs/tti-middleware';
+
+// Enable via environment variable
+// DEBUG_TTI_REQUESTS=true
+
+// Or programmatically
+TTIDebugger.setEnabled(true);
+TTIDebugger.setLogsDir('./logs/tti/requests');
+
+// Configure all options at once
+TTIDebugger.configure({
+  enabled: true,
+  logsDir: './logs/tti/requests',
+  consoleLog: true,      // Also log to console
+  includeBase64: false,  // Exclude base64 data (default)
+});
+```
+
+**Log file contents:**
+- Provider, model, and region
+- Full prompt text
+- Subject description (for character consistency)
+- Reference image metadata
+- Response data (duration, image count)
+- Errors with full details
+
+**Use case:** Debug why character consistency isn't working by inspecting exactly what prompt and `subjectDescription` are being sent to the API.
+
+</details>
+
 <details>
 <summary><strong>Error Handling</strong></summary>
 

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

@@ -1,2 +1,3 @@
 export * from './tti.service';
 export * from './providers';
+export * from './utils';

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

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./tti.service"), exports);
 __exportStar(require("./providers"), exports);
+__exportStar(require("./utils"), exports);

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

@@ -133,9 +133,14 @@ class BaseTTIProvider {
                 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');
-            }
+            // RELAXED: We now allow missing subjectDescription to support raw multimodal prompting
+            // where the user references images directly in the prompt (e.g., "Image 1 is X...").
+            // 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];

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

@@ -49,6 +49,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GoogleCloudTTIProvider = void 0;
 const types_1 = require("../../../types");
 const base_tti_provider_1 = require("./base-tti-provider");
+const debug_tti_utils_1 = require("../utils/debug-tti.utils");
 // ============================================================
 // MODEL DEFINITIONS
 // ============================================================
@@ -157,19 +158,44 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         }
         // Validate region availability
         const effectiveRegion = this.getEffectiveRegion(modelId);
+        // Create debug info for logging
+        let debugInfo = null;
+        if (debug_tti_utils_1.TTIDebugger.isEnabled) {
+            debugInfo = debug_tti_utils_1.TTIDebugger.createDebugInfo(request, this.providerName, modelId, { region: effectiveRegion });
+            await debug_tti_utils_1.TTIDebugger.logRequest(debugInfo);
+        }
         this.log('debug', 'Generating image', {
             model: modelId,
             region: effectiveRegion,
             hasReferenceImages: (0, base_tti_provider_1.hasReferenceImages)(request),
         });
-        // Route to appropriate implementation with retry support
-        switch (modelId) {
-            case 'imagen-3':
-                return this.executeWithRetry(request, () => this.generateWithImagen(request, effectiveRegion), 'Imagen API call');
-            case 'gemini-flash-image':
-                return this.executeWithRetry(request, () => this.generateWithGemini(request, effectiveRegion), 'Gemini API call');
-            default:
-                throw new base_tti_provider_1.InvalidConfigError(this.providerName, `Unknown model: ${modelId}`);
+        try {
+            // Route to appropriate implementation with retry support
+            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}`);
+            }
+            // Log successful response
+            if (debugInfo) {
+                debugInfo = debug_tti_utils_1.TTIDebugger.updateWithResponse(debugInfo, response);
+                await debug_tti_utils_1.TTIDebugger.logResponse(debugInfo);
+            }
+            return response;
+        }
+        catch (error) {
+            // Log error
+            if (debugInfo) {
+                debugInfo = debug_tti_utils_1.TTIDebugger.updateWithError(debugInfo, error);
+                await debug_tti_utils_1.TTIDebugger.logError(debugInfo);
+            }
+            throw error;
         }
     }
     // ============================================================
@@ -347,9 +373,16 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                         },
                     });
                 }
-                // Build character consistency prompt
-                const fullPrompt = this.buildCharacterConsistencyPrompt(request.prompt, request.subjectDescription, request.referenceImages.length);
-                parts.push({ text: fullPrompt });
+                // Build character consistency prompt if subject description is provided
+                if (request.subjectDescription) {
+                    const fullPrompt = this.buildCharacterConsistencyPrompt(request.prompt, request.subjectDescription, request.referenceImages.length);
+                    parts.push({ text: fullPrompt });
+                }
+                else {
+                    // No subject description - treat as raw multimodal prompt
+                    // This allows "image 1", "image 2" style prompting
+                    parts.push({ text: request.prompt });
+                }
             }
             else {
                 parts.push({ text: request.prompt });

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

@@ -0,0 +1,150 @@
+/**
+ * TTI Debugger Utility
+ *
+ * Provides markdown-based logging for TTI requests, similar to LLM middleware.
+ * Logs prompts, subject descriptions, reference image metadata, and responses.
+ *
+ * Enable via:
+ * - Environment variable: DEBUG_TTI_REQUESTS=true
+ * - Or programmatically: TTIDebugger.setEnabled(true)
+ *
+ * Configure log directory:
+ * - Environment variable: TTI_DEBUG_LOG_DIR=/path/to/logs
+ * - Or programmatically: TTIDebugger.setLogsDir('/path/to/logs')
+ * - Default: process.cwd()/logs/tti/requests/
+ */
+import { TTIRequest, TTIResponse } from '../../../types';
+/**
+ * Debug information for a TTI request
+ */
+export interface TTIDebugInfo {
+    requestTimestamp: Date;
+    responseTimestamp?: Date;
+    provider: string;
+    model: string;
+    region?: string;
+    prompt: string;
+    subjectDescription?: string;
+    referenceImageCount: number;
+    referenceImageMimeTypes?: string[];
+    aspectRatio?: string;
+    providerOptions?: Record<string, unknown>;
+    useCase?: string;
+    sessionId?: string;
+    bookId?: string;
+    characterId?: string;
+    sectionId?: string;
+    response?: {
+        imageCount: number;
+        imageMimeTypes: string[];
+        duration: number;
+    };
+    rawRequest?: TTIRequest;
+    rawResponse?: TTIResponse;
+    error?: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+}
+/**
+ * Configuration options for TTIDebugger
+ */
+export interface TTIDebuggerConfig {
+    /** Enable/disable logging (default: from DEBUG_TTI_REQUESTS env) */
+    enabled?: boolean;
+    /** Directory for log files (default: process.cwd()/logs/tti/requests) */
+    logsDir?: string;
+    /** Include raw base64 image data in logs (default: false - too large) */
+    includeBase64?: boolean;
+    /** Log to console as well (default: false) */
+    consoleLog?: boolean;
+}
+/**
+ * Static debugger class for TTI request/response logging
+ */
+export declare class TTIDebugger {
+    private static _enabled;
+    private static _logsDir;
+    private static _includeBase64;
+    private static _consoleLog;
+    /**
+     * Check if debugging is enabled
+     */
+    static get isEnabled(): boolean;
+    /**
+     * Enable or disable debugging
+     */
+    static setEnabled(enabled: boolean): void;
+    /**
+     * Get the current logs directory
+     */
+    static getLogsDir(): string;
+    /**
+     * Set the logs directory
+     */
+    static setLogsDir(dir: string): void;
+    /**
+     * Configure the debugger
+     */
+    static configure(config: TTIDebuggerConfig): void;
+    /**
+     * Log a TTI request (call before generation)
+     */
+    static logRequest(debugInfo: TTIDebugInfo): Promise<void>;
+    /**
+     * Log a TTI response (call after generation)
+     */
+    static logResponse(debugInfo: TTIDebugInfo): Promise<void>;
+    /**
+     * Log an error
+     */
+    static logError(debugInfo: TTIDebugInfo): Promise<void>;
+    /**
+     * Save debug info to a markdown file
+     */
+    static saveToMarkdown(debugInfo: TTIDebugInfo): Promise<string>;
+    /**
+     * Generate a filename for the log file
+     */
+    private static generateFilename;
+    /**
+     * Format debug info as markdown
+     */
+    private static formatMarkdown;
+    /**
+     * Sanitize request by removing/truncating base64 data
+     */
+    private static sanitizeRequest;
+    /**
+     * Sanitize response by removing/truncating base64 data
+     */
+    private static sanitizeResponse;
+    /**
+     * Ensure the logs directory exists
+     */
+    private static ensureLogsDirectory;
+    /**
+     * Create debug info from a request (helper for providers)
+     */
+    static createDebugInfo(request: TTIRequest, provider: string, model: string, options?: {
+        region?: string;
+        useCase?: string;
+        sessionId?: string;
+        bookId?: string;
+        characterId?: string;
+        sectionId?: string;
+    }): TTIDebugInfo;
+    /**
+     * Update debug info with response data (helper for providers)
+     */
+    static updateWithResponse(debugInfo: TTIDebugInfo, response: TTIResponse): TTIDebugInfo;
+    /**
+     * Update debug info with error data (helper for providers)
+     */
+    static updateWithError(debugInfo: TTIDebugInfo, error: Error & {
+        code?: string;
+        cause?: unknown;
+    }): TTIDebugInfo;
+}
+export default TTIDebugger;

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

@@ -0,0 +1,418 @@
+"use strict";
+/**
+ * TTI Debugger Utility
+ *
+ * Provides markdown-based logging for TTI requests, similar to LLM middleware.
+ * Logs prompts, subject descriptions, reference image metadata, and responses.
+ *
+ * Enable via:
+ * - Environment variable: DEBUG_TTI_REQUESTS=true
+ * - Or programmatically: TTIDebugger.setEnabled(true)
+ *
+ * Configure log directory:
+ * - Environment variable: TTI_DEBUG_LOG_DIR=/path/to/logs
+ * - Or programmatically: TTIDebugger.setLogsDir('/path/to/logs')
+ * - Default: process.cwd()/logs/tti/requests/
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTIDebugger = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ============================================================
+// DEBUGGER CLASS
+// ============================================================
+/**
+ * Static debugger class for TTI request/response logging
+ */
+class TTIDebugger {
+    // ============================================================
+    // CONFIGURATION
+    // ============================================================
+    /**
+     * Check if debugging is enabled
+     */
+    static get isEnabled() {
+        return this._enabled;
+    }
+    /**
+     * Enable or disable debugging
+     */
+    static setEnabled(enabled) {
+        this._enabled = enabled;
+    }
+    /**
+     * Get the current logs directory
+     */
+    static getLogsDir() {
+        return this._logsDir;
+    }
+    /**
+     * Set the logs directory
+     */
+    static setLogsDir(dir) {
+        this._logsDir = dir;
+    }
+    /**
+     * Configure the debugger
+     */
+    static configure(config) {
+        if (config.enabled !== undefined) {
+            this._enabled = config.enabled;
+        }
+        if (config.logsDir !== undefined) {
+            this._logsDir = config.logsDir;
+        }
+        if (config.includeBase64 !== undefined) {
+            this._includeBase64 = config.includeBase64;
+        }
+        if (config.consoleLog !== undefined) {
+            this._consoleLog = config.consoleLog;
+        }
+    }
+    // ============================================================
+    // LOGGING METHODS
+    // ============================================================
+    /**
+     * Log a TTI request (call before generation)
+     */
+    static async logRequest(debugInfo) {
+        if (!this._enabled)
+            return;
+        if (this._consoleLog) {
+            console.log('[TTI Debug] Request:', {
+                provider: debugInfo.provider,
+                model: debugInfo.model,
+                useCase: debugInfo.useCase,
+                prompt: debugInfo.prompt.substring(0, 100) + '...',
+                subjectDescription: debugInfo.subjectDescription,
+                referenceImageCount: debugInfo.referenceImageCount,
+            });
+        }
+    }
+    /**
+     * Log a TTI response (call after generation)
+     */
+    static async logResponse(debugInfo) {
+        if (!this._enabled)
+            return;
+        try {
+            await this.saveToMarkdown(debugInfo);
+            if (this._consoleLog) {
+                console.log('[TTI Debug] Response saved:', {
+                    provider: debugInfo.provider,
+                    model: debugInfo.model,
+                    duration: debugInfo.response?.duration,
+                    imageCount: debugInfo.response?.imageCount,
+                });
+            }
+        }
+        catch (error) {
+            console.error('[TTI Debug] Failed to save log:', error);
+        }
+    }
+    /**
+     * Log an error
+     */
+    static async logError(debugInfo) {
+        if (!this._enabled)
+            return;
+        try {
+            await this.saveToMarkdown(debugInfo);
+            if (this._consoleLog) {
+                console.error('[TTI Debug] Error:', debugInfo.error);
+            }
+        }
+        catch (error) {
+            console.error('[TTI Debug] Failed to save error log:', error);
+        }
+    }
+    // ============================================================
+    // MARKDOWN GENERATION
+    // ============================================================
+    /**
+     * Save debug info to a markdown file
+     */
+    static async saveToMarkdown(debugInfo) {
+        this.ensureLogsDirectory();
+        const filename = this.generateFilename(debugInfo);
+        const filepath = path.join(this._logsDir, filename);
+        const content = this.formatMarkdown(debugInfo);
+        await fs.promises.writeFile(filepath, content, 'utf-8');
+        return filepath;
+    }
+    /**
+     * Generate a filename for the log file
+     */
+    static generateFilename(debugInfo) {
+        const timestamp = debugInfo.requestTimestamp
+            .toISOString()
+            .replace(/[:.]/g, '-');
+        const useCasePart = debugInfo.useCase
+            ? `_${debugInfo.useCase.toLowerCase().replace(/[^a-z0-9]/g, '-')}`
+            : '';
+        const identifierPart = debugInfo.characterId
+            ? `_char-${debugInfo.characterId.substring(0, 8)}`
+            : debugInfo.sectionId
+                ? `_sec-${debugInfo.sectionId.substring(0, 8)}`
+                : '';
+        return `${timestamp}${useCasePart}${identifierPart}.md`;
+    }
+    /**
+     * Format debug info as markdown
+     */
+    static formatMarkdown(debugInfo) {
+        const sections = [];
+        // Header
+        sections.push('# TTI Request & Response Log\n');
+        // Provider Information
+        sections.push('## Provider Information\n');
+        sections.push(`- **Provider**: ${debugInfo.provider}`);
+        sections.push(`- **Model**: ${debugInfo.model}`);
+        if (debugInfo.region) {
+            sections.push(`- **Region**: ${debugInfo.region}`);
+        }
+        sections.push('');
+        // Request Information
+        sections.push('## Request Information\n');
+        sections.push(`- **Request Timestamp**: ${debugInfo.requestTimestamp.toISOString()}`);
+        if (debugInfo.responseTimestamp) {
+            sections.push(`- **Response Timestamp**: ${debugInfo.responseTimestamp.toISOString()}`);
+        }
+        if (debugInfo.useCase) {
+            sections.push(`- **Use Case**: ${debugInfo.useCase}`);
+        }
+        if (debugInfo.sessionId) {
+            sections.push(`- **Session ID**: ${debugInfo.sessionId}`);
+        }
+        if (debugInfo.bookId) {
+            sections.push(`- **Book ID**: ${debugInfo.bookId}`);
+        }
+        if (debugInfo.characterId) {
+            sections.push(`- **Character ID**: ${debugInfo.characterId}`);
+        }
+        if (debugInfo.sectionId) {
+            sections.push(`- **Section ID**: ${debugInfo.sectionId}`);
+        }
+        if (debugInfo.aspectRatio) {
+            sections.push(`- **Aspect Ratio**: ${debugInfo.aspectRatio}`);
+        }
+        sections.push('');
+        // Reference Images
+        sections.push('## Reference Images\n');
+        sections.push(`- **Count**: ${debugInfo.referenceImageCount}`);
+        if (debugInfo.referenceImageMimeTypes &&
+            debugInfo.referenceImageMimeTypes.length > 0) {
+            sections.push(`- **MIME Types**: ${debugInfo.referenceImageMimeTypes.join(', ')}`);
+        }
+        sections.push('');
+        // Subject Description (important for character consistency debugging)
+        sections.push('## Subject Description\n');
+        if (debugInfo.subjectDescription) {
+            sections.push('```');
+            sections.push(debugInfo.subjectDescription);
+            sections.push('```');
+        }
+        else {
+            sections.push('*No subject description provided (raw multimodal mode)*');
+        }
+        sections.push('');
+        // Prompt (the most important part for debugging)
+        sections.push('## Prompt\n');
+        sections.push('```');
+        sections.push(debugInfo.prompt);
+        sections.push('```');
+        sections.push('');
+        // Provider Options
+        if (debugInfo.providerOptions &&
+            Object.keys(debugInfo.providerOptions).length > 0) {
+            sections.push('## Provider Options\n');
+            sections.push('```json');
+            sections.push(JSON.stringify(debugInfo.providerOptions, null, 2));
+            sections.push('```');
+            sections.push('');
+        }
+        // Response
+        if (debugInfo.response) {
+            sections.push('## Response\n');
+            sections.push(`- **Image Count**: ${debugInfo.response.imageCount}`);
+            sections.push(`- **MIME Types**: ${debugInfo.response.imageMimeTypes.join(', ')}`);
+            sections.push(`- **Duration**: ${debugInfo.response.duration}ms`);
+            sections.push('');
+        }
+        // Raw Request Data (without base64)
+        if (debugInfo.rawRequest) {
+            sections.push('## Raw Request Data\n');
+            sections.push('```json');
+            const sanitizedRequest = this.sanitizeRequest(debugInfo.rawRequest);
+            sections.push(JSON.stringify(sanitizedRequest, null, 2));
+            sections.push('```');
+            sections.push('');
+        }
+        // Raw Response Data (without base64)
+        if (debugInfo.rawResponse) {
+            sections.push('## Raw Response Data\n');
+            sections.push('```json');
+            const sanitizedResponse = this.sanitizeResponse(debugInfo.rawResponse);
+            sections.push(JSON.stringify(sanitizedResponse, null, 2));
+            sections.push('```');
+            sections.push('');
+        }
+        // Error
+        if (debugInfo.error) {
+            sections.push('## Error\n');
+            sections.push(`- **Message**: ${debugInfo.error.message}`);
+            if (debugInfo.error.code) {
+                sections.push(`- **Code**: ${debugInfo.error.code}`);
+            }
+            if (debugInfo.error.details) {
+                sections.push('- **Details**:');
+                sections.push('```json');
+                sections.push(JSON.stringify(debugInfo.error.details, null, 2));
+                sections.push('```');
+            }
+            sections.push('');
+        }
+        // Footer
+        sections.push('---');
+        sections.push(`*Generated on ${new Date().toISOString()}*`);
+        return sections.join('\n');
+    }
+    /**
+     * Sanitize request by removing/truncating base64 data
+     */
+    static sanitizeRequest(request) {
+        const sanitized = { ...request };
+        if (request.referenceImages && !this._includeBase64) {
+            sanitized.referenceImages = request.referenceImages.map((ref, index) => ({
+                index,
+                mimeType: ref.mimeType || 'unknown',
+                base64Length: ref.base64?.length || 0,
+                base64Preview: ref.base64 ? `${ref.base64.substring(0, 50)}...` : null,
+            }));
+        }
+        return sanitized;
+    }
+    /**
+     * Sanitize response by removing/truncating base64 data
+     */
+    static sanitizeResponse(response) {
+        const sanitized = { ...response };
+        if (response.images && !this._includeBase64) {
+            sanitized.images = response.images.map((img, index) => ({
+                index,
+                contentType: img.contentType || 'unknown',
+                hasUrl: !!img.url,
+                base64Length: img.base64?.length || 0,
+                base64Preview: img.base64 ? `${img.base64.substring(0, 50)}...` : null,
+            }));
+        }
+        return sanitized;
+    }
+    // ============================================================
+    // HELPER METHODS
+    // ============================================================
+    /**
+     * Ensure the logs directory exists
+     */
+    static ensureLogsDirectory() {
+        if (!fs.existsSync(this._logsDir)) {
+            fs.mkdirSync(this._logsDir, { recursive: true });
+        }
+    }
+    /**
+     * Create debug info from a request (helper for providers)
+     */
+    static createDebugInfo(request, provider, model, options) {
+        return {
+            requestTimestamp: new Date(),
+            provider,
+            model,
+            region: options?.region,
+            prompt: request.prompt,
+            subjectDescription: request.subjectDescription,
+            referenceImageCount: request.referenceImages?.length || 0,
+            referenceImageMimeTypes: request.referenceImages?.map((ref) => ref.mimeType || 'unknown'),
+            aspectRatio: request.aspectRatio,
+            providerOptions: request.providerOptions,
+            useCase: options?.useCase,
+            sessionId: options?.sessionId,
+            bookId: options?.bookId,
+            characterId: options?.characterId,
+            sectionId: options?.sectionId,
+            rawRequest: request,
+        };
+    }
+    /**
+     * Update debug info with response data (helper for providers)
+     */
+    static updateWithResponse(debugInfo, response) {
+        return {
+            ...debugInfo,
+            responseTimestamp: new Date(),
+            response: {
+                imageCount: response.images.length,
+                imageMimeTypes: response.images.map((img) => img.contentType || 'unknown'),
+                duration: response.metadata.duration,
+            },
+            rawResponse: response,
+        };
+    }
+    /**
+     * Update debug info with error data (helper for providers)
+     */
+    static updateWithError(debugInfo, error) {
+        return {
+            ...debugInfo,
+            responseTimestamp: new Date(),
+            error: {
+                message: error.message,
+                code: error.code,
+                details: error.cause,
+            },
+        };
+    }
+}
+exports.TTIDebugger = TTIDebugger;
+TTIDebugger._enabled = process.env.DEBUG_TTI_REQUESTS === 'true' ||
+    process.env.NODE_ENV === 'development';
+TTIDebugger._logsDir = process.env.TTI_DEBUG_LOG_DIR ||
+    path.join(process.cwd(), 'logs', 'tti', 'requests');
+TTIDebugger._includeBase64 = false;
+TTIDebugger._consoleLog = false;
+// ============================================================
+// EXPORTS
+// ============================================================
+exports.default = TTIDebugger;

package/dist/middleware/services/tti/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './debug-tti.utils';

package/dist/middleware/services/tti/utils/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./debug-tti.utils"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loonylabs/tti-middleware",
-  "version": "1.0.0",
+  "version": "1.1.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",