studio-lumiere-cli 0.1.4 → 0.1.6

package/README.md

@@ -1,96 +1,532 @@
-# local-lumiere
+# Studio Lumiere CLI
 
-Local SDK + CLI for Studio Lumiere generation flows. Runs entirely on your machine and talks directly to Gemini APIs.
+Local SDK + CLI for AI-powered jewelry product photography. Generate editorial-quality images, videos, and compositions from reference jewelry photos.
+
+```bash
+npx studio-lumiere-cli <command> [options]
+```
 
 ## Setup
 
-1) Install dependencies
+1. Install dependencies
 
 ```
 npm install
 ```
 
-2) Create `.env`
+2. Create `.env`
 
 ```
 GEMINI_API_KEY=your_key_here
 LUMIERE_OUTPUT_DIR=outputs
 ```
 
-## CLI Usage
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| [`generate`](#generate) | Generate styled jewelry product images |
+| [`refine`](#refine) | Apply refinement instructions to an existing image |
+| [`upscale`](#upscale) | Upscale an image to higher resolution |
+| [`muse`](#muse) | Create a consistent character reference ("Muse") |
+| [`video`](#video) | Generate video from a text prompt |
+| [`tired-girl`](#tired-girl) | Generate "before" / casual aesthetic images |
+| [`annotate`](#annotate) | Overlay text on an image |
+| [`grid`](#grid) | Combine multiple images into a grid layout |
+| [`list`](#list) | List available templates, backgrounds, vibes, etc. |
 
-List options:
+---
 
+## generate
+
+Generate styled jewelry product images using AI.
+
+```bash
+lumiere generate --images <paths> --template <id> [options]
 ```
-node dist/cli.js list templates
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--images <paths>` | Comma-separated input image paths |
+| `--template <id>` | Template ID (see [Templates](#templates)) |
+
+### Customization
+
+| Flag | Description |
+|------|-------------|
+| `--detail <id>` | Primary customization (template-specific) |
+| `--secondary-detail <id>` | Secondary customization |
+| `--tertiary-detail <id>` | Tertiary customization |
+| `--ethnicity <id>` | Model ethnicity |
+| `--skin-tone <id>` | Model skin tone |
+| `--hair-color <id>` | Model hair color |
+| `--background <id>` | Background color/texture |
+| `--background-type <id>` | Background type (studio, interior, exterior, texture) |
+| `--vibe <id>` | Photography mood/style |
+| `--resolution <id>` | Output aspect ratio (default: `portrait`) |
+| `--occasion <id>` | Special occasion theme |
+
+### Generation
+
+| Flag | Description |
+|------|-------------|
+| `--quantity <n>` | Number of images to generate (default: `1`) |
+| `--muse-id <id>` | Muse ID for consistent model appearance |
+| `--muse-images <paths>` | Comma-separated Muse reference image paths |
+| `--no-enhance` | Skip LLM prompt enhancement |
+
+### Example
+
+```bash
+lumiere generate \
+  --images "ring.jpg" \
+  --template hand_model \
+  --detail nail_red \
+  --background velvet_black \
+  --vibe golden_hour \
+  --quantity 4
 ```
 
-Generate images:
+---
+
+## refine
 
+Apply refinement instructions to an existing generated image.
+
+```bash
+lumiere refine --image <path> --instruction <text> [options]
 ```
-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 2
+
+| Flag | Description |
+|------|-------------|
+| `--image <path>` | **(required)** Path to image to refine |
+| `--instruction <text>` | **(required)** Refinement instruction |
+| `--size <percent>` | Resize jewelry to given percentage (e.g. `80` = smaller, `120` = larger) |
+
+```bash
+lumiere refine --image "output.png" --instruction "make the background warmer"
+lumiere refine --image "output.png" --instruction "adjust jewelry" --size 80
 ```
 
-Refine:
+---
 
+## upscale
+
+Upscale an image to higher resolution.
+
+```bash
+lumiere upscale --image <path> [--scale <n>]
 ```
-node dist/cli.js refine --image ./outputs/image.png --instruction "Make the ring slightly larger"
+
+| Flag | Description |
+|------|-------------|
+| `--image <path>` | **(required)** Path to image |
+| `--scale <n>` | Scale factor (default: `2`) |
+
+---
+
+## muse
+
+Create a Muse (consistent character reference) from a source image. Used with the `half_body_muse` template for identity-consistent generations.
+
+```bash
+lumiere muse --name <name> --source <path> [--variations <n>]
 ```
 
-Upscale:
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | **(required)** Name for the Muse |
+| `--source <path>` | **(required)** Path to source image |
+| `--variations <n>` | Number of variations to generate (default: `3`) |
 
+```bash
+lumiere muse --name "Sarah" --source "reference.jpg"
+lumiere generate --images "necklace.jpg" --template half_body_muse --muse-id sarah
 ```
-node dist/cli.js upscale --image ./outputs/image.png --scale 2
+
+---
+
+## video
+
+Generate a short video from a text prompt.
+
+```bash
+lumiere video --prompt <text> [options]
 ```
 
-Create a Muse:
+| Flag | Description |
+|------|-------------|
+| `--prompt <text>` | **(required)** Video description |
+| `--aspect <ratio>` | Aspect ratio (`1:1`, `3:4`, `9:16`, `16:9`) |
+| `--duration <seconds>` | Duration in seconds |
 
+Video-enabled templates: `hand_model`, `neck_model`, `ear_model`, `flatlay_creative`, `floating_minimal`, `half_body_muse`.
+
+---
+
+## tired-girl
+
+Generate "tired girl" / "before" aesthetic images showing a model in casual, un-styled looks (no jewelry).
+
+```bash
+lumiere tired-girl [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--muse-id <id>` | Muse ID for identity reference |
+| `--image <path>` | Single reference image (if no Muse) |
+| `--styles <ids>` | Comma-separated style IDs |
+| `--quantity <n>` | Number of images (default: `1`) |
+
+### Available styles
+
+| ID | Description |
+|----|-------------|
+| `tired` | Slightly tired, soft under-eye shadows, relaxed expression |
+| `morning` | Freshly awake, morning light, sleepy energy |
+| `no_makeup` | Completely bare faced |
+| `crazy_hair` | Messy, unstyled wild hair |
+| `pyjama` | Cozy pajamas or loungewear |
+
+```bash
+lumiere tired-girl --muse-id sarah --styles "tired,no_makeup" --quantity 2
+```
+
+---
+
+## annotate
+
+Overlay text on an image with customizable styling.
+
+```bash
+lumiere annotate --input <path> --output <path> --text <text> [options]
+```
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--input <path>` | Input image path |
+| `--output <path>` | Output image path |
+| `--text <text>` | Text to overlay |
+
+### Text styling
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--font <name>` | `Poppins` | Font family |
+| `--size <px>` | auto | Font size in pixels |
+| `--weight <n>` | `700` | Font weight |
+| `--color <hex>` | `#FFFFFF` | Text color |
+| `--stroke-color <value>` | `rgba(0,0,0,0.6)` | Text outline color |
+| `--stroke-width <px>` | `fontSize * 0.08` | Text outline width |
+
+### Banner
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--banner` | off | Enable semi-transparent banner behind text |
+| `--banner-color <value>` | `rgba(0,0,0,0.45)` | Banner color |
+| `--banner-padding <px>` | `fontSize * 0.6` | Banner padding |
+| `--banner-radius <px>` | `fontSize * 0.4` | Banner corner radius |
+
+### Position
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--position <pos>` | `bottom-center` | One of: `top-center`, `top-left`, `top-right`, `bottom-center`, `bottom-center-high`, `bottom-left`, `bottom-right`, `center` |
+| `--padding <px>` | auto | Padding from edges |
+| `--max-width <ratio>` | auto | Max text width as ratio of image width (0-1) |
+
+```bash
+lumiere annotate \
+  --input "image.jpg" \
+  --output "branded.jpg" \
+  --text "New Collection" \
+  --position bottom-center \
+  --banner \
+  --size 48
 ```
-node dist/cli.js muse --name "Editorial Muse" --source ./inputs/muse_source.jpg --variations 3
+
+---
+
+## grid
+
+Combine multiple images into a grid layout.
+
+```bash
+lumiere grid --inputs <paths> --output <path> [options]
 ```
 
-Generate video:
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--inputs <paths>` | | **(required)** Comma-separated image paths |
+| `--output <path>` | | **(required)** Output image path |
+| `--columns <n>` | `2` | Number of columns |
+| `--rows <n>` | `2` | Number of rows |
+| `--padding <px>` | `20` | Padding between tiles |
+| `--background <hex>` | `#000000` | Background color |
+| `--tile-width <px>` | auto | Fixed tile width |
+| `--tile-height <px>` | auto | Fixed tile height |
 
+```bash
+lumiere grid \
+  --inputs "img1.jpg,img2.jpg,img3.jpg,img4.jpg" \
+  --output "grid.jpg" \
+  --columns 2 --rows 2 \
+  --padding 10 --background "#FFFFFF"
 ```
-node dist/cli.js video --prompt "Cinematic head turn showing earrings" --aspect 9:16 --duration 5
+
+---
+
+## list
+
+List available options for any category. Output is JSON.
+
+```bash
+lumiere list <type>
 ```
 
+| Type | Description |
+|------|-------------|
+| `templates` | All templates with their customization options |
+| `ethnicities` | Model ethnicity options |
+| `skin-tones` | Skin tone options |
+| `hair-colors` | Hair color options |
+| `backgrounds` | Background color/texture options |
+| `background-types` | Background type options |
+| `vibes` | Photography mood options |
+| `resolutions` | Aspect ratio options |
+| `occasions` | Special occasion themes |
+
+---
+
+## Templates
+
+### `hand_model` -- Hand Model
+
+Close-up of a model's hand, wrist, and forearm. Perfect for rings and bracelets.
+
+| Customization | Options |
+|---------------|---------|
+| **Nail Polish** (`--detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+
+---
+
+### `neck_model` -- Neckline Portrait
+
+Waist-up portrait focusing on the neck and collarbone. Ideal for necklaces and pendants.
+
+| Customization | Options |
+|---------------|---------|
+| **Wardrobe** (`--detail`) | `wear_skin` Bare Skin, `wear_silk` White Silk Shirt, `wear_black` Black Turtleneck, `wear_gown` Evening Gown, `wear_kaftan` Modern Kaftan |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+
+---
+
+### `ear_model` -- Ear Detail
+
+Intimate side profile shot. Best for earrings.
+
+| Customization | Options |
+|---------------|---------|
+| **Hairstyle** (`--detail`) | `hair_tucked` Tucked Behind Ear, `hair_updo` Elegant Updo, `hair_waves` Loose Waves, `hair_sleek` Sleek & Straight |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+
+---
+
+### `flatlay_creative` -- Creative Flatlay
+
+Artistic still-life composition on a surface. No model. Great for any jewelry type.
+
+| Customization | Options |
+|---------------|---------|
+| **Surface** (`--detail`) | `surf_marble` White Marble, `surf_stone` Dark Slate, `surf_velvet` Beige Velvet, `surf_wood` Aged Wood, `surf_sand` Fine Sand, `surf_pedestal` Geometric Pedestal, `surf_riser` Stone Riser |
+
+---
+
+### `floating_minimal` -- Floating Minimalist
+
+Jewelry suspended in mid-air with dramatic lighting. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Lighting** (`--detail`) | `light_soft` Soft & Diffused, `light_hard` Hard Contrast, `light_warm` Golden Glow, `light_cool` Cool Steel |
+
+---
+
+### `half_body_muse` -- The Editorial Muse
+
+Dynamic waist-up fashion shot. The only template that supports Muse (consistent model identity).
+
+| Customization | Options |
+|---------------|---------|
+| **Outfit** (`--detail`) | `outfit_blazer` Power Suit, `outfit_evening` Evening Glamour, `outfit_linen` Resort Linen, `outfit_knit` Cashmere Knit, `outfit_silk` Silk Shirt, `outfit_turtleneck` Turtleneck |
+| **Nail Polish** (`--secondary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+| **Pose** (quaternary) | `pose_winking`, `pose_grimace`, `pose_teasing`, `pose_kiss`, `pose_laughing`, `pose_pout`, `pose_peace` |
+
+---
+
+### `romance_proposal` -- Romance & Proposal
+
+Emotional engagement ring moments with a couple.
+
+| Customization | Options |
+|---------------|---------|
+| **Moment** (`--detail`) | `moment_proposal` The Proposal, `moment_said_yes` Just Said Yes, `moment_hand_in_hand` Hand in Hand, `moment_dinner` Intimate Dinner, `moment_promise` The Promise |
+| **Setting** (`--secondary-detail`) | `setting_garden` Garden, `setting_restaurant` Candlelit Restaurant, `setting_beach` Beach at Sunset, `setting_home` Cozy at Home, `setting_rooftop` Rooftop City Views, `setting_winter` Winter Snow |
+| **Nail Polish** (`--tertiary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+
+---
+
+### `museum_exhibit` -- Museum Exhibit
+
+Jewelry displayed as a priceless museum artifact. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Museum Style** (`--detail`) | `museum_classical` Classical Gallery, `museum_modern` Modern Art Museum, `museum_baroque` Baroque Palace, `museum_art_deco` Art Deco Gallery |
+| **Display Type** (`--secondary-detail`) | `display_vitrine` Glass Vitrine, `display_pedestal` Velvet Pedestal, `display_stand` Open Display, `display_wall` Wall Mount, `display_alcove` Illuminated Alcove |
+
+---
+
+### `romantic_mood` -- Romantic Mood
+
+Jewelry styled as a romantic still life with props. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Props** (`--detail`) | `prop_rose_petals` Rose Petals, `prop_candles` Candlelight, `prop_love_letter` Love Letter, `prop_silk_lace` Silk & Lace, `prop_fresh_roses` Fresh Roses, `prop_gift_box` The Gift |
+| **Mood** (`--secondary-detail`) | `mood_candlelight` Warm Candlelight, `mood_morning` Soft Morning Light, `mood_moody` Moody & Dark, `mood_golden` Golden Hour Glow, `mood_blush` Blush Pink Haze |
+
+---
+
+## Global Options
+
+### Ethnicities (`--ethnicity`)
+
+| ID | Name |
+|----|------|
+| `european` | European |
+| `moroccan` | Moroccan |
+| `middle_east` | Middle Eastern |
+| `african` | African |
+| `asian` | East Asian |
+
+### Skin Tones (`--skin-tone`)
+
+| ID | Name |
+|----|------|
+| `fair` | Porcelain |
+| `light` | Light |
+| `medium` | Tan |
+| `deep` | Deep |
+| `dark` | Ebony |
+
+### Hair Colors (`--hair-color`)
+
+| ID | Name |
+|----|------|
+| `dark` | Dark / Black |
+| `brunette` | Brunette |
+| `blonde` | Blonde |
+| `red` | Red / Auburn |
+| `grey` | Silver / Grey |
+
+### Backgrounds (`--background`)
+
+| ID | Name |
+|----|------|
+| `silk_cream` | Cream Silk |
+| `velvet_black` | Midnight Velvet |
+| `marble_white` | Carrara Marble |
+| `emerald_velvet` | Emerald Velvet |
+| `studio_grey` | Studio Grey |
+| `warm_beige` | Warm Beige |
+| `burgundy_velvet` | Burgundy Velvet |
+| `champagne_gold` | Champagne Gold |
+| `navy_sapphire` | Navy Sapphire |
+| `blush_rose` | Blush Rose |
+| `ivory_pearl` | Ivory Pearl |
+| `slate_charcoal` | Slate Charcoal |
+
+### Background Types (`--background-type`)
+
+| ID | Name |
+|----|------|
+| `studio` | Studio Flat |
+| `interior` | Luxury Interior |
+| `exterior` | Outdoors |
+| `texture` | Macro Texture |
+
+### Vibes (`--vibe`)
+
+| ID | Name |
+|----|------|
+| `golden_hour` | Golden Hour -- warm natural sunlight |
+| `moody_chic` | Moody Chic -- dramatic shadows, high contrast |
+| `clean_minimal` | Clean Minimal -- bright, airy, minimalist |
+| `romantic_soft` | Romantic -- soft focus, pastel tones |
+
+### Resolutions (`--resolution`)
+
+| ID | Aspect Ratio | Best for |
+|----|-------------|----------|
+| `square` | 1:1 | Instagram Feed |
+| `portrait` | 3:4 | Instagram Feed (vertical) |
+| `story` | 9:16 | Instagram Stories / Reels |
+| `landscape` | 16:9 | Website / Ads |
+
+### Occasions (`--occasion`)
+
+Occasions auto-configure vibe, background, and background type, and inject thematic prompt details.
+
+| ID | Name |
+|----|------|
+| `moroccan_wedding` | Moroccan Wedding |
+| `eid_fitr` | Eid al-Fitr |
+| `eid_adha` | Eid al-Adha |
+| `henna_night` | Henna Night |
+| `ramadan` | Ramadan |
+| `valentines` | Valentine's Day |
+| `mothers_day` | Mother's Day |
+| `birthday` | Birthday |
+| `anniversary` | Anniversary |
+| `graduation` | Graduation |
+| `christmas` | Christmas |
+| `new_year` | New Year |
+
+---
+
 ## SDK Usage
 
 ```ts
-import { generateImages } from "local-lumiere";
-
-const result = await generateImages({ apiKey, outputDir: "outputs" }, {
-  inputImages: ["./inputs/ring.jpg"],
-  quantity: 1,
-  selections: {
-    templateId: "hand_model",
-    detailId: "nail_nude",
-    ethnicityId: "mena",
-    skinToneId: "medium",
-    hairColorId: "brunette",
-    backgroundId: "cream_silk",
-    backgroundTypeId: "studio",
-    vibeId: "clean",
-    resolutionId: "portrait"
+import { generateImages } from "studio-lumiere-cli";
+
+const result = await generateImages(
+  { apiKey: "your-key", outputDir: "outputs" },
+  {
+    inputImages: ["./ring.jpg"],
+    quantity: 4,
+    selections: {
+      templateId: "hand_model",
+      detailId: "nail_red",
+      backgroundId: "velvet_black",
+      vibeId: "golden_hour",
+      resolutionId: "portrait",
+    },
   }
-});
+);
 ```
 
 ## Notes
 
-- The config lists are a curated subset of the full Studio Lumiere options. You can add or override options in `src/config/`.
+- Templates, backgrounds, vibes, and all shared options are synced from the main Studio Lumiere web app at build time (`npm run sync`). The CLI always matches the web app.
 - The Muse flow generates variations and stores a local `muses.json` index under your output directory.
 - Video generation uses Veo via the Gemini SDK and returns an operation name plus the video file when available.
-

package/dist/config/constants.d.ts

@@ -1,63 +1 @@
-import { Template, Option, Resolution } from '../types.js';
-export declare const DEFAULT_IMAGE_COUNT = 4;
-export declare const UPSCALE_CREDIT_COST = 5;
-export declare const REFINE_CREDIT_COST = 5;
-export declare const GENERATE_CREDIT_COST = 5;
-export declare const VIDEO_GENERATION_CREDIT_COST = 20;
-export declare const VIDEO_ENABLED_TEMPLATES: readonly ["hand_model", "neck_model", "ear_model", "flatlay_creative", "floating_minimal", "half_body_muse"];
-export type VideoEnabledTemplate = typeof VIDEO_ENABLED_TEMPLATES[number];
-export declare const isVideoEnabledTemplate: (templateId: string) => boolean;
-export declare const MUSE_ENABLED_TEMPLATES: readonly ["half_body_muse"];
-export type MuseEnabledTemplate = typeof MUSE_ENABLED_TEMPLATES[number];
-export declare const MUSE_GENERATION_CREDIT_COST = 5;
-export declare const MUSE_BATCH_SIZE = 3;
-export declare const MUSE_BATCH_CREDIT_COST: number;
-export declare const REQUIRED_MUSE_VARIATIONS = 3;
-export declare const MAX_MUSES_PER_USER = 3;
-export declare const isMuseEnabledTemplate: (templateId: string) => boolean;
-export declare const TEMPLATES: Template[];
-export declare const SKIN_TONES: Option[];
-export declare const ETHNICITY_REGIONS: Record<string, string[]>;
-export declare const ETHNICITIES: Option[];
-export declare const HAIR_COLORS: Option[];
-export declare const BACKGROUNDS: Option[];
-export declare const LUXURY_INTERIOR_POOL: string[];
-export declare const getRandomLuxuryInterior: () => string;
-export declare const BACKGROUND_TYPES: Option[];
-export declare const VIBES: Option[];
-export interface OccasionTheme {
-    id: string;
-    name: string;
-    icon: string;
-    description: string;
-    autoConfig: {
-        vibe: string;
-        background: string;
-        backgroundType: string;
-    };
-    promptDetails?: {
-        setting: string;
-        atmosphere: string;
-        colorPalette: string;
-        culturalElements: string;
-        styling: string;
-    };
-}
-export declare const OCCASIONS: OccasionTheme[];
-export declare const GENERATION_STYLE_POOL: string[];
-export declare const HAND_MODEL_STYLE_POOL: string[];
-export declare const EAR_MODEL_STYLE_POOL: string[];
-export declare const FLATLAY_STYLE_POOL: string[];
-export declare const FLOATING_STYLE_POOL: string[];
-export declare const ROMANCE_STYLE_POOL: string[];
-export declare const MUSEUM_STYLE_POOL: string[];
-export declare const ROMANTIC_MOOD_STYLE_POOL: string[];
-export declare const getStylePoolForTemplate: (templateId: string | null) => string[];
-export declare const HAND_MODEL_VIDEO_PROMPTS: string[];
-export declare const NECK_MODEL_VIDEO_PROMPTS: string[];
-export declare const EAR_MODEL_VIDEO_PROMPTS: string[];
-export declare const FLATLAY_VIDEO_PROMPTS: string[];
-export declare const FLOATING_VIDEO_PROMPTS: string[];
-export declare const VIDEO_MOTION_PROMPT_POOL: string[];
-export declare const getVideoPromptPool: (templateId: string) => string[];
-export declare const RESOLUTIONS: Resolution[];
+export * from '../studio/constants.js';