studio-lumiere-cli 0.1.0

package/.agents/skills/generate-images/SKILL.md

@@ -0,0 +1,667 @@
+---
+name: generate-images
+description: End-to-end guide to generate images with local-lumiere SDK/CLI; use for image generation workflows and parameter reference.
+---
+
+# Skill: Generate Images (local-lumiere)
+
+This document is a complete, end-to-end guide for an AI agent to generate images using the **local-lumiere** SDK/CLI. It is designed to be consumed as a standalone skill: read this file, then follow the steps exactly. It covers **every function**, **every parameter**, and **all configuration points** involved in image generation.
+
+---
+
+## Quick Start (60 seconds)
+
+1) Ensure `GEMINI_API_KEY` is set in your environment.
+2) Build the project:
+
+```
+npm install
+npm run build
+```
+
+3) Generate an image via CLI:
+
+```
+node dist/cli.js generate \
+  --images ./inputs/ring.jpg \
+  --template hand_model \
+  --detail nail_nude \
+  --ethnicity mena \
+  --skin-tone medium \
+  --hair-color brunette \
+  --background cream_silk \
+  --background-type studio \
+  --vibe clean \
+  --resolution portrait \
+  --quantity 1
+```
+
+4) Find output files under `outputs/generations/<timestamp>/`.
+
+---
+
+## 0) Purpose
+
+The goal is to programmatically generate high-end jewelry imagery locally, mirroring the Studio Lumiere app flow:
+
+- Provide input jewelry images
+- Choose a template + template options
+- Pick model/style settings (ethnicity, skin tone, hair, background, vibe, resolution, occasion)
+- Optionally use a Muse (consistent model reference)
+- Optionally generate multiple outputs in one run
+- Save outputs locally + log full metadata
+
+This skill focuses specifically on **image generation** (not refine/upscale/video/muse creation except where Muse references are used in generation).
+
+---
+
+## 1) Where the Image Generation API Lives
+
+**SDK entrypoint**: `src/index.ts`
+
+- `generateImages` (primary API)
+- `TEMPLATES`, `ETHNICITIES`, `SKIN_TONES`, `HAIR_COLORS`, `BACKGROUNDS`, `BACKGROUND_TYPES`, `VIBES`, `RESOLUTIONS`, `OCCASIONS` (config lists)
+
+**Pipeline implementation**: `src/pipelines/generateImages.ts`
+
+**Prompt building**: `src/prompt/buildPrompt.ts`
+
+**Gemini client wrapper**: `src/clients/geminiClient.ts`
+
+**Option resolution**: `src/pipelines/resolve.ts`
+
+**File I/O**: `src/storage/files.ts`
+
+**Muse lookup**: `src/storage/museStore.ts`
+
+---
+
+## 2) Required Environment and Configuration
+
+### 2.1 Environment Variables
+
+- `GEMINI_API_KEY` (required)
+  - Used by `GeminiClient` to authenticate to Gemini APIs.
+
+- `LUMIERE_OUTPUT_DIR` (optional)
+  - Default output directory for all generated assets.
+  - Defaults to `outputs` if not set.
+
+### 2.2 Runtime Config Object
+
+All SDK functions expect a `LumiereConfig` object:
+
+```ts
+export interface LumiereConfig {
+  apiKey: string;        // required
+  outputDir: string;     // required (can be read from env)
+  models?: {
+    prompt?: string;     // Gemini text model
+    image?: string;      // Gemini image model
+    video?: string;      // Gemini video model
+  };
+  retry?: {
+    maxRetries?: number; // default: 3
+    baseDelayMs?: number;// default: 1500
+    maxDelayMs?: number; // default: 12000
+  };
+}
+```
+
+Defaults if omitted:
+
+- `models.prompt`: `gemini-3-flash-preview`
+- `models.image`: `gemini-3-pro-image-preview`
+- `models.video`: `veo-3.1-generate-preview` (not used for images)
+- `retry.maxRetries`: 3
+- `retry.baseDelayMs`: 1500
+- `retry.maxDelayMs`: 12000
+
+### 2.3 Output Directory Structure
+
+`generateImages()` creates a timestamped folder under `outputDir`:
+
+```
+outputs/
+  generations/
+    2026-02-11T19-40-12-123Z/
+      image_1.png
+      image_2.png
+      generation.json
+```
+
+The timestamp is generated in `resolveOutputDir()` in `src/storage/files.ts`.
+
+---
+
+## 3) Primary Function: generateImages
+
+### 3.1 Function Signature
+
+```ts
+export const generateImages = async (
+  config: LumiereConfig,
+  request: GenerationRequest
+): Promise<GenerationResult>
+```
+
+### 3.2 Request Object: GenerationRequest
+
+```ts
+export interface GenerationRequest {
+  inputImages: string[];         // Required. File paths to local jewelry images.
+  quantity?: number;             // Optional. Number of images to generate. Default: 1.
+  selections: GenerationSelections; // Required. All template/style choices.
+  styleHint?: string;            // Optional. Extra pose/angle guidance.
+  museId?: string;               // Optional. ID of a stored Muse.
+  museImagePaths?: string[];     // Optional. Direct Muse image paths.
+  outputDir?: string;            // Optional. Override config.outputDir.
+  enhancePrompt?: boolean;       // Optional. Default true. Uses LLM prompt enhancement.
+}
+```
+
+### 3.3 Response Object: GenerationResult
+
+```ts
+export interface GenerationResult {
+  prompt: string;           // Base prompt (pre-enhancement)
+  enhancedPrompt?: string;  // Final prompt after enhancement
+  outputImages: string[];   // Paths of saved output images
+  logPath: string;          // Path to generation.json
+}
+```
+
+---
+
+## 4) GenerationSelections (All Parameters)
+
+The **selections** object controls all creative settings. All IDs must match configured options.
+
+```ts
+export interface GenerationSelections {
+  templateId: string;        // Required: template key
+  detailId?: string;         // Primary template option
+  secondaryDetailId?: string;// Secondary template option
+  tertiaryDetailId?: string; // Tertiary template option
+  ethnicityId?: string;      // Model ethnicity
+  skinToneId?: string;       // Model skin tone
+  hairColorId?: string;      // Model hair color
+  backgroundId?: string;     // Background palette
+  backgroundTypeId?: string; // Background environment
+  vibeId?: string;           // Lighting & mood
+  resolutionId?: string;     // Aspect ratio preset
+  occasionId?: string;       // Optional theme
+}
+```
+
+**Every field is optional except `templateId`.**
+
+If a field is not provided, the pipeline may:
+- Omit that parameter from the prompt
+- Fall back to a safe default (e.g., `resolutionId` defaults to `portrait`)
+
+---
+
+## 5) Templates (All Available IDs)
+
+Templates are defined in `src/config/templates.ts` and resolved by `TEMPLATE_MAP`.
+
+### 5.1 Template IDs
+
+- `hand_model`
+- `neck_model`
+- `ear_model`
+- `flatlay_creative`
+- `floating_minimal`
+- `half_body_muse`
+- `museum_exhibit`
+- `romantic_mood`
+- `romance_proposal`
+
+Each template includes:
+
+```ts
+interface Template {
+  id: string;
+  name: string;
+  description: string;
+  basePrompt: string;
+  customizationLabel?: string;
+  customizationOptions?: Option[];
+  secondaryCustomizationLabel?: string;
+  secondaryCustomizationOptions?: Option[];
+  tertiaryCustomizationLabel?: string;
+  tertiaryCustomizationOptions?: Option[];
+  museEnabled?: boolean;
+  videoEnabled?: boolean;
+}
+```
+
+### 5.2 Template Options (Primary/Secondary/Tertiary)
+
+Each template can define up to 3 customization groups:
+
+- **Primary** => `detailId`
+- **Secondary** => `secondaryDetailId`
+- **Tertiary** => `tertiaryDetailId`
+
+The option lists are defined per template in `src/config/templates.ts`.
+
+If an ID is passed but not found in the template’s option list, the resolver will still accept it by mapping it to a placeholder `{ id, name, value }`.
+
+---
+
+## 6) Global Style Options (All Config Lists)
+
+Defined in `src/config/options.ts`.
+
+### 6.1 Ethnicities (`ETHNICITIES`)
+
+```ts
+id: "none" | "mena" | "south_asian" | "east_asian" | "black" | "white" | "latina"
+```
+
+Used for prompt substitution and may expand to specific regions via `ETHNICITY_REGIONS`.
+
+### 6.2 Skin Tones (`SKIN_TONES`)
+
+```ts
+id: "porcelain" | "fair" | "medium" | "tan" | "deep"
+```
+
+### 6.3 Hair Colors (`HAIR_COLORS`)
+
+```ts
+id: "black" | "brunette" | "blonde" | "red" | "salt_pepper"
+```
+
+### 6.4 Background Palettes (`BACKGROUNDS`)
+
+```ts
+id: "cream_silk" | "midnight_velvet" | "white_marble" | "warm_sand" | "charcoal"
+```
+
+### 6.5 Background Types (`BACKGROUND_TYPES`)
+
+```ts
+id: "studio" | "interior" | "outdoor" | "macro"
+```
+
+### 6.6 Vibes (`VIBES`)
+
+```ts
+id: "golden" | "moody" | "clean" | "romantic"
+```
+
+### 6.7 Resolutions (`RESOLUTIONS`)
+
+```ts
+id: "square" | "portrait" | "story" | "landscape"
+```
+
+Maps to aspect ratio values:
+
+- square => `1:1`
+- portrait => `3:4`
+- story => `9:16`
+- landscape => `16:9`
+
+### 6.8 Occasions (`OCCASIONS`)
+
+Example IDs:
+
+- `wedding`
+- `eid`
+- `valentines`
+
+Each occasion injects a rich scene description into the prompt if selected.
+
+---
+
+## 7) Prompt Construction (All Inputs and Behavior)
+
+Prompt construction happens in `buildLumierePrompt()` in `src/prompt/buildPrompt.ts`.
+
+### 7.1 Inputs
+
+```ts
+interface PromptInputs {
+  template: Template;
+  detail?: Option;
+  secondaryDetail?: Option;
+  tertiaryDetail?: Option;
+  ethnicity?: Option;
+  skinTone?: Option;
+  hairColor?: Option;
+  background?: Option;
+  backgroundType?: Option;
+  vibe?: Option;
+  resolution: Resolution;
+  occasion?: OccasionTheme;
+  imageCount: number;
+  isVariation?: boolean;
+  styleHint?: string;
+  hasMuse?: boolean;
+}
+```
+
+### 7.2 Core Prompt Rules
+
+- Replaces `[ETHNICITY]` and `[HAIR_COLOR]` placeholders in template base prompts.
+- Enforces jewelry fidelity (no extra jewelry, no fake sparkles).
+- Optionally adds occasion scene blocks.
+- Adds model specifications from detail/secondary/tertiary selections.
+- Applies environment settings if no occasion is chosen.
+- Adds technical requirements, aspect ratio, and strict prohibitions.
+- If `styleHint` is provided, it appends “STYLE & POSE DIRECTION.”
+- If `isVariation` true, it appends an explicit “variation instruction.”
+
+### 7.3 Skip Logic for Ethnicity
+
+Ethnicity is **not** included when:
+
+- A Muse is being used (`hasMuse` true), OR
+- Template is one of: `hand_model`, `flatlay_creative`, `floating_minimal`, `museum_exhibit`, `romantic_mood`
+
+### 7.4 System Instruction
+
+`buildSystemInstruction(template, ethnicity)` generates an additional system-style block to guide the LLM for each template.
+
+This is combined with the base prompt if `enhancePrompt` is enabled:
+
+```
+final = systemInstruction + "\n\n" + basePrompt
+```
+
+---
+
+## 8) Prompt Enhancement (Gemini Text Model)
+
+If `enhancePrompt` is `true` (default), the pipeline calls:
+
+```ts
+GeminiClient.generateText(promptInput)
+```
+
+- `promptInput` = system instruction + base prompt
+- The result becomes `enhancedPrompt`
+
+If disabled, `enhancedPrompt` is the same as `basePrompt`.
+
+---
+
+## 9) Muse Handling in Generation
+
+There are **two ways** to supply Muse references:
+
+1) **Direct image paths**: `museImagePaths` (preferred for ad-hoc runs)
+2) **Stored Muse**: `museId`, loaded from `muses.json`
+
+### 9.1 Muse Image Parts
+
+If Muse images are provided, they are appended to the image parts array and the final prompt is extended with strict Muse consistency language.
+
+Muse logic happens in `generateImages.ts`:
+
+```ts
+if (museImageParts) {
+  finalPrompt += "Muse consistency requirement...";
+}
+```
+
+Muse images are passed **after** jewelry images in the `parts` array:
+
+```
+parts = [ { text: finalPrompt }, ...jewelryImages, ...museImages ]
+```
+
+---
+
+## 10) Gemini Image Generation Call
+
+Image generation is performed by:
+
+```ts
+GeminiClient.generateImage({
+  parts,
+  aspectRatio,
+  imageSize: "2K"
+})
+```
+
+### 10.1 parts
+
+`parts` is an array of:
+
+```ts
+{ text?: string; inlineData?: { mimeType: string; data: string } }
+```
+
+The first part is always the prompt (text). Subsequent parts are inline base64 images.
+
+### 10.2 Aspect Ratio
+
+Passed from `Resolution.aspectRatio`, resolved via `resolveResolution()`.
+
+### 10.3 Image Size
+
+Hard-coded to `2K` in the image generation pipeline.
+
+---
+
+## 11) Upscaling an Image
+
+While this skill focuses on generation, upscaling is a common follow-up step and is supported locally via `upscaleImage`.
+
+### 11.1 Function Signature
+
+```ts
+export const upscaleImage = async (
+  config: LumiereConfig,
+  request: UpscaleRequest
+): Promise<string>
+```
+
+### 11.2 Request Object: UpscaleRequest
+
+```ts
+export interface UpscaleRequest {
+  inputImage: string; // Required. Path to a local image file.
+  scale?: number;     // Optional. Scale factor (default: 2).
+  outputDir?: string; // Optional. Override config.outputDir.
+}
+```
+
+### 11.3 Behavior
+
+- Builds an upscaling prompt: "Upscale this image to Nx resolution..."
+- Uses Gemini image model via `GeminiClient.generateImage()`
+- Saves output as `upscaled.png` in `outputs/upscales/<timestamp>/`
+- Writes `upscale.json` log with input path, scale, output path
+
+### 11.4 SDK Example
+
+```ts
+import { upscaleImage } from "./dist/index.js";
+
+const outputPath = await upscaleImage(
+  { apiKey, outputDir: "outputs" },
+  { inputImage: "./outputs/generations/.../image_1.png", scale: 2 }
+);
+
+console.log(outputPath);
+```
+
+### 11.5 CLI Example
+
+```
+node dist/cli.js upscale --image ./outputs/image.png --scale 2
+```
+
+---
+
+## 12) CLI Usage (Full Parameters)
+
+The CLI is implemented in `src/cli.ts` and compiled to `dist/cli.js`.
+
+### 12.1 Generate Command
+
+```
+node dist/cli.js generate \
+  --images ./inputs/ring.jpg,./inputs/bracelet.jpg \
+  --template hand_model \
+  --detail nail_nude \
+  --secondary-detail nail_red \
+  --tertiary-detail makeup_soft \
+  --ethnicity mena \
+  --skin-tone medium \
+  --hair-color brunette \
+  --background cream_silk \
+  --background-type studio \
+  --vibe clean \
+  --resolution portrait \
+  --occasion wedding \
+  --quantity 2 \
+  --muse-id muse_1700000000000 \
+  --muse-images ./muses/m1.png,./muses/m2.png,./muses/m3.png
+```
+
+### 12.2 Important CLI Flags
+
+- `--images`: **required**. Comma-separated list.
+- `--template`: **required**. Must match one of `TEMPLATES`.
+- `--detail`: optional
+- `--secondary-detail`: optional
+- `--tertiary-detail`: optional
+- `--ethnicity`: optional
+- `--skin-tone`: optional
+- `--hair-color`: optional
+- `--background`: optional
+- `--background-type`: optional
+- `--vibe`: optional
+- `--resolution`: optional
+- `--occasion`: optional
+- `--quantity`: optional (default 1)
+- `--muse-id`: optional
+- `--muse-images`: optional (comma list)
+- `--no-enhance`: disable prompt enhancement
+
+`--no-enhance` flips `enhancePrompt=false`.
+
+---
+
+## 13) Function Call Example (SDK)
+
+```ts
+import { generateImages } from "./dist/index.js";
+
+const result = await generateImages(
+  {
+    apiKey: process.env.GEMINI_API_KEY!,
+    outputDir: "outputs",
+    models: {
+      prompt: "gemini-3-flash-preview",
+      image: "gemini-3-pro-image-preview"
+    },
+    retry: {
+      maxRetries: 3,
+      baseDelayMs: 1500,
+      maxDelayMs: 12000
+    }
+  },
+  {
+    inputImages: ["./inputs/ring.jpg"],
+    quantity: 2,
+    selections: {
+      templateId: "hand_model",
+      detailId: "nail_nude",
+      ethnicityId: "mena",
+      skinToneId: "medium",
+      hairColorId: "brunette",
+      backgroundId: "cream_silk",
+      backgroundTypeId: "studio",
+      vibeId: "clean",
+      resolutionId: "portrait",
+      occasionId: "wedding"
+    },
+    enhancePrompt: true
+  }
+);
+
+console.log(result.outputImages);
+```
+
+---
+
+## 14) Error Handling and Retries
+
+All Gemini calls use a retry wrapper:
+
+```ts
+retry: {
+  maxRetries: 3,
+  baseDelayMs: 1500,
+  maxDelayMs: 12000
+}
+```
+
+Retryable error detection looks for:
+- HTTP 429 / 503
+- “overloaded”, “unavailable”, “timeout” text
+
+If all retries fail, the error is thrown as-is.
+
+---
+
+## 15) Extending or Modifying the Skill
+
+If you need more templates/options:
+
+- Add them to `src/config/templates.ts` or `src/config/options.ts`.
+- Ensure your new IDs are used in `GenerationSelections`.
+- The resolver will accept unknown IDs but won’t provide canonical names/values.
+
+If you want a different image model or output size:
+
+- Change defaults in `GeminiClient` or override `config.models.image`.
+- Modify `generateImages.ts` to change `imageSize` from `2K` to `4K`.
+
+---
+
+## 16) Quick Checklist for an AI Agent
+
+1) Ensure `GEMINI_API_KEY` is set.
+2) Choose template ID from `TEMPLATES`.
+3) Pick detail IDs based on that template’s options.
+4) Decide optional style params (ethnicity, skin tone, hair, background, vibe, resolution, occasion).
+5) Collect local input image paths.
+6) Optionally provide Muse images or a stored `museId`.
+7) Call `generateImages(config, request)`.
+8) Read output paths and logs from the result.
+
+---
+
+## 17) Related Files (For Reference)
+
+- `src/pipelines/generateImages.ts`
+- `src/prompt/buildPrompt.ts`
+- `src/clients/geminiClient.ts`
+- `src/pipelines/resolve.ts`
+- `src/config/templates.ts`
+- `src/config/options.ts`
+- `src/storage/files.ts`
+- `src/storage/museStore.ts`
+- `src/cli.ts`
+
+End of skill.
+
+## Related Skills
+
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\generate-video.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\refine-images.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\muse-management.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\tired-girl.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\image-grid.md`
+- `C:\\Users\\karim\\Documents\\local-lumiere\\.agents\\skills\\config-troubleshooting.md`
+