@mixio-pro/kalaasetu-mcp 1.2.1 → 2.0.1-beta

package/src/utils/prompt-enhancer-presets.ts

@@ -0,0 +1,303 @@
+/**
+ * Prompt Enhancer Presets
+ *
+ * A factory/dictionary of predefined prompt enhancer configurations.
+ * Organized by use case: image generation, video generation, and specialized styles.
+ *
+ * Based on best practices from LTX-2 prompting guide and industry standards.
+ */
+
+import { PromptEnhancer, type PromptEnhancerConfig } from "./prompt-enhancer";
+
+// =============================================================================
+// IMAGE GENERATION PRESETS
+// =============================================================================
+
+/**
+ * Presets optimized for image generation (Gemini Imagen, Flux, SD, etc.)
+ */
+export const IMAGE_PRESETS: Record<string, PromptEnhancerConfig> = {
+  /**
+   * Cinematic still photography style
+   */
+  cinematic: {
+    styleGuide:
+      "cinematic composition, dramatic lighting, shallow depth of field, film grain, 4K, hyperdetailed",
+    negativeElements:
+      "blurry, low quality, pixelated, distorted, watermark, text, logo",
+  },
+
+  /**
+   * Photorealistic, DSLR-quality imagery
+   */
+  photorealistic: {
+    styleGuide:
+      "photorealistic, ultra-detailed, natural lighting, DSLR quality, 8K resolution, sharp focus",
+    negativeElements:
+      "cartoon, anime, illustration, painting, blurry, distorted, artificial",
+  },
+
+  /**
+   * Anime and manga illustration style
+   */
+  anime: {
+    styleGuide:
+      "anime style, vibrant colors, cel-shaded, detailed linework, Studio Ghibli inspired",
+    negativeElements:
+      "photorealistic, 3D render, Western cartoon, blurry, low detail",
+  },
+
+  /**
+   * Abstract and modern art
+   */
+  abstract: {
+    styleGuide:
+      "abstract art, geometric shapes, bold colors, modern art, contemporary, expressive brushstrokes",
+    negativeElements:
+      "photorealistic, detailed faces, text, logo, realistic proportions",
+  },
+
+  /**
+   * Vintage and retro aesthetic
+   */
+  vintage: {
+    styleGuide:
+      "vintage aesthetic, retro, film grain, 1970s color palette, warm tones, nostalgic, analog photography",
+    negativeElements:
+      "modern, digital, clean, sharp, contemporary, high contrast",
+  },
+
+  /**
+   * Fashion editorial photography
+   */
+  fashion_editorial: {
+    styleGuide:
+      "fashion editorial, high-end photography, professional lighting, Vogue style, elegant composition, soft rim light",
+    negativeElements:
+      "casual, amateur, blurry, bad lighting, unflattering angle",
+  },
+
+  /**
+   * Fantasy illustration
+   */
+  fantasy: {
+    styleGuide:
+      "fantasy art, epic composition, magical atmosphere, detailed, painterly, dramatic lighting, ethereal",
+    negativeElements: "modern, realistic, mundane, blurry, low detail",
+  },
+
+  /**
+   * Minimalist design
+   */
+  minimalist: {
+    styleGuide:
+      "minimalist design, clean lines, negative space, simple composition, modern, elegant, refined",
+    negativeElements: "cluttered, busy, detailed, ornate, complex, messy",
+  },
+};
+
+// =============================================================================
+// VIDEO GENERATION PRESETS
+// Based on LTX-2 Prompting Guide best practices
+// =============================================================================
+
+/**
+ * Presets optimized for video generation (LTX, Luma, Veo, etc.)
+ * Following LTX-2 guidelines:
+ * - Establish the shot with cinematography terms
+ * - Set the scene with lighting/atmosphere
+ * - Describe action as natural sequence
+ * - Define camera movements clearly
+ */
+export const VIDEO_PRESETS: Record<string, PromptEnhancerConfig> = {
+  /**
+   * LTX-2 specific preset based on official prompting guide.
+   * Key principles:
+   * - Establish shot with cinematography terms
+   * - Set scene with lighting/atmosphere
+   * - Describe action as natural flowing sequence
+   * - Use clean, readable camera language
+   * - Focus on emotive moments, atmosphere, and stylized aesthetics
+   */
+  ltx2: {
+    // No prefix - LTX-2 wants complete flowing scenes, not formulaic starts
+    suffix:
+      "The camera captures this with thoughtful cinematography, shallow depth of field, and natural motion.",
+    styleGuide:
+      "cinematic composition, present tense, flowing narrative, clear camera language, atmospheric lighting, emotive expressions through physical cues",
+    negativeElements:
+      "text, logos, signage, brand names, complex physics, chaotic motion, jumping, juggling, conflicting light sources, overloaded scene, too many characters, internal emotional states without visual cues",
+  },
+
+  /**
+   * Cinematic video with dramatic camera work
+   */
+  cinematic_video: {
+    prefix: "A cinematic shot.",
+    styleGuide:
+      "smooth camera movement, professional cinematography, dramatic lighting, shallow depth of field, film grain, cinematic color grading",
+    negativeElements:
+      "shaky camera, low quality, pixelated, glitchy, jerky motion, text overlay",
+  },
+
+  /**
+   * Documentary-style realistic footage
+   */
+  documentary: {
+    prefix: "Documentary footage.",
+    styleGuide:
+      "natural lighting, handheld camera feel, authentic, observational, steady tracking shot",
+    negativeElements:
+      "staged, artificial, over-produced, fantasy elements, special effects",
+  },
+
+  /**
+   * Action-packed dynamic shots
+   */
+  action: {
+    prefix: "An action packed shot.",
+    styleGuide:
+      "dynamic camera movement, motion blur, intense, fast-paced, dramatic angles, handheld feel",
+    negativeElements:
+      "static, slow, boring, calm, peaceful, stable tripod shot",
+  },
+
+  /**
+   * Slow and atmospheric
+   */
+  atmospheric: {
+    styleGuide:
+      "slow camera movement, atmospheric, moody lighting, fog or mist, ambient, lingering shot, soft focus background",
+    negativeElements:
+      "fast motion, harsh lighting, chaotic, busy, cluttered scene",
+  },
+
+  /**
+   * Talking head / dialogue scene
+   */
+  dialogue: {
+    prefix: "A warm, intimate scene.",
+    styleGuide:
+      "medium close-up, soft lighting, natural conversation, over-the-shoulder shots, subtle camera movement, realistic acting",
+    negativeElements:
+      "wide shot, action, fast movement, loud, chaotic, unrealistic",
+  },
+
+  /**
+   * Product showcase / commercial
+   */
+  commercial: {
+    styleGuide:
+      "smooth dolly movement, professional studio lighting, clean background, product focus, slow rotation, sharp detail, premium aesthetic",
+    negativeElements:
+      "cluttered, dark, amateur, shaky, low quality, distraction",
+  },
+
+  /**
+   * Animation / stylized motion
+   */
+  animated: {
+    styleGuide:
+      "animated style, expressive movement, stylized timing, smooth transitions, character animation, vibrant colors",
+    negativeElements: "photorealistic, live action, jerky, static, dull colors",
+  },
+
+  /**
+   * Establish wide shot for scene setting
+   */
+  establishing: {
+    prefix: "Wide establishing shot.",
+    styleGuide:
+      "expansive view, slow pan or static frame, epic scale, atmospheric, cinematic composition, golden hour lighting",
+    negativeElements:
+      "close-up, cluttered, indoor, tight framing, rapid movement",
+  },
+
+  /**
+   * Intimate close-up for emotional moments
+   */
+  closeup_emotional: {
+    prefix: "An intimate close-up.",
+    styleGuide:
+      "tight framing on face, shallow depth of field, emotional expression, soft lighting, subtle movement, eyes in focus",
+    negativeElements:
+      "wide shot, distant, cold lighting, static expression, fast movement",
+  },
+};
+
+// =============================================================================
+// COMBINED PRESETS DICTIONARY
+// =============================================================================
+
+/**
+ * All available prompt enhancer presets.
+ */
+export const PROMPT_ENHANCER_PRESETS: Record<string, PromptEnhancerConfig> = {
+  ...IMAGE_PRESETS,
+  ...VIDEO_PRESETS,
+};
+
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+
+/**
+ * Get a PromptEnhancer for a named preset.
+ * Returns undefined if the preset doesn't exist.
+ */
+export function getPromptEnhancer(
+  presetName: string
+): PromptEnhancer | undefined {
+  const config = PROMPT_ENHANCER_PRESETS[presetName];
+  if (!config) {
+    return undefined;
+  }
+  return PromptEnhancer.fromConfig(config);
+}
+
+/**
+ * List all available enhancer preset names.
+ */
+export function listEnhancerPresets(): string[] {
+  return Object.keys(PROMPT_ENHANCER_PRESETS);
+}
+
+/**
+ * List image-specific enhancer preset names.
+ */
+export function listImageEnhancerPresets(): string[] {
+  return Object.keys(IMAGE_PRESETS);
+}
+
+/**
+ * List video-specific enhancer preset names.
+ */
+export function listVideoEnhancerPresets(): string[] {
+  return Object.keys(VIDEO_PRESETS);
+}
+
+/**
+ * Resolve an enhancer from either a preset name (string) or inline config.
+ * Returns PASSTHROUGH enhancer if resolution fails.
+ */
+export function resolveEnhancer(
+  input: string | PromptEnhancerConfig | undefined
+): PromptEnhancer {
+  if (!input) {
+    return PromptEnhancer.PASSTHROUGH;
+  }
+
+  if (typeof input === "string") {
+    const enhancer = getPromptEnhancer(input);
+    if (!enhancer) {
+      console.warn(
+        `Prompt enhancer preset '${input}' not found, using passthrough.`
+      );
+      return PromptEnhancer.PASSTHROUGH;
+    }
+    return enhancer;
+  }
+
+  // It's an inline config object
+  return PromptEnhancer.fromConfig(input);
+}

