studio-lumiere-cli 0.1.0

package/src/pipelines/refineImage.ts

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { GeminiClient } from "../clients/geminiClient.js";
+import { LumiereConfig, RefineRequest } from "../types.js";
+import { readImageAsPart, resolveOutputDir, saveBase64Image, writeJson } from "../storage/files.js";
+
+export const refineImage = async (config: LumiereConfig, request: RefineRequest): Promise<string> => {
+  const client = new GeminiClient(config);
+  const outputDir = resolveOutputDir(request.outputDir ?? config.outputDir, "refinements");
+
+  const sizeAdjustment = request.sizeAdjustment;
+  let prompt = `You are an expert high-end jewelry photo retoucher. Refine this image according to: "${request.instruction}". Preserve jewelry design and materials. Maintain photorealism.`;
+
+  if (sizeAdjustment !== undefined && sizeAdjustment !== 100) {
+    const direction = sizeAdjustment < 100 ? "smaller" : "larger";
+    prompt = `Adjust the size of all jewelry pieces to ${sizeAdjustment}% of current size (${direction}). Preserve all details, lighting, and composition. ${request.instruction}`;
+  }
+
+  const imagePart = await readImageAsPart(request.inputImage);
+  const images = await client.generateImage({
+    parts: [{ text: prompt }, imagePart],
+    imageSize: "2K"
+  });
+
+  const outputPath = path.join(outputDir, "refined.png");
+  await saveBase64Image(images[0], outputPath);
+
+  await writeJson(path.join(outputDir, "refine.json"), {
+    inputImage: request.inputImage,
+    instruction: request.instruction,
+    sizeAdjustment,
+    outputPath
+  });
+
+  return outputPath;
+};
+

package/src/pipelines/resolve.ts

@@ -0,0 +1,88 @@
+import { Option, OccasionTheme, Resolution, Template } from "../types.js";
+import { TEMPLATE_MAP } from "../config/templates.js";
+import {
+  BACKGROUNDS,
+  BACKGROUND_TYPES,
+  ETHNICITIES,
+  HAIR_COLORS,
+  OCCASIONS,
+  RESOLUTIONS,
+  SKIN_TONES,
+  VIBES
+} from "../config/options.js";
+
+const optionMap = (options: Option[]): Map<string, Option> => {
+  return new Map(options.map((opt) => [opt.id, opt]));
+};
+
+const ETHNICITY_MAP = optionMap(ETHNICITIES);
+const SKIN_TONE_MAP = optionMap(SKIN_TONES);
+const HAIR_COLOR_MAP = optionMap(HAIR_COLORS);
+const BACKGROUND_MAP = optionMap(BACKGROUNDS);
+const BACKGROUND_TYPE_MAP = optionMap(BACKGROUND_TYPES);
+const VIBE_MAP = optionMap(VIBES);
+const OCCASION_MAP = new Map(OCCASIONS.map((o) => [o.id, o]));
+const RESOLUTION_MAP = new Map(RESOLUTIONS.map((r) => [r.id, r]));
+
+export const getTemplate = (id: string): Template => {
+  const template = TEMPLATE_MAP.get(id);
+  if (!template) {
+    throw new Error(`Unknown template: ${id}`);
+  }
+  return template;
+};
+
+export const resolveTemplateOption = (template: Template, id?: string, which?: "primary" | "secondary" | "tertiary"): Option | undefined => {
+  if (!id) return undefined;
+  const options =
+    which === "secondary"
+      ? template.secondaryCustomizationOptions
+      : which === "tertiary"
+        ? template.tertiaryCustomizationOptions
+        : template.customizationOptions;
+
+  return options?.find((opt: Option) => opt.id === id) ?? { id, name: id, value: id };
+};
+
+export const resolveEthnicity = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return ETHNICITY_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveSkinTone = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return SKIN_TONE_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveHairColor = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return HAIR_COLOR_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveBackground = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return BACKGROUND_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveBackgroundType = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return BACKGROUND_TYPE_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveVibe = (id?: string): Option | undefined => {
+  if (!id) return undefined;
+  return VIBE_MAP.get(id) ?? { id, name: id, value: id };
+};
+
+export const resolveOccasion = (id?: string): OccasionTheme | undefined => {
+  if (!id) return undefined;
+  return OCCASION_MAP.get(id);
+};
+
+export const resolveResolution = (id?: string): Resolution => {
+  const fallback = RESOLUTION_MAP.get("portrait") ?? Array.from(RESOLUTION_MAP.values())[0];
+  if (!fallback) throw new Error("No resolutions configured.");
+  if (!id) return fallback;
+  return RESOLUTION_MAP.get(id) ?? fallback;
+};
+

