studio-lumiere-cli 0.1.0

package/.agents/skills/muse-management/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: muse-management
+description: Create and manage Muses locally with the SDK/CLI; use when building or reusing Muse profiles.
+---
+
+# Skill: Muse Creation & Management (local-lumiere)
+
+This document is a complete, end-to-end guide for creating and managing Muses locally using the **local-lumiere** SDK/CLI. It covers every function, parameter, and configuration point involved in Muse creation and reuse.
+
+---
+
+## Quick Start (60 seconds)
+
+1) Ensure `GEMINI_API_KEY` is set in your environment.
+2) Build the project:
+
+```
+npm install
+npm run build
+```
+
+3) Create a Muse via CLI:
+
+```
+node dist/cli.js muse \
+  --name "Editorial Muse" \
+  --source ./inputs/muse_source.jpg \
+  --variations 3
+```
+
+4) Find outputs under `outputs/muses/<timestamp>/` and the local index in `outputs/muses.json`.
+
+---
+
+## 0) Purpose
+
+Muses are reusable model references. You create a Muse by generating variation portraits from a source image, then selecting 3 to store as the Muse’s reference set. Those reference images can be used in `generateImages()` to keep model identity consistent.
+
+---
+
+## 1) Where the Muse API Lives
+
+**SDK entrypoint**: `src/index.ts`
+
+- `createMuse`
+- `generateMuseVariations`
+
+**Pipeline implementation**: `src/pipelines/createMuse.ts`
+
+**Muse storage**: `src/storage/museStore.ts`
+
+---
+
+## 2) Required Environment and Configuration
+
+### 2.1 Environment Variables
+
+- `GEMINI_API_KEY` (required)
+- `LUMIERE_OUTPUT_DIR` (optional, default `outputs`)
+
+### 2.2 Runtime Config Object
+
+```ts
+export interface LumiereConfig {
+  apiKey: string;
+  outputDir: string;
+  models?: {
+    prompt?: string;
+    image?: string;
+    video?: string;
+  };
+  retry?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+  };
+}
+```
+
+---
+
+## 3) Primary Functions
+
+### 3.1 generateMuseVariations
+
+```ts
+export const generateMuseVariations = async (
+  config: LumiereConfig,
+  sourceImage: string,
+  count: number,
+  outputDir: string
+): Promise<string[]>
+```
+
+**Behavior:**
+- Creates `count` portrait variations from the source image.
+- Enforces **same identity** but different hair, styling, pose, and background.
+- Writes each variation as `variation_<n>.png`.
+
+### 3.2 createMuse
+
+```ts
+export const createMuse = async (
+  config: LumiereConfig,
+  request: CreateMuseRequest
+): Promise<CreateMuseResult>
+```
+
+```ts
+export interface CreateMuseRequest {
+  name: string;          // Required
+  sourceImage: string;   // Required
+  variations?: number;   // Optional (default: 3)
+  outputDir?: string;    // Optional override
+}
+```
+
+```ts
+export interface CreateMuseResult {
+  muse: MuseRecord;
+  variationPaths: string[];
+  logPath: string;
+}
+```
+
+---
+
+## 4) Muse Storage and Indexing
+
+Muses are stored locally in a simple JSON index at:
+
+```
+<outputDir>/muses.json
+```
+
+Each Muse record:
+
+```ts
+export interface MuseRecord {
+  id: string;
+  name: string;
+  imagePaths: string[]; // exactly 3 paths used for reference
+  createdAt: string;
+}
+```
+
+The helper functions in `src/storage/museStore.ts` allow:
+
+- `loadMuses(baseDir)`
+- `saveMuses(baseDir, muses)`
+- `addMuse(baseDir, muse)`
+- `getMuseById(baseDir, id)`
+
+---
+
+## 5) Using a Muse in Image Generation
+
+To use a Muse when generating images, provide **either**:
+
+- `museImagePaths` (direct paths), OR
+- `museId` (stored in `muses.json`)
+
+Example in `generateImages()`:
+
+```ts
+await generateImages(config, {
+  inputImages: ["./inputs/ring.jpg"],
+  selections: { templateId: "half_body_muse" },
+  museId: "muse_1700000000000"
+});
+```
+
+---
+
+## 6) CLI Usage
+
+### 6.1 Create a Muse
+
+```
+node dist/cli.js muse --name "Editorial Muse" --source ./inputs/muse_source.jpg --variations 3
+```
+
+The CLI does not include a delete or rename command; those are handled by editing `muses.json` directly or using the helper functions in code.
+
+---
+
+## 7) SDK Example
+
+```ts
+import { createMuse } from "./dist/index.js";
+
+const result = await createMuse(
+  { apiKey, outputDir: "outputs" },
+  { name: "Editorial Muse", sourceImage: "./inputs/muse_source.jpg", variations: 3 }
+);
+
+console.log(result.muse.id);
+```
+
+---
+
+## 8) Error Handling and Retries
+
+Muse creation uses the same retry settings as other pipelines.
+
+---
+
+## 9) Related Files
+
+- `src/pipelines/createMuse.ts`
+- `src/storage/museStore.ts`
+- `src/clients/geminiClient.ts`
+- `src/cli.ts`
+
+---
+
+## 10) See Also
+
+- `C:\Users\karim\Documents\local-lumiere\.agents\skills\config-troubleshooting.md`
+
+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`
+

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

@@ -0,0 +1,192 @@
+---
+name: refine-images
+description: Refine existing images with the local-lumiere SDK/CLI; use when you need to enhance or edit prior outputs.
+---
+
+# Skill: Refine Images (local-lumiere)
+
+This document is a complete, end-to-end guide for an AI agent to refine existing images using the **local-lumiere** SDK/CLI. It covers every function, parameter, and configuration point involved in refinement.
+
+---
+
+## Quick Start (60 seconds)
+
+1) Ensure `GEMINI_API_KEY` is set in your environment.
+2) Build the project:
+
+```
+npm install
+npm run build
+```
+
+3) Refine an image via CLI:
+
+```
+node dist/cli.js refine \
+  --image ./outputs/generations/<timestamp>/image_1.png \
+  --instruction "Make the ring slightly larger"
+```
+
+4) Find output files under `outputs/refinements/<timestamp>/`.
+
+---
+
+## 0) Purpose
+
+Refinement applies targeted edits to an existing image while preserving jewelry fidelity, lighting, and composition unless explicitly changed. This is ideal for adjusting size, mood, or minor details without re-generating from scratch.
+
+---
+
+## 1) Where the Refinement API Lives
+
+**SDK entrypoint**: `src/index.ts`
+
+- `refineImage` (primary API)
+
+**Pipeline implementation**: `src/pipelines/refineImage.ts`
+
+**Gemini client wrapper**: `src/clients/geminiClient.ts`
+
+**File I/O**: `src/storage/files.ts`
+
+---
+
+## 2) Required Environment and Configuration
+
+### 2.1 Environment Variables
+
+- `GEMINI_API_KEY` (required)
+- `LUMIERE_OUTPUT_DIR` (optional, default `outputs`)
+
+### 2.2 Runtime Config Object
+
+```ts
+export interface LumiereConfig {
+  apiKey: string;
+  outputDir: string;
+  models?: {
+    prompt?: string;
+    image?: string;
+    video?: string;
+  };
+  retry?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+  };
+}
+```
+
+---
+
+## 3) Primary Function: refineImage
+
+### 3.1 Function Signature
+
+```ts
+export const refineImage = async (
+  config: LumiereConfig,
+  request: RefineRequest
+): Promise<string>
+```
+
+### 3.2 Request Object: RefineRequest
+
+```ts
+export interface RefineRequest {
+  inputImage: string;      // Required. Path to local image file.
+  instruction: string;     // Required. Natural-language refinement instruction.
+  sizeAdjustment?: number; // Optional. Percentage size of jewelry (e.g. 80, 120).
+  outputDir?: string;      // Optional. Override config.outputDir.
+}
+```
+
+### 3.3 Behavior
+
+- Builds a refinement prompt using the instruction.
+- If `sizeAdjustment` is provided and not 100, it explicitly scales **all jewelry** by that percent.
+- Uses the Gemini image model via `GeminiClient.generateImage()`.
+- Saves output as `refined.png` in `outputs/refinements/<timestamp>/`.
+- Writes `refine.json` log with input path, instruction, size, output path.
+
+---
+
+## 4) CLI Usage
+
+### 4.1 Basic Refinement
+
+```
+node dist/cli.js refine \
+  --image ./outputs/generations/<timestamp>/image_1.png \
+  --instruction "Soften the lighting and add a warmer mood"
+```
+
+### 4.2 Size Adjustment
+
+```
+node dist/cli.js refine \
+  --image ./outputs/generations/<timestamp>/image_1.png \
+  --instruction "Keep everything else the same" \
+  --size 120
+```
+
+---
+
+## 5) SDK Example
+
+```ts
+import { refineImage } from "./dist/index.js";
+
+const outputPath = await refineImage(
+  { apiKey, outputDir: "outputs" },
+  {
+    inputImage: "./outputs/generations/.../image_1.png",
+    instruction: "Make the ring slightly larger and the background softer",
+    sizeAdjustment: 115
+  }
+);
+
+console.log(outputPath);
+```
+
+---
+
+## 6) Error Handling and Retries
+
+Refinement uses the same retry settings as other pipelines:
+
+```ts
+retry: {
+  maxRetries: 3,
+  baseDelayMs: 1500,
+  maxDelayMs: 12000
+}
+```
+
+---
+
+## 7) Related Files
+
+- `src/pipelines/refineImage.ts`
+- `src/clients/geminiClient.ts`
+- `src/storage/files.ts`
+- `src/cli.ts`
+
+---
+
+## 8) See Also
+
+- `C:\Users\karim\Documents\local-lumiere\.agents\skills\config-troubleshooting.md`
+
+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`
+

