@contractspec/lib.image-gen 0.2.0

package/dist/generators/index.js

@@ -0,0 +1,528 @@
+// @bun
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "image-gen.messages",
+    version: "1.0.0",
+    domain: "image-gen",
+    description: "All user-facing, LLM-facing, and developer-facing strings for the image-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "prompt.system.imagePromptEngineer": {
+      value: "You are an expert image prompt engineer. Given a JSON brief containing title, summary, problems, solutions, purpose, style, and style tokens, produce a single detailed image generation prompt. The prompt should be vivid, specific, and optimized for AI image generation models. Focus on composition, lighting, color palette, and subject matter. Output only the prompt text, no JSON.",
+      description: "System prompt for LLM-based image prompt engineering"
+    },
+    "image.generate.description": {
+      value: "Generate a {style} image for {purpose}",
+      description: "Description template for image generation tasks",
+      placeholders: [
+        { name: "style", type: "string" },
+        { name: "purpose", type: "string" }
+      ]
+    },
+    "image.prompt.featuring": {
+      value: "featuring {solutions}",
+      description: "Prompt fragment for featured solutions",
+      placeholders: [{ name: "solutions", type: "string" }]
+    },
+    "image.prompt.industryContext": {
+      value: "{industry} context",
+      description: "Prompt fragment for industry context",
+      placeholders: [{ name: "industry", type: "string" }]
+    },
+    "image.error.noProvider": {
+      value: "No image provider configured",
+      description: "Error message when no ImageProvider is available"
+    },
+    "image.error.generationFailed": {
+      value: "Image generation failed",
+      description: "Error message when image generation fails"
+    },
+    "purpose.blogHero": {
+      value: "Blog hero image",
+      description: "Label for blog hero image purpose"
+    },
+    "purpose.socialOg": {
+      value: "Social media OG image",
+      description: "Label for Open Graph image purpose"
+    },
+    "purpose.socialTwitter": {
+      value: "Twitter card image",
+      description: "Label for Twitter card image purpose"
+    },
+    "purpose.socialInstagram": {
+      value: "Instagram image",
+      description: "Label for Instagram image purpose"
+    },
+    "purpose.landingHero": {
+      value: "Landing page hero",
+      description: "Label for landing page hero image purpose"
+    },
+    "purpose.videoThumbnail": {
+      value: "Video thumbnail",
+      description: "Label for video thumbnail purpose"
+    },
+    "purpose.emailHeader": {
+      value: "Email header",
+      description: "Label for email header image purpose"
+    },
+    "purpose.illustration": {
+      value: "Illustration",
+      description: "Label for illustration purpose"
+    },
+    "purpose.icon": {
+      value: "Icon",
+      description: "Label for icon purpose"
+    }
+  }
+});
+
+// src/i18n/catalogs/fr.ts
+import { defineTranslation as defineTranslation2 } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation2({
+  meta: {
+    key: "image-gen.messages",
+    version: "1.0.0",
+    domain: "image-gen",
+    description: "French translations for the image-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "prompt.system.imagePromptEngineer": {
+      value: "Vous \xEAtes un expert en ing\xE9nierie de prompts d'images. \xC0 partir d'un brief JSON contenant titre, r\xE9sum\xE9, probl\xE8mes, solutions, objectif, style et tokens de style, produisez un prompt d\xE9taill\xE9 de g\xE9n\xE9ration d'image. Le prompt doit \xEAtre vivant, sp\xE9cifique et optimis\xE9 pour les mod\xE8les de g\xE9n\xE9ration d'images IA. Concentrez-vous sur la composition, l'\xE9clairage, la palette de couleurs et le sujet. Produisez uniquement le texte du prompt, pas de JSON.",
+      description: "Prompt syst\xE8me pour l'ing\xE9nierie de prompts d'images par LLM"
+    },
+    "image.generate.description": {
+      value: "G\xE9n\xE9rer une image {style} pour {purpose}",
+      description: "Mod\xE8le de description pour les t\xE2ches de g\xE9n\xE9ration d'images",
+      placeholders: [
+        { name: "style", type: "string" },
+        { name: "purpose", type: "string" }
+      ]
+    },
+    "image.prompt.featuring": {
+      value: "mettant en avant {solutions}",
+      description: "Fragment de prompt pour les solutions mises en avant",
+      placeholders: [{ name: "solutions", type: "string" }]
+    },
+    "image.prompt.industryContext": {
+      value: "contexte {industry}",
+      description: "Fragment de prompt pour le contexte industriel",
+      placeholders: [{ name: "industry", type: "string" }]
+    },
+    "image.error.noProvider": {
+      value: "Aucun fournisseur d'images configur\xE9",
+      description: "Message d'erreur quand aucun ImageProvider n'est disponible"
+    },
+    "image.error.generationFailed": {
+      value: "La g\xE9n\xE9ration d'image a \xE9chou\xE9",
+      description: "Message d'erreur quand la g\xE9n\xE9ration d'image \xE9choue"
+    },
+    "purpose.blogHero": {
+      value: "Image hero de blog",
+      description: "Libell\xE9 pour l'objectif image hero de blog"
+    },
+    "purpose.socialOg": {
+      value: "Image OG pour r\xE9seaux sociaux",
+      description: "Libell\xE9 pour l'objectif image Open Graph"
+    },
+    "purpose.socialTwitter": {
+      value: "Image carte Twitter",
+      description: "Libell\xE9 pour l'objectif image carte Twitter"
+    },
+    "purpose.socialInstagram": {
+      value: "Image Instagram",
+      description: "Libell\xE9 pour l'objectif image Instagram"
+    },
+    "purpose.landingHero": {
+      value: "Hero de page d'atterrissage",
+      description: "Libell\xE9 pour l'objectif image hero de page d'atterrissage"
+    },
+    "purpose.videoThumbnail": {
+      value: "Miniature vid\xE9o",
+      description: "Libell\xE9 pour l'objectif miniature vid\xE9o"
+    },
+    "purpose.emailHeader": {
+      value: "En-t\xEAte d'email",
+      description: "Libell\xE9 pour l'objectif image en-t\xEAte d'email"
+    },
+    "purpose.illustration": {
+      value: "Illustration",
+      description: "Libell\xE9 pour l'objectif illustration"
+    },
+    "purpose.icon": {
+      value: "Ic\xF4ne",
+      description: "Libell\xE9 pour l'objectif ic\xF4ne"
+    }
+  }
+});
+
+// src/i18n/catalogs/es.ts
+import { defineTranslation as defineTranslation3 } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation3({
+  meta: {
+    key: "image-gen.messages",
+    version: "1.0.0",
+    domain: "image-gen",
+    description: "Spanish translations for the image-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "prompt.system.imagePromptEngineer": {
+      value: "Eres un experto en ingenier\xEDa de prompts de im\xE1genes. Dado un brief JSON que contiene t\xEDtulo, resumen, problemas, soluciones, prop\xF3sito, estilo y tokens de estilo, produce un prompt detallado de generaci\xF3n de im\xE1genes. El prompt debe ser v\xEDvido, espec\xEDfico y optimizado para modelos de generaci\xF3n de im\xE1genes con IA. Conc\xE9ntrate en la composici\xF3n, iluminaci\xF3n, paleta de colores y tema. Produce solo el texto del prompt, sin JSON.",
+      description: "Prompt del sistema para ingenier\xEDa de prompts de im\xE1genes por LLM"
+    },
+    "image.generate.description": {
+      value: "Generar una imagen {style} para {purpose}",
+      description: "Plantilla de descripci\xF3n para tareas de generaci\xF3n de im\xE1genes",
+      placeholders: [
+        { name: "style", type: "string" },
+        { name: "purpose", type: "string" }
+      ]
+    },
+    "image.prompt.featuring": {
+      value: "presentando {solutions}",
+      description: "Fragmento de prompt para soluciones destacadas",
+      placeholders: [{ name: "solutions", type: "string" }]
+    },
+    "image.prompt.industryContext": {
+      value: "contexto de {industry}",
+      description: "Fragmento de prompt para contexto de industria",
+      placeholders: [{ name: "industry", type: "string" }]
+    },
+    "image.error.noProvider": {
+      value: "No hay proveedor de im\xE1genes configurado",
+      description: "Mensaje de error cuando no hay ImageProvider disponible"
+    },
+    "image.error.generationFailed": {
+      value: "La generaci\xF3n de imagen fall\xF3",
+      description: "Mensaje de error cuando la generaci\xF3n de imagen falla"
+    },
+    "purpose.blogHero": {
+      value: "Imagen hero de blog",
+      description: "Etiqueta para el prop\xF3sito imagen hero de blog"
+    },
+    "purpose.socialOg": {
+      value: "Imagen OG para redes sociales",
+      description: "Etiqueta para el prop\xF3sito imagen Open Graph"
+    },
+    "purpose.socialTwitter": {
+      value: "Imagen de tarjeta Twitter",
+      description: "Etiqueta para el prop\xF3sito imagen tarjeta Twitter"
+    },
+    "purpose.socialInstagram": {
+      value: "Imagen de Instagram",
+      description: "Etiqueta para el prop\xF3sito imagen Instagram"
+    },
+    "purpose.landingHero": {
+      value: "Hero de p\xE1gina de aterrizaje",
+      description: "Etiqueta para el prop\xF3sito imagen hero de p\xE1gina de aterrizaje"
+    },
+    "purpose.videoThumbnail": {
+      value: "Miniatura de video",
+      description: "Etiqueta para el prop\xF3sito miniatura de video"
+    },
+    "purpose.emailHeader": {
+      value: "Encabezado de email",
+      description: "Etiqueta para el prop\xF3sito imagen encabezado de email"
+    },
+    "purpose.illustration": {
+      value: "Ilustraci\xF3n",
+      description: "Etiqueta para el prop\xF3sito ilustraci\xF3n"
+    },
+    "purpose.icon": {
+      value: "Icono",
+      description: "Etiqueta para el prop\xF3sito icono"
+    }
+  }
+});
+
+// src/i18n/messages.ts
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory = createI18nFactory({
+  specKey: "image-gen.messages",
+  catalogs: [enMessages, frMessages, esMessages]
+});
+var createImageGenI18n = factory.create;
+var getDefaultI18n = factory.getDefault;
+var resetI18nRegistry = factory.resetRegistry;
+
+// src/generators/prompt-builder.ts
+class PromptBuilder {
+  llm;
+  model;
+  temperature;
+  i18n;
+  constructor(options) {
+    this.llm = options.llm;
+    this.model = options.model;
+    this.temperature = options.temperature ?? 0.4;
+    this.i18n = options.i18n;
+  }
+  async build(brief, resolvedStyle) {
+    const style = brief.style ?? "photorealistic";
+    const format = brief.format ?? "png";
+    if (this.llm) {
+      try {
+        return await this.buildWithLlm(brief, resolvedStyle, style, format);
+      } catch {
+        return this.buildDeterministic(brief, resolvedStyle, style, format);
+      }
+    }
+    return this.buildDeterministic(brief, resolvedStyle, style, format);
+  }
+  async buildWithLlm(brief, resolvedStyle, style, format) {
+    const systemPrompt = this.i18n.t("prompt.system.imagePromptEngineer");
+    const briefJson = JSON.stringify({
+      title: brief.content.title,
+      summary: brief.content.summary,
+      problems: brief.content.problems,
+      solutions: brief.content.solutions,
+      purpose: brief.purpose,
+      style,
+      styleTokens: resolvedStyle.styleTokens
+    });
+    const messages = [
+      {
+        role: "system",
+        content: [{ type: "text", text: systemPrompt }]
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: briefJson }]
+      }
+    ];
+    const llm = this.llm;
+    if (!llm) {
+      throw new Error("LLM provider is required for buildWithLlm");
+    }
+    const response = await llm.chat(messages, {
+      model: this.model,
+      temperature: this.temperature
+    });
+    const text = response.message.content.filter((block) => block.type === "text").map((block) => ("text" in block) ? block.text : "").join("");
+    return {
+      text: text.trim(),
+      negativeText: resolvedStyle.negativeTokens.join(", "),
+      style,
+      dimensions: resolvedStyle.dimensions,
+      format
+    };
+  }
+  buildDeterministic(brief, resolvedStyle, style, format) {
+    const parts = [
+      brief.content.title,
+      this.i18n.t("image.generate.description", {
+        style,
+        purpose: brief.purpose
+      })
+    ];
+    if (brief.content.solutions.length > 0) {
+      parts.push(this.i18n.t("image.prompt.featuring", {
+        solutions: brief.content.solutions.slice(0, 3).join(", ")
+      }));
+    }
+    if (brief.content.audience?.industry) {
+      parts.push(this.i18n.t("image.prompt.industryContext", {
+        industry: brief.content.audience.industry
+      }));
+    }
+    parts.push(...resolvedStyle.styleTokens);
+    return {
+      text: parts.join(", "),
+      negativeText: resolvedStyle.negativeTokens.join(", "),
+      style,
+      dimensions: resolvedStyle.dimensions,
+      format
+    };
+  }
+}
+
+// src/types.ts
+import { IMAGE_PRESETS } from "@contractspec/lib.contracts-integrations/integrations/providers/image";
+// src/generators/style-resolver.ts
+var PURPOSE_DIMENSIONS = {
+  "blog-hero": IMAGE_PRESETS.blogHero,
+  "social-og": IMAGE_PRESETS.ogImage,
+  "social-twitter": IMAGE_PRESETS.twitterCard,
+  "social-instagram": IMAGE_PRESETS.instagramSquare,
+  "landing-hero": IMAGE_PRESETS.blogHero,
+  "video-thumbnail": IMAGE_PRESETS.thumbnail,
+  "email-header": IMAGE_PRESETS.emailHeader,
+  illustration: IMAGE_PRESETS.illustration,
+  icon: IMAGE_PRESETS.favicon
+};
+var STYLE_TOKENS = {
+  photorealistic: [
+    "professional photography",
+    "high resolution",
+    "natural lighting",
+    "detailed textures"
+  ],
+  illustration: [
+    "digital illustration",
+    "clean lines",
+    "vibrant colors",
+    "artistic composition"
+  ],
+  "3d-render": [
+    "3D render",
+    "volumetric lighting",
+    "glossy materials",
+    "depth of field"
+  ],
+  "flat-design": [
+    "clean flat vector",
+    "geometric shapes",
+    "solid colors",
+    "minimal shadows"
+  ],
+  abstract: [
+    "abstract composition",
+    "bold shapes",
+    "dynamic colors",
+    "artistic interpretation"
+  ],
+  minimalist: [
+    "minimalist design",
+    "clean whitespace",
+    "simple elements",
+    "restrained palette"
+  ],
+  branded: [
+    "brand-consistent design",
+    "professional layout",
+    "corporate aesthetic",
+    "clean composition"
+  ]
+};
+var BASE_NEGATIVE_TOKENS = [
+  "blurry",
+  "low quality",
+  "text overlay",
+  "watermark",
+  "distorted",
+  "pixelated"
+];
+
+class StyleResolver {
+  resolve(purpose, style, brand) {
+    const resolvedStyle = style ?? "photorealistic";
+    const dimensions = PURPOSE_DIMENSIONS[purpose];
+    const styleTokens = [...STYLE_TOKENS[resolvedStyle]];
+    const negativeTokens = [...BASE_NEGATIVE_TOKENS];
+    if (brand) {
+      if (brand.primary) {
+        styleTokens.push(`primary color ${brand.primary} palette`);
+      }
+      if (brand.accent) {
+        styleTokens.push(`accent color ${brand.accent}`);
+      }
+      if (brand.background) {
+        styleTokens.push(`background color ${brand.background}`);
+      }
+    }
+    return { styleTokens, negativeTokens, dimensions };
+  }
+}
+
+// src/generators/image-generator.ts
+var DEFAULT_CLOCK = {
+  now: () => Date.now(),
+  toISOString: () => new Date().toISOString()
+};
+
+class ImageGenerator {
+  promptBuilder;
+  styleResolver;
+  options;
+  i18n;
+  clock;
+  constructor(options) {
+    this.options = options ?? {};
+    this.i18n = createImageGenI18n(options?.locale);
+    this.clock = options?.clock ?? DEFAULT_CLOCK;
+    this.styleResolver = new StyleResolver;
+    this.promptBuilder = new PromptBuilder({
+      llm: options?.llm,
+      model: options?.model,
+      temperature: options?.temperature,
+      i18n: this.i18n
+    });
+  }
+  async generate(brief) {
+    const resolvedStyle = this.styleResolver.resolve(brief.purpose, brief.style ?? this.options.defaultStyle, brief.brandColors);
+    const prompt = await this.promptBuilder.build(brief, resolvedStyle);
+    if (brief.dimensions) {
+      prompt.dimensions = brief.dimensions;
+    }
+    const id = this.generateId(brief);
+    const project = {
+      id,
+      prompt,
+      metadata: {
+        purpose: brief.purpose,
+        title: brief.content.title,
+        createdAt: this.clock.toISOString(),
+        locale: brief.locale ?? this.options.locale ?? "en"
+      }
+    };
+    if (this.options.image) {
+      try {
+        const results = await this.options.image.generate({
+          prompt: prompt.text,
+          negativePrompt: prompt.negativeText,
+          dimensions: prompt.dimensions,
+          format: prompt.format,
+          style: this.mapStyleToProviderStyle(prompt.style),
+          numVariants: brief.variants,
+          seed: brief.seed
+        });
+        project.results = results;
+      } catch (error) {
+        const message = this.i18n.t("image.error.generationFailed");
+        throw new Error(message, error instanceof Error ? { cause: error } : undefined);
+      }
+    }
+    return project;
+  }
+  generateId(brief) {
+    const slug = brief.content.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+    const ts = this.clock.now().toString(36);
+    return `img-${slug}-${ts}`;
+  }
+  mapStyleToProviderStyle(style) {
+    const providerStyles = [
+      "photorealistic",
+      "illustration",
+      "3d-render",
+      "flat-design",
+      "abstract"
+    ];
+    if (providerStyles.includes(style)) {
+      return style;
+    }
+    if (style === "minimalist" || style === "branded") {
+      return "flat-design";
+    }
+    return;
+  }
+}
+export {
+  StyleResolver,
+  PromptBuilder,
+  ImageGenerator
+};

