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

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 };
+  }
+}