package/.agents/skills/tired-girl/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: tired-girl
+description: Generate the tired-girl before-look image with no jewelry using a Muse or reference image; use for before/after sets.
+---
+
+# Skill: Tired Girl (Before-Look) Generation (local-lumiere)
+
+This document explains how to generate a "before" look image (tired, morning, no-makeup, crazy hair, pyjama) with **NO jewelry**, using either a Muse (preferred) or a single reference image.
+
+---
+
+## Quick Start (60 seconds)
+
+1) Ensure `GEMINI_API_KEY` is set.
+2) Build the project:
+
+```
+npm install
+npm run build
+```
+
+3) Generate a tired-girl image via CLI:
+
+```
+node dist/cli.js tired-girl \
+  --muse-id muse_1700000000000 \
+  --styles tired,morning \
+  --quantity 2
+```
+
+4) Find outputs under `outputs/tired_girl/<timestamp>/`.
+
+---
+
+## 1) API Location
+
+- Pipeline: `src/pipelines/generateTiredGirl.ts`
+- Prompt builder: `src/prompt/tiredGirlPrompt.ts`
+- Styles config: `src/config/tiredGirl.ts`
+
+---
+
+## 2) Request/Response
+
+```ts
+export interface TiredGirlRequest {
+  inputImage?: string;
+  museId?: string;
+  styleIds?: string[];
+  quantity?: number;
+  outputDir?: string;
+}
+
+export interface TiredGirlResult {
+  outputImages: string[];
+  logPath: string;
+}
+```
+
+Rules:
+- If `museId` is provided, it is used and `inputImage` is ignored.
+- If `museId` is not provided, `inputImage` is required.
+- `quantity` defaults to 1.
+- Styles cycle if quantity exceeds provided styles.
+
+---
+
+## 3) Styles
+
+Defined in `src/config/tiredGirl.ts`:
+
+- `tired`
+- `morning`
+- `no_makeup`
+- `crazy_hair`
+- `pyjama`
+
+---
+
+## 4) Two-Step Approach
+
+1) **Prompt enhancement** with reference images + user prompt (no jewelry requirement).
+2) **Image generation** using the enhanced prompt + reference images.
+
+Both steps are image-conditioned, mirroring the app’s two-step approach.
+
+---
+
+## 5) CLI Usage
+
+```
+node dist/cli.js tired-girl --muse-id muse_123 --styles tired,pyjama --quantity 2
+```
+
+Or with a single reference image:
+
+```
+node dist/cli.js tired-girl --image ./inputs/model.jpg --styles no_makeup
+```
+
+---
+
+## 6) SDK Example
+
+```ts
+import { generateTiredGirl } from "./dist/index.js";
+
+const result = await generateTiredGirl(
+  { apiKey, outputDir: "outputs" },
+  {
+    museId: "muse_1700000000000",
+    styleIds: ["tired", "pyjama"],
+    quantity: 2
+  }
+);
+
+console.log(result.outputImages);
+```
+
+---
+
+## 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`
+