package/src/pipelines/upscaleImage.ts

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { GeminiClient } from "../clients/geminiClient.js";
+import { LumiereConfig, UpscaleRequest } from "../types.js";
+import { readImageAsPart, resolveOutputDir, saveBase64Image, writeJson } from "../storage/files.js";
+
+export const upscaleImage = async (config: LumiereConfig, request: UpscaleRequest): Promise<string> => {
+  const client = new GeminiClient(config);
+  const outputDir = resolveOutputDir(request.outputDir ?? config.outputDir, "upscales");
+
+  const scale = request.scale ?? 2;
+  const prompt = `Upscale this image to ${scale}x resolution. Preserve all details, composition, and color. Do not change jewelry design, lighting, or background.`;
+
+  const imagePart = await readImageAsPart(request.inputImage);
+  const images = await client.generateImage({
+    parts: [{ text: prompt }, imagePart],
+    imageSize: scale >= 4 ? "4K" : "2K"
+  });
+
+  const outputPath = path.join(outputDir, "upscaled.png");
+  await saveBase64Image(images[0], outputPath);
+
+  await writeJson(path.join(outputDir, "upscale.json"), {
+    inputImage: request.inputImage,
+    scale,
+    outputPath
+  });
+
+  return outputPath;
+};
+

package/src/prompt/buildPrompt.ts

