studio-lumiere-cli 0.1.0 → 0.1.2

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

@@ -1,28 +1,25 @@
 ---
 name: generate-images
-description: End-to-end guide to generate images with local-lumiere SDK/CLI; use for image generation workflows and parameter reference.
+description: Generate images with the Studio Lumiere CLI (npx studio-lumiere-cli); inputs, outputs, and parameters.
 ---
 
-# Skill: Generate Images (local-lumiere)
+# Skill: Generate Images (CLI)
 
-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.
+This skill covers **CLI usage only** for image generation with Studio Lumiere.
 
 ---
 
-## Quick Start (60 seconds)
+## Requirements
 
-1) Ensure `GEMINI_API_KEY` is set in your environment.
-2) Build the project:
+- Set `GEMINI_API_KEY` in your environment.
+- Optional: set `LUMIERE_OUTPUT_DIR` to change the default output folder (defaults to `outputs`).
 
-```
-npm install
-npm run build
-```
+---
 
-3) Generate an image via CLI:
+## Quick Start
 
-```
-node dist/cli.js generate \
+```bash
+npx studio-lumiere-cli generate \
   --images ./inputs/ring.jpg \
   --template hand_model \
   --detail nail_nude \
@@ -36,632 +33,89 @@ node dist/cli.js generate \
   --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`
+## Inputs
 
-If disabled, `enhancedPrompt` is the same as `basePrompt`.
+- `--images` (required): Comma-separated local file paths to jewelry images.
+- `--template` (required): Template ID.
+- Optional style/scene parameters (see below).
+- Optional Muse reference (either `--muse-id` or `--muse-images`).
 
 ---
 
-## 9) Muse Handling in Generation
-
-There are **two ways** to supply Muse references:
+## Outputs
 
-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 ]
-```
+- Generated images are written under:
+  - `outputs/generations/<timestamp>/` by default, or
+  - `LUMIERE_OUTPUT_DIR/generations/<timestamp>/` if configured.
+- Each run writes a `generation.json` log alongside the images.
+- The CLI prints a JSON result containing `outputImages` and `logPath`.
 
 ---
 
-## 10) Gemini Image Generation Call
-
-Image generation is performed by:
-
-```ts
-GeminiClient.generateImage({
-  parts,
-  aspectRatio,
-  imageSize: "2K"
-})
-```
-
-### 10.1 parts
+## Parameters (generate)
 
-`parts` is an array of:
+Required:
+- `--images <paths>`: Comma-separated list of input image paths.
+- `--template <id>`: Template ID.
 
-```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.
+Optional:
+- `--detail <id>`
+- `--secondary-detail <id>`
+- `--tertiary-detail <id>`
+- `--ethnicity <id>`
+- `--skin-tone <id>`
+- `--hair-color <id>`
+- `--background <id>`
+- `--background-type <id>`
+- `--vibe <id>`
+- `--resolution <id>`
+- `--occasion <id>`
+- `--quantity <n>`: Number of outputs (default `1`).
+- `--muse-id <id>`: Use a stored Muse.
+- `--muse-images <paths>`: Comma-separated Muse image paths.
+- `--no-enhance`: Disable prompt enhancement.
 
 ---
 
-## 11) Upscaling an Image
-
-While this skill focuses on generation, upscaling is a common follow-up step and is supported locally via `upscaleImage`.
+## Find Valid IDs (templates/options)
 
-### 11.1 Function Signature
+Use the `list` command to see allowed IDs:
 
-```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
+```bash
+npx studio-lumiere-cli list templates
+npx studio-lumiere-cli list ethnicities
+npx studio-lumiere-cli list skin-tones
+npx studio-lumiere-cli list hair-colors
+npx studio-lumiere-cli list backgrounds
+npx studio-lumiere-cli list background-types
+npx studio-lumiere-cli list vibes
+npx studio-lumiere-cli list resolutions
+npx studio-lumiere-cli list occasions
 ```
 
 ---
 
-## 12) CLI Usage (Full Parameters)
-
-The CLI is implemented in `src/cli.ts` and compiled to `dist/cli.js`.
-
-### 12.1 Generate Command
+## Example (multiple images + muse)
 
-```
-node dist/cli.js generate \
+```bash
+npx studio-lumiere-cli 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
+  --muse-images ./muses/m1.png,./muses/m2.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`
-
+- `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`