package/src/utils/prompt-enhancer.ts

@@ -0,0 +1,186 @@
+/**
+ * Prompt Enhancer Utility
+ *
+ * A fluent builder pattern for constructing prompt enhancers that can be
+ * applied to improve prompts for image and video generation models.
+ */
+
+/**
+ * Configuration interface for a prompt enhancer.
+ */
+export interface PromptEnhancerConfig {
+  /** Added before the user prompt */
+  prefix?: string;
+  /** Added after the user prompt */
+  suffix?: string;
+  /** Style/quality modifiers (e.g., "cinematic, 8k, hyperdetailed") */
+  styleGuide?: string;
+  /** Elements to avoid (used where supported as negative_prompt) */
+  negativeElements?: string;
+  /** How to join parts (default: " ") */
+  separator?: string;
+  /**
+   * Template to wrap the entire result. Use "{prompt}" as placeholder.
+   * Example: "A cinematic shot of {prompt}, dramatic lighting"
+   */
+  wrapTemplate?: string;
+}
+
+/**
+ * Fluent builder for constructing PromptEnhancer instances.
+ */
+export class PromptEnhancerBuilder {
+  private config: PromptEnhancerConfig = {};
+
+  /**
+   * Add text before the user's prompt.
+   * Useful for establishing shot type or scene context.
+   */
+  withPrefix(text: string): this {
+    this.config.prefix = text;
+    return this;
+  }
+
+  /**
+   * Add text after the user's prompt.
+   * Useful for technical specifications or quality modifiers.
+   */
+  withSuffix(text: string): this {
+    this.config.suffix = text;
+    return this;
+  }
+
+  /**
+   * Add style guide modifiers that get appended.
+   * Examples: "cinematic, film grain, dramatic lighting"
+   */
+  withStyleGuide(styles: string): this {
+    this.config.styleGuide = styles;
+    return this;
+  }
+
+  /**
+   * Set negative elements to avoid in generation.
+   * Used as negative_prompt where supported.
+   */
+  withNegativeElements(elements: string): this {
+    this.config.negativeElements = elements;
+    return this;
+  }
+
+  /**
+   * Set the separator between prompt parts.
+   * Default is a single space " ".
+   */
+  withSeparator(sep: string): this {
+    this.config.separator = sep;
+    return this;
+  }
+
+  /**
+   * Set a template that wraps the entire enhanced prompt.
+   * Use "{prompt}" as placeholder for the combined prompt content.
+   */
+  withTemplate(template: string): this {
+    this.config.wrapTemplate = template;
+    return this;
+  }
+
+  /**
+   * Build the final PromptEnhancer instance.
+   */
+  build(): PromptEnhancer {
+    return PromptEnhancer.fromConfig({ ...this.config });
+  }
+}
+
+/**
+ * Main prompt enhancer class.
+ * Applies configured transformations to improve prompts for AI generation.
+ */
+export class PromptEnhancer {
+  private config: PromptEnhancerConfig;
+
+  private constructor(config: PromptEnhancerConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Create a new fluent builder instance.
+   */
+  static builder(): PromptEnhancerBuilder {
+    return new PromptEnhancerBuilder();
+  }
+
+  /**
+   * Create a PromptEnhancer directly from a config object.
+   */
+  static fromConfig(config: PromptEnhancerConfig): PromptEnhancer {
+    return new PromptEnhancer({ ...config });
+  }
+
+  /**
+   * A no-op enhancer that returns prompts unchanged.
+   */
+  static readonly PASSTHROUGH = new PromptEnhancer({});
+
+  /**
+   * Enhance a prompt by applying all configured transformations.
+   *
+   * Order of operations:
+   * 1. Combine: prefix + prompt + suffix + styleGuide
+   * 2. Apply wrapTemplate if set
+   */
+  enhance(prompt: string): string {
+    const separator = this.config.separator ?? " ";
+    const parts: string[] = [];
+
+    if (this.config.prefix) {
+      parts.push(this.config.prefix);
+    }
+
+    parts.push(prompt);
+
+    if (this.config.suffix) {
+      parts.push(this.config.suffix);
+    }
+
+    if (this.config.styleGuide) {
+      parts.push(this.config.styleGuide);
+    }
+
+    let result = parts.join(separator);
+
+    if (this.config.wrapTemplate) {
+      result = this.config.wrapTemplate.replace("{prompt}", result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the negative elements (for use as negative_prompt).
+   */
+  getNegativeElements(): string | undefined {
+    return this.config.negativeElements;
+  }
+
+  /**
+   * Check if this enhancer has any transformations configured.
+   */
+  hasTransformations(): boolean {
+    return !!(
+      this.config.prefix ||
+      this.config.suffix ||
+      this.config.styleGuide ||
+      this.config.wrapTemplate
+    );
+  }
+
+  /**
+   * Export the enhancer's configuration.
+   */
+  toConfig(): PromptEnhancerConfig {
+    return { ...this.config };
+  }
+}