package/dist/generators/prompt-builder.d.ts

@@ -0,0 +1,21 @@
+import type { LLMProvider } from '@contractspec/lib.contracts-integrations/integrations/providers/llm';
+import type { ImageBrief, ImagePrompt } from '../types';
+import type { ResolvedStyle } from './style-resolver';
+import type { ImageGenI18n } from '../i18n/messages';
+interface PromptBuilderOptions {
+    llm?: LLMProvider;
+    model?: string;
+    temperature?: number;
+    i18n: ImageGenI18n;
+}
+export declare class PromptBuilder {
+    private readonly llm?;
+    private readonly model?;
+    private readonly temperature;
+    private readonly i18n;
+    constructor(options: PromptBuilderOptions);
+    build(brief: ImageBrief, resolvedStyle: ResolvedStyle): Promise<ImagePrompt>;
+    private buildWithLlm;
+    private buildDeterministic;
+}
+export {};

package/dist/generators/prompt-builder.js

@@ -0,0 +1,94 @@
+// @bun
+// src/generators/prompt-builder.ts
+class PromptBuilder {
+  llm;
+  model;
+  temperature;
+  i18n;
+  constructor(options) {
+    this.llm = options.llm;
+    this.model = options.model;
+    this.temperature = options.temperature ?? 0.4;
+    this.i18n = options.i18n;
+  }
+  async build(brief, resolvedStyle) {
+    const style = brief.style ?? "photorealistic";
+    const format = brief.format ?? "png";
+    if (this.llm) {
+      try {
+        return await this.buildWithLlm(brief, resolvedStyle, style, format);
+      } catch {
+        return this.buildDeterministic(brief, resolvedStyle, style, format);
+      }
+    }
+    return this.buildDeterministic(brief, resolvedStyle, style, format);
+  }
+  async buildWithLlm(brief, resolvedStyle, style, format) {
+    const systemPrompt = this.i18n.t("prompt.system.imagePromptEngineer");
+    const briefJson = JSON.stringify({
+      title: brief.content.title,
+      summary: brief.content.summary,
+      problems: brief.content.problems,
+      solutions: brief.content.solutions,
+      purpose: brief.purpose,
+      style,
+      styleTokens: resolvedStyle.styleTokens
+    });
+    const messages = [
+      {
+        role: "system",
+        content: [{ type: "text", text: systemPrompt }]
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: briefJson }]
+      }
+    ];
+    const llm = this.llm;
+    if (!llm) {
+      throw new Error("LLM provider is required for buildWithLlm");
+    }
+    const response = await llm.chat(messages, {
+      model: this.model,
+      temperature: this.temperature
+    });
+    const text = response.message.content.filter((block) => block.type === "text").map((block) => ("text" in block) ? block.text : "").join("");
+    return {
+      text: text.trim(),
+      negativeText: resolvedStyle.negativeTokens.join(", "),
+      style,
+      dimensions: resolvedStyle.dimensions,
+      format
+    };
+  }
+  buildDeterministic(brief, resolvedStyle, style, format) {
+    const parts = [
+      brief.content.title,
+      this.i18n.t("image.generate.description", {
+        style,
+        purpose: brief.purpose
+      })
+    ];
+    if (brief.content.solutions.length > 0) {
+      parts.push(this.i18n.t("image.prompt.featuring", {
+        solutions: brief.content.solutions.slice(0, 3).join(", ")
+      }));
+    }
+    if (brief.content.audience?.industry) {
+      parts.push(this.i18n.t("image.prompt.industryContext", {
+        industry: brief.content.audience.industry
+      }));
+    }
+    parts.push(...resolvedStyle.styleTokens);
+    return {
+      text: parts.join(", "),
+      negativeText: resolvedStyle.negativeTokens.join(", "),
+      style,
+      dimensions: resolvedStyle.dimensions,
+      format
+    };
+  }
+}
+export {
+  PromptBuilder
+};

package/dist/generators/prompt-builder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generators/style-resolver.d.ts

@@ -0,0 +1,9 @@
+import type { ImageDimensions, ImagePurpose, ImageStyle, BrandColorOverrides } from '../types';
+export interface ResolvedStyle {
+    styleTokens: string[];
+    negativeTokens: string[];
+    dimensions: ImageDimensions;
+}
+export declare class StyleResolver {
+    resolve(purpose: ImagePurpose, style?: ImageStyle, brand?: BrandColorOverrides): ResolvedStyle;
+}