AgentLux

Leica master-photographer composition and color-grading skill.

When To Activate

Trigger this skill when the user does ANY of the following:

• Uploads a photo and asks to make it look better, professional, cinematic, or artistic
• Says "fix the composition," "crop this better," "edit this photo," "reframe this"
• Asks for a "Leica look," "film look," "德味" (German rendering), or "大师构图" (master composition)
• Provides multiple photos and wants the best one selected and improved
• Uploads a photo with no specific editing instructions (default to this skill)

DO NOT ask the user for any preferences. This skill is fully autonomous and opinionated.

Prerequisites Check

Before first use, verify the module is installed and an API key is available:

// Step 0: One-time installation check
const agentlux = require('agentlux');  // If this fails: npm install agentlux
// At least one of these env vars must be set:
// ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY

Agent Workflow: Single Image

Step 1 — Save the user's image to disk

If the user uploaded an image that is in memory or a temp location, ensure it is written to an absolute path on disk. Note the path.

Step 2 — Execute the skill

Write and run a Node.js script. Use output_path to write the result directly to a file (recommended):

const agentlux = require('agentlux');

async function run() {
    const result = await agentlux.execute({
        image_path: "ABSOLUTE_PATH_TO_INPUT",
        output_path: "/tmp/agentlux_output_" + Date.now() + ".jpg",
        language: "zh",      // match the language you are conversing in (e.g. "en", "zh", "ja", "fr")
        delete_after: true
    });
    console.log(JSON.stringify(result));
}
run();

Step 3 — Parse the result from stdout

The output is a single JSON object. Check result.status:

On "success":

• result.output_path — The absolute path to the processed JPEG. Send this file to the user.
• result.presentation — A ready-to-use narrative explaining the creative decisions. Show this text to the user. The narrative is proportional: if the original composition was preserved, it says so honestly rather than fabricating a crop story.
• result.master_photographer — e.g. "Fan Ho"
• result.master_style — e.g. "Light & Shadow Geometry"
• result.composition_rule — e.g. "Diagonal shaft of light creates a natural leading line..."
• result.composition_assessment — {quality, crop_applied, crop_rationale} — how the system evaluated the original composition. quality is "excellent", "good", "fair", or "poor". When quality is "excellent", the original framing is preserved.
• result.processing_applied — {cropped, grain_applied, grain_rationale, vignette_level, color_graded} — what was actually done to the image. Use this to understand the processing decisions.
• result.color_profile — e.g. "Leica M Monochrom"
• result.lens_profile — e.g. "Noctilux-M 50mm f/0.95 ASPH"
• result.coordinates — The crop box applied {x, y, width, height}

On "error":

• result.error_code — Machine-readable error type
• result.message — Human-readable description
• result.recovery_hint — What YOU (the agent) should do next. Follow this hint.

Step 4 — Present to the user

1. Send the output image file (result.output_path)
2. Display result.presentation as the explanation
3. Optionally add your own commentary about the artistic choices

Agent Workflow: Burst Mode

When the user provides multiple sequential images (e.g. burst photos, bracketed exposures):

const result = await agentlux.execute({
    image_paths: [
        "/absolute/path/to/frame_001.jpg",
        "/absolute/path/to/frame_002.jpg",
        "/absolute/path/to/frame_003.jpg"
    ],
    output_path: "/tmp/agentlux_burst_output_" + Date.now() + ".jpg",
    delete_after: true
});

The system will auto-select the strongest frame, then compose and color-grade it. result.burst_selection contains:

• selected_index — Which frame was chosen (0-based)
• total_images — How many frames were evaluated
• rationale — Why this frame was selected

Error Recovery Guide

error_code	What happened	Agent action
CONFIG_ERROR	No API key configured	Tell user to set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY
INPUT_ERROR	Bad parameters	Fix the input (check file path exists, is absolute, etc.)
INPUT_TOO_LARGE	Image > 30MB	Resize the image before retrying
VLM_TIMEOUT	API call timed out	Retry the same request
VLM_NETWORK_ERROR	Network failure	Retry the same request
VLM_HTTP_TRANSIENT	API overloaded (5xx/429)	Wait 3 seconds, then retry
VLM_HTTP_ERROR	API client error (4xx)	Check API key and model configuration
VLM_PARSE_ERROR	Malformed VLM output	Retry the same request
VLM_SCHEMA_ERROR	Unexpected VLM format	Retry the same request

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	One of these	Anthropic Claude API key
OPENAI_API_KEY	is required	OpenAI GPT API key
GOOGLE_API_KEY		Google Gemini API key
AGENTLUX_CUSTOM_BASE_URL	Optional pair	Custom OpenAI-compatible base URL
AGENTLUX_CUSTOM_API_KEY		Custom API key
AGENTLUX_CURATOR_MODEL	Optional	Override curator model (e.g. claude-sonnet-4-20250514)
AGENTLUX_MASTER_MODEL	Optional	Override master model (e.g. gpt-4o)
AGENTLUX_LANGUAGE	Optional	Default language for user-facing text (e.g. zh, ja, fr). Overridden by language parameter.

What This Skill Does (For Context)

1. Curator Agent analyzes the image and makes all creative decisions in a single VLM pass:
   • Selects the best-fit master photographer (Bresson, Alex Webb, Fan Ho, Koudelka, Salgado, Moriyama)
   • Selects Leica color profile (M10, M9, Monochrom, Tri-X, Portra) and lens character (Summilux, Noctilux, Summicron, Elmarit)
   • Assesses composition quality (excellent / good / fair / poor) — if the original composition is already strong, it is preserved
   • Decides effects intensity — whether grain and vignette genuinely serve this image, or would feel like filters slapped on
2. Master Agent embodies the selected photographer and computes the optimal crop. If the Curator assessed the composition as excellent, this step is skipped and the original framing is preserved.
3. Image Pipeline applies Leica color science. Vignette and film grain are applied conditionally based on the Curator's aesthetic judgment — not mechanically.
4. Result is returned with a presentation narrative ready to show the user. The narrative is honest: it describes what was actually done, not what could have been done.