package/.env.example

@@ -0,0 +1,2 @@
+GEMINI_API_KEY=your_key_here
+LUMIERE_OUTPUT_DIR=outputs

package/AGENTS.md

@@ -0,0 +1,66 @@
+# AI Agent Workflow & Standards
+
+This document outlines the mandatory workflow for all AI agents collaborating on this project. Strictly adhere to these procedures for every brand-new feature or significant task.
+
+## Image Overlay Defaults
+
+- Logo file: `logo-round.png`
+- Placement: `top-left`
+- Scale: `0.08`
+- Margin: `24`
+- Opacity: `0.75`
+- Script: `node .agents/skills/image-overlay/scripts/overlay-image.js`
+
+## 1. Workspace Preparation
+
+*   **Stories Directory:** All documentation and state tracking for a task must reside in the `stories/` folder.
+    *   *Action:* Check if the `stories/` folder exists. If not, create it immediately.
+*   **Git Branching:** All work must be performed on a dedicated feature branch.
+    *   *Naming Convention:* `story/<name-of-story>` (e.g., `story/mobile-ui-fix`).
+    *   *Action:* Create and switch to the new branch before writing any code.
+    *   *IMPORTANT:* all git commands should be executed one at a time. Don't try to chain them in one command. 
+
+## 2. The 5-Step Development Process
+
+We follow a strict iterative cycle. All outputs from these steps must be documented in a **single file** within the `stories/` folder.
+
+**Documentation File Details:**
+*   **Location:** `stories/`
+*   **Naming Convention:** `YYYY-MM-DD-short-descriptive-name.md` (e.g., `2026-01-25-mobile-ui-refactor.md`).
+*   **Format:** Markdown.
+
+### Step 1: Spec
+*   Analyze the user's request and requirements.
+*   Define the scope, goals, and technical constraints.
+*   Write this into the documentation file under a `## Spec` header.
+
+### Step 2: Plan
+*   Break down the implementation into actionable steps.
+*   Identify necessary file changes, dependencies, and architectural impacts.
+*   Write this into the documentation file under a `## Plan` header.
+
+### Step 3: Implement
+*   Write the code according to the approved plan.
+*   Adhere to existing project patterns, style guides, and tech stack conventions.
+*   Log significant actions or decisions in the documentation file under a `## Implementation Log` header.
+
+### Step 4: Review
+*   Self-critique the code.
+*   Run builds, linters, and tests (`npm run build`, `npx tsc --noEmit`, etc.) to verify correctness.
+*   Present the results and any findings to the user.
+*   Write findings in the documentation file under a `## Review` header.
+
+### Step 5: Fix (Iterative Loop)
+*   Address issues found in the Review step or feedback provided by the user.
+*   **Loop:** Repeat Steps 4 (Review) and 5 (Fix) until the user explicitly confirms the code works and is approved.
+*   Log fixes and subsequent reviews in the documentation file.
+
+## 3. Completion & Git Workflow
+
+Once the work is approved by the user (after the Review/Fix loop):
+
+1.  **Stage Files:** `git add` all relevant code files and the story documentation file.
+2.  **Review Changes:** Use the command `/git:review` to generate a summary of staged changes.
+3.  **Commit:** Use the command `/git:commit` to create the commit.
+4.  **Push & PR:** Use the command `/git:commit-push-pr` to push the branch and automatically create/open a Pull Request.
+5.  **Cleanup:** Use the command `/git:clean-gone` to clean up local branches and synchronize with the remote.

package/README.md

@@ -0,0 +1,96 @@
+# local-lumiere
+
+Local SDK + CLI for Studio Lumiere generation flows. Runs entirely on your machine and talks directly to Gemini APIs.
+
+## Setup
+
+1) Install dependencies
+
+```
+npm install
+```
+
+2) Create `.env`
+
+```
+GEMINI_API_KEY=your_key_here
+LUMIERE_OUTPUT_DIR=outputs
+```
+
+## CLI Usage
+
+List options:
+
+```
+node dist/cli.js list templates
+```
+
+Generate images:
+
+```
+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
+```
+
+Refine:
+
+```
+node dist/cli.js refine --image ./outputs/image.png --instruction "Make the ring slightly larger"
+```
+
+Upscale:
+
+```
+node dist/cli.js upscale --image ./outputs/image.png --scale 2
+```
+
+Create a Muse:
+
+```
+node dist/cli.js muse --name "Editorial Muse" --source ./inputs/muse_source.jpg --variations 3
+```
+
+Generate video:
+
+```
+node dist/cli.js video --prompt "Cinematic head turn showing earrings" --aspect 9:16 --duration 5
+```
+
+## 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"
+  }
+});
+```
+
+## Notes
+
+- The config lists are a curated subset of the full Studio Lumiere options. You can add or override options in `src/config/`.
+- 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.
+