@@ -0,0 +1,380 @@
+import { Template, Option } from "../types.js";
+import { OccasionTheme, ETHNICITY_REGIONS, getRandomLuxuryInterior } from "../config/constants.js";
+export const buildLLMPrompt = (
+  template: Template,
+  detail: Option | undefined,
+  secondaryDetail: Option | undefined,
+  tertiaryDetail: Option | undefined,
+  ethnicity: Option | undefined,
+  skinTone: Option | undefined,
+  hairColor: Option | undefined,
+  background: Option | undefined,
+  backgroundType: Option | undefined,
+  vibe: Option | undefined,
+  imageCount: number,
+  occasion: OccasionTheme | undefined,
+  isVariation: boolean = false,
+  styleHint?: string
+) => {
+  const needsBothHands = template.id === 'hand_model' && imageCount >= 3;
+  const quantityConstraint = imageCount > 1
+    ? `The model is wearing ALL the provided pieces together. Do NOT add any other jewelry.${needsBothHands ? ' IMPORTANT: Show BOTH hands with the pieces distributed naturally and elegantly across both hands — do NOT cram all pieces onto a single hand.' : ''}`
+    : 'The model is wearing ONLY the single piece of jewelry shown in the reference. Do NOT add matching earrings, necklaces, or other rings.';
+
+  // Dynamic Base Concept
+  let ethnicityLabel = (ethnicity && ethnicity.id !== 'none') ? ethnicity.name : "professional female";
+  
+  // Diversity Injection: Pick a specific region if available
+  if (ethnicity && ethnicity.id && ETHNICITY_REGIONS[ethnicity.id]) {
+    const regions = ETHNICITY_REGIONS[ethnicity.id];
+    const randomRegion = regions[Math.floor(Math.random() * regions.length)];
+    ethnicityLabel = `${randomRegion} (${ethnicity.name})`; 
+  }
+
+  let basePrompt = template.basePrompt;
+  basePrompt = basePrompt.replace(/\[ETHNICITY\]/g, ethnicityLabel);
+
+  const hairColorLabel = (hairColor && hairColor.id !== 'none') ? hairColor.name.toLowerCase() : "natural colored";
+  basePrompt = basePrompt.replace(/\[HAIR_COLOR\]/g, hairColorLabel);
+
+  let instruction = `Write a highly detailed, structured photorealistic prompt for the specific jewelry shown in the attached images.
+
+══════════════════════════════════
+📸 PHOTOGRAPHY SPECIFICATION
+══════════════════════════════════
+Base Concept: ${basePrompt}
+Camera: Hasselblad X2D 100C, 120mm Macro lens, f/2.8
+Target: Authentic, high-end editorial photography. Cinematic, naturalistic, slightly imperfect.
+
+══════════════════════════════════
+💎 SUBJECT & JEWELRY (HIGHEST PRIORITY)
+══════════════════════════════════
+${quantityConstraint}
+CRITICAL: Describe the jewelry EXACTLY as seen in the reference images. Preserve all details: metal type, stone cuts, chain style, settings, etc.
+Do NOT invent additional jewelry pieces or embellishments.
+Do NOT add sparkles, glitter, or magical glow effects.
+`;
+
+  // OCCASION CONTEXT - Give this prominence if selected
+  if (occasion?.promptDetails) {
+    instruction += `
+══════════════════════════════════
+🎭 OCCASION CONTEXT: ${occasion.name.toUpperCase()}
+══════════════════════════════════
+${occasion.description}
+
+🏛️ SETTING & ENVIRONMENT:
+${occasion.promptDetails.setting}
+
+✨ ATMOSPHERE & MOOD:
+${occasion.promptDetails.atmosphere}
+
+🎨 COLOR PALETTE:
+${occasion.promptDetails.colorPalette}
+
+🌟 CULTURAL & THEMATIC ELEMENTS:
+${occasion.promptDetails.culturalElements}
+
+💄 MODEL STYLING & AESTHETIC:
+${occasion.promptDetails.styling}
+`;
+  }
+
+  // MODEL CUSTOMIZATIONS
+  let modelDetails = [];
+
+  if (ethnicity && ethnicity.id !== 'none') {
+    modelDetails.push(`Model Ethnicity: ${ethnicityLabel}`);
+  }
+
+  if (detail) {
+    // Replace [HAIR_COLOR] in the detail value (e.g. Hairstyle Context)
+    const detailValue = detail.value.replace(/\[HAIR_COLOR\]/g, hairColorLabel);
+    modelDetails.push(`${template.customizationLabel}: ${detailValue}`);
+  } else if (template.customizationLabel?.toLowerCase().includes('makeup')) {
+    modelDetails.push(`${template.customizationLabel}: completely bare faced, no makeup, fresh natural skin`);
+  } else if (template.customizationLabel?.toLowerCase().includes('nail')) {
+    modelDetails.push(`${template.customizationLabel}: natural unpainted nails with a clear healthy coat`);
+  }
+
+  if (secondaryDetail) {
+    modelDetails.push(`${template.secondaryCustomizationLabel}: ${secondaryDetail.value}`);
+  } else if (template.secondaryCustomizationLabel?.toLowerCase().includes('makeup')) {
+    modelDetails.push(`${template.secondaryCustomizationLabel}: completely bare faced, no makeup, fresh natural skin`);
+  } else if (template.secondaryCustomizationLabel?.toLowerCase().includes('nail')) {
+    modelDetails.push(`${template.secondaryCustomizationLabel}: natural unpainted nails with a clear healthy coat`);
+  }
+
+  if (tertiaryDetail) {
+    modelDetails.push(`${template.tertiaryCustomizationLabel}: ${tertiaryDetail.value}`);
+  } else if (template.tertiaryCustomizationLabel?.toLowerCase().includes('makeup')) {
+    modelDetails.push(`${template.tertiaryCustomizationLabel}: completely bare faced, no makeup, fresh natural skin`);
+  } else if (template.tertiaryCustomizationLabel?.toLowerCase().includes('nail')) {
+    modelDetails.push(`${template.tertiaryCustomizationLabel}: natural unpainted nails with a clear healthy coat`);
+  }
+
+      if (skinTone && skinTone.id !== 'none' && !template.id.includes('flatlay')) {
+
+    
+
+        modelDetails.push(`Model Skin Tone: ${skinTone.value}`);
+
+    
+
+      }
+
+  
+
+      if (hairColor && hairColor.id !== 'none' && !['hand_model', 'flatlay_creative', 'floating_minimal'].includes(template.id)) {
+
+  
+
+    
+
+  
+
+        modelDetails.push(`Model Hair Color: ${hairColor.value}`);
+
+  
+
+    
+
+  
+
+      }
+
+  
+
+  
+
+  
+
+    if (modelDetails.length > 0) {
+    instruction += `
+══════════════════════════════════
+👤 MODEL SPECIFICATIONS
+══════════════════════════════════
+${modelDetails.join('\n')}
+The model should look like a natural, real human.
+`;
+  }
+
+  // SETTING & BACKGROUND (if not overridden by occasion)
+  if (!occasion && (background || backgroundType || vibe)) {
+    instruction += `
+══════════════════════════════════
+🎬 SETTING & ENVIRONMENT
+══════════════════════════════════
+`;
+
+    if (backgroundType) {
+      const bgValue = backgroundType.id === 'interior' ? getRandomLuxuryInterior() : backgroundType.value;
+      instruction += `Setting Type: ${bgValue}\n`;
+    }
+
+    if (background) {
+      if (template.id === 'flatlay_creative') {
+        instruction += `Secondary accent color/texture element to complement the main surface: ${background.value}\n`;
+      } else {
+        instruction += `Color Palette & Texture: ${background.value}\n`;
+      }
+    }
+
+    if (vibe) {
+      instruction += `Photography Style & Mood: ${vibe.value}\n`;
+    }
+
+    instruction += `\nBackground Treatment: HEAVILY BLURRED (deep cinematic bokeh) to keep focus strictly on the jewelry.
+`;
+  }
+
+  // TECHNICAL REQUIREMENTS
+  instruction += `
+══════════════════════════════════
+⚙️ TECHNICAL REQUIREMENTS
+══════════════════════════════════
+- Natural light reflections on jewelry (NO artificial sparkles or glow)
+- Sharp focus on jewelry with shallow depth of field
+- Authentic photographic quality (film grain acceptable)
+- Professional color grading
+- 2K resolution output quality
+`;
+
+  // STYLE & POSE DIRECTION (for diversity in batch generation)
+  if (styleHint) {
+    instruction += `
+══════════════════════════════════
+🎭 STYLE & POSE DIRECTION
+══════════════════════════════════
+${styleHint}
+IMPORTANT: Follow this specific direction to ensure variety across generated images.
+`;
+  }
+
+  if (isVariation) {
+    instruction += `
+══════════════════════════════════
+🔄 VARIATION INSTRUCTION
+══════════════════════════════════
+Keep the SAME jewelry pieces and overall aesthetic, but RADICALLY CHANGE THE POSE.
+- If previous shot was static, make this dynamic
+- If previous was profile, try 3/4 view or different angle
+- Change hand placement, head tilt, or body position
+- Goal: Fresh perspective with different composition
+`;
+  }
+
+  instruction += `
+══════════════════════════════════
+🚫 STRICT PROHIBITIONS
+══════════════════════════════════
+DO NOT add: fake sparkles, glitter particles, magical glows, lens flares, additional jewelry not in reference
+DO NOT change: the jewelry design, metal type, stone cuts, or any jewelry characteristics
+DO NOT use: artificial effects, over-processing, unrealistic elements
+DO NOT describe: skin details like pores, skin texture, or hyper-realistic skin features - just let the model look naturally human
+
+OUTPUT: A structured JSON-like prompt with distinct sections. Do not use a single block of text. Use the following format:
+
+{
+  "Subject": "Detailed description of the jewelry and model...",
+  "Environment": "Setting, background, and atmosphere...",
+  "Lighting": "Lighting details...",
+  "Photography": "Camera and technical specs..."
+}
+
+Ensure the content of each section is rich, dense, and highly descriptive.
+`;
+
+  return instruction;
+};
+
+export const buildSystemInstruction = (
+  template: Template,
+  ethnicity: Option | undefined
+): string => {
+  const isFloating = template.id === 'floating_minimal';
+  const isFlatlay = template.id === 'flatlay_creative';
+  const isHandModel = template.id === 'hand_model';
+  const isMuseumExhibit = template.id === 'museum_exhibit';
+  const isRomance = template.id === 'romance_proposal';
+  const isRomanticMood = template.id === 'romantic_mood';
+  let llmSystemInstruction = '';
+  if (isRomanticMood) {
+    llmSystemInstruction = `You are a world-renowned still-life photographer and prop stylist for luxury jewelry and lifestyle brands.
+    Your task is to write a prompt for an AI image generator to create a DREAMY, INTIMATE STILL-LIFE PHOTOGRAPH of jewelry in a romantic setting.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces.
+       - Do NOT modify the design of the existing jewelry.
+    2. **PROP DISCIPLINE (CRITICAL)**: Use ONLY the specific prop/scene described in the user's customization choice. Do NOT add other props.
+       - If the user chose "candles", the scene is ONLY candles and the jewelry. Do NOT add roses, letters, or other objects.
+       - If the user chose "rose petals", the scene is ONLY rose petals and the jewelry. Do NOT add candles, letters, or other objects.
+       - Keep the scene focused and minimal — one prop theme, not a cluttered collection of romantic clichés.
+    3. **Subject**: NO human model, NO body parts, NO mannequins, NO hands.
+    4. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Use natural light and genuine material textures.
+    5. **Realism**: Use product photography keywords (Hasselblad X2D 100C, 120mm Macro, f/2.8, shallow depth of field). Props must look real and tactile.
+    6. **Vibe**: Romantic, intimate, dreamy, feminine.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else if (isRomance) {
+    const ethnicityPrompt = (ethnicity && ethnicity.id !== 'none') ? ethnicity.value : "Professional couple";
+    llmSystemInstruction = `You are a world-renowned wedding and engagement photographer, known for capturing raw, authentic emotional moments.
+    Your task is to write a prompt for an AI image generator to create an INTIMATE, EMOTIONALLY POWERFUL photograph based on reference jewelry images.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces (e.g. do not add a necklace if only a ring is provided).
+       - Do NOT modify the design of the existing jewelry.
+    2. **Subject**: Focus on the emotional authenticity of the moment. The jewelry (especially rings) should be prominently visible but feel naturally integrated.
+       - Hands, fingers, and body language are critical storytelling elements.
+       - Ethnicity context: ${ethnicityPrompt}
+    3. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Natural light reflection only.
+    4. **Realism**: Use photography keywords (Contax 645, Zeiss Planar 80mm f/2, Kodak Portra 400).
+    5. **Vibe**: Tender, authentic, emotionally powerful, intimate. Real love story energy.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else if (isMuseumExhibit) {
+    llmSystemInstruction = `You are a world-renowned museum photographer and exhibition designer.
+    Your task is to write a prompt for an AI image generator to create a MUSEUM-QUALITY photograph of jewelry displayed as a priceless exhibit.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces.
+       - Do NOT modify the design of the existing jewelry.
+    2. **Subject**: The jewelry should be displayed as a priceless artifact worthy of the world's greatest museums.
+       - NO human model, NO body parts, NO mannequins.
+    3. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Professional museum lighting only.
+    4. **Realism**: Use professional museum photography equipment and lighting terminology.
+    5. **Vibe**: Reverent, prestigious, archival quality, awe-inspiring.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else if (isFloating) {
+    llmSystemInstruction = `You are a world-renowned product photographer and creative director for luxury jewelry campaigns.
+    Your task is to write a prompt for an AI image generator to create a HYPER-REALISTIC product photograph based on reference images.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces (e.g. do not add earrings if only a necklace is provided).
+       - Do NOT modify the design of the existing jewelry.
+    2. **Subject**: The jewelry should appear to be SUSPENDED in mid-air, floating, with NO human model, NO body parts, and NO mannequins. Focus on dramatic lighting, shadows, and a clean, minimalist composition.
+    3. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Natural light reflection only.
+    4. **Realism**: Use photography keywords (Hasselblad X2D 100C, Macro Lens 120mm, f/2.8).
+    5. **Vibe**: Old money, elegant, classy, expensive, minimalist.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else if (isFlatlay) {
+    llmSystemInstruction = `You are a world-renowned product photographer and creative director for luxury jewelry campaigns.
+    Your task is to write a prompt for an AI image generator to create a HYPER-REALISTIC product photograph based on reference images.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces (e.g. do not add earrings if only a necklace is provided).
+       - Do NOT modify the design of the existing jewelry.
+    2. **Subject**: The jewelry should be displayed as a creative still-life composition, with NO human model, NO body parts, and NO mannequins.
+       - The jewelry may be laid flat on a surface, OR elevated on geometric pedestals, cubes, stone risers, plinths, or sculptural props.
+       - Lighting should always look natural and photographic � soft studio light, window light, or gentle directional light. Shadows should feel organic, not artificial.
+    3. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow", neon lighting, overly stylized color gels. Natural light reflection only.
+    4. **Realism**: Use photography keywords (Hasselblad X2D 100C, Macro Lens 120mm, f/2.8).
+    5. **Vibe**: Old money, elegant, classy, expensive, artistic.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else if (isHandModel) {
+    llmSystemInstruction = `You are a world-renowned product photographer and creative director for luxury jewelry campaigns.
+    Your task is to write a prompt for an AI image generator to create a HYPER-REALISTIC hand model photograph based on reference images.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces (e.g. do not add earrings if only a ring is provided).
+       - Do NOT modify the design of the existing jewelry.
+    2. **FRAMING (CRITICAL)**: The image focuses on the hand, wrist, and forearm area.
+       - NO face, head, or shoulders visible.
+       - The forearm may be bare OR elegantly sleeved (luxurious fabrics like silk, cashmere, lace, velvet).
+       - When clothing is present, it should be high-end and sophisticated.
+    3. **Subject**: A model's hand(s) (age 20-30) with elegant, relaxed pose wearing the jewelry. Focus on authentic skin texture and natural nail appearance.
+       - If 3 or more jewelry pieces are provided, show BOTH hands to distribute the pieces naturally and elegantly across both hands. Avoid cramming all pieces onto a single hand.
+       - If 1-2 pieces, a single hand is fine.
+    4. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Natural light reflection only.
+    5. **Realism**: Use photography keywords (Hasselblad X2D 100C, Macro Lens 120mm, f/2.8).
+    6. **Vibe**: Old money, elegant, classy, expensive, feminine.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  } else {
+    const ethnicityPrompt = (ethnicity && ethnicity.id !== 'none') ? ethnicity.value : "Professional female model";
+    llmSystemInstruction = `You are a world-renowned fashion photographer and creative director for Vogue Arabia and High Jewelry campaigns.
+    Your task is to write a prompt for an AI image generator to create an AUTHENTIC, CINEMATIC photograph based on reference images. Skin texture should look natural and smooth.
+
+    CRITICAL GUIDELINES:
+    1. **JEWELRY FIDELITY (TOP PRIORITY)**: The final image must contain ONLY the jewelry pieces visible in the reference images.
+       - Do NOT invent new pieces (e.g. do not add earrings if only a necklace is provided).
+       - Do NOT modify the design of the existing jewelry.
+       - If one ring is provided, the model wears ONE ring.
+    2. **Subject**: ALWAYS a ${ethnicityPrompt} (age 20-30).
+    3. **NO FAKE EFFECTS**: Strictly FORBID "sparkles", "glitter particles", "magical glow". Natural light reflection only.
+    4. **Realism**: Use photography keywords (Hasselblad X2D 100C, Macro Lens 120mm, f/2.8).
+    5. **Vibe**: Old money, elegant, classy, expensive, feminine.
+
+    Output: A single, dense, highly descriptive English prompt. No introductions.`;
+  }
+  return llmSystemInstruction;
+};

package/src/prompt/tiredGirlPrompt.ts

@@ -0,0 +1,35 @@
+import { Option } from "../types.js";
+import { TIRED_GIRL_STYLE_MAP, TIRED_GIRL_STYLES } from "../config/tiredGirl.js";
+
+export const resolveTiredGirlStyles = (styleIds?: string[], quantity: number = 1): Option[] => {
+  if (styleIds && styleIds.length > 0) {
+    const resolved = styleIds
+      .map((id) => TIRED_GIRL_STYLE_MAP.get(id))
+      .filter((style): style is Option => !!style);
+    if (resolved.length > 0) return resolved;
+  }
+
+  // Default cycling through predefined styles
+  const styles: Option[] = [];
+  for (let i = 0; i < quantity; i += 1) {
+    styles.push(TIRED_GIRL_STYLES[i % TIRED_GIRL_STYLES.length]);
+  }
+  return styles;
+};
+
+export const buildTiredGirlPrompt = (style: Option, hasMuse: boolean): string => {
+  return `You are a world-renowned fashion photographer.
+Your task is to write a prompt for an AI image generator to create a photorealistic portrait of a model in a "before" look.
+
+CRITICAL GUIDELINES:
+1. JEWELRY REMOVAL: The final image must contain NO jewelry whatsoever (no rings, earrings, necklaces, bracelets, watches).
+   - If jewelry appears in reference images, REMOVE it.
+2. IDENTITY CONSISTENCY: The model must match the reference images exactly (same face, features, skin tone).
+${hasMuse ? "3. The reference images are of the same model (Muse). Use them to preserve identity." : "3. Use the reference image to preserve identity."}
+4. STYLE: ${style.value}
+5. WARDROBE: casual, at-home, or relaxed styling (if not explicitly specified in style).
+6. LIGHTING: naturalistic, soft, real-world light.
+7. REALISM: no stylized effects, no glamour retouching.
+
+OUTPUT: A single, dense prompt describing the scene. Do not include any jewelry.`;
+};

package/src/storage/files.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const ensureDir = async (dir: string): Promise<void> => {
+  await fs.mkdir(dir, { recursive: true });
+};
+
+export const readFileAsBase64 = async (filePath: string): Promise<{ data: string; mimeType: string }> => {
+  const buffer = await fs.readFile(filePath);
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeType = ext === ".png" ? "image/png" : ext === ".webp" ? "image/webp" : "image/jpeg";
+  return { data: buffer.toString("base64"), mimeType };
+};
+
+export const readImageAsPart = async (filePath: string): Promise<{ inlineData: { mimeType: string; data: string } }> => {
+  const { data, mimeType } = await readFileAsBase64(filePath);
+  return { inlineData: { data, mimeType } };
+};
+
+export const saveBase64Image = async (base64DataUrl: string, outputPath: string): Promise<void> => {
+  const base64 = base64DataUrl.includes(",") ? base64DataUrl.split(",")[1] : base64DataUrl;
+  const buffer = Buffer.from(base64, "base64");
+  await ensureDir(path.dirname(outputPath));
+  await fs.writeFile(outputPath, buffer);
+};
+
+export const saveBinary = async (bytes: Uint8Array, outputPath: string): Promise<void> => {
+  await ensureDir(path.dirname(outputPath));
+  await fs.writeFile(outputPath, Buffer.from(bytes));
+};
+
+export const writeJson = async (outputPath: string, payload: unknown): Promise<void> => {
+  await ensureDir(path.dirname(outputPath));
+  await fs.writeFile(outputPath, JSON.stringify(payload, null, 2));
+};
+
+export const resolveOutputDir = (baseDir: string, subdir: string): string => {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(baseDir, subdir, stamp);
+};
+

package/src/storage/museStore.ts

@@ -0,0 +1,31 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { MuseRecord } from "../types.js";
+
+const museIndexPath = (baseDir: string) => path.join(baseDir, "muses.json");
+
+export const loadMuses = async (baseDir: string): Promise<MuseRecord[]> => {
+  try {
+    const raw = await fs.readFile(museIndexPath(baseDir), "utf-8");
+    return JSON.parse(raw) as MuseRecord[];
+  } catch {
+    return [];
+  }
+};
+
+export const saveMuses = async (baseDir: string, muses: MuseRecord[]): Promise<void> => {
+  await fs.mkdir(baseDir, { recursive: true });
+  await fs.writeFile(museIndexPath(baseDir), JSON.stringify(muses, null, 2));
+};
+
+export const addMuse = async (baseDir: string, muse: MuseRecord): Promise<void> => {
+  const muses = await loadMuses(baseDir);
+  muses.push(muse);
+  await saveMuses(baseDir, muses);
+};
+
+export const getMuseById = async (baseDir: string, id: string): Promise<MuseRecord | undefined> => {
+  const muses = await loadMuses(baseDir);
+  return muses.find((m) => m.id === id);
+};
+