prompts.chat Prompt Builder

A comprehensive developer toolkit for building, validating, and parsing AI prompts. Create structured prompts for chat models, image generators, video AI, and music generation with fluent, type-safe APIs.

Reason

Building effective AI prompts is challenging. Developers often struggle with:

• Inconsistent prompt structure — Different team members write prompts differently, leading to unpredictable AI responses
• No type safety — Typos and missing fields go unnoticed until runtime
• Repetitive boilerplate — Writing the same patterns over and over for common use cases
• Hard to maintain — Prompts scattered across codebases without standardization
• Multi-modal complexity — Each AI platform (chat, image, video, audio) has different requirements

prompts.chat solves these problems by providing a fluent, type-safe API that guides you through prompt construction with autocomplete, validation, and pre-built templates for common patterns.

Installation

npm install prompts.chat

Quick Start

import { builder, chat, image, audio, variables, quality } from 'prompts.chat';

// Build structured text prompts
const prompt = builder()
  .role("Senior TypeScript Developer")
  .task("Review the following code for bugs and improvements")
  .constraints(["Be concise", "Focus on critical issues"])
  .variable("code", { required: true })
  .build();

// Build chat prompts with full control
const chatPrompt = chat()
  .role("expert code reviewer")
  .tone("professional")
  .expertise("TypeScript", "React", "Node.js")
  .task("Review code and provide actionable feedback")
  .stepByStep()
  .json()
  .build();

// Build image generation prompts
const imagePrompt = image()
  .subject("a cyberpunk samurai")
  .environment("neon-lit Tokyo streets")
  .shot("medium")
  .lens("35mm")
  .lightingType("rim")
  .medium("cinematic")
  .build();

// Build music generation prompts  
const musicPrompt = audio()
  .genre("electronic")
  .mood("energetic")
  .bpm(128)
  .instruments(["synthesizer", "drums", "bass"])
  .build();

// Normalize variable formats
const normalized = variables.normalize("Hello {{name}}, you are [ROLE]");
// → "Hello ${name}, you are ${role}"

// Check quality locally (no API needed)
const result = quality.check("Act as a developer...");
console.log(result.score); // 0.85

Modules

• Variables — Variable detection and normalization
• Similarity — Content deduplication
• Builder — Structured text prompts
• Chat Builder — Chat/conversational prompts
• Image Builder — Image generation prompts
• Video Builder — Video generation prompts
• Audio Builder — Music/audio generation prompts
• Quality — Prompt validation
• Parser — Multi-format parsing

🔧 Variables

Universal variable detection and normalization across different formats.

import { variables } from 'prompts.chat';

// Detect variables in any format
const detected = variables.detect("Hello {{name}}, welcome to [COMPANY]");
// → [{ name: "name", pattern: "double_curly" }, { name: "COMPANY", pattern: "single_bracket" }]

// Normalize all formats to ${var}
const normalized = variables.normalize("Hello {{name}}, you are [ROLE]");
// → "Hello ${name}, you are ${role}"

// Extract variables from ${var} format
const vars = variables.extractVariables("Hello ${name:World}");
// → [{ name: "name", defaultValue: "World" }]

// Compile template with values
const result = variables.compile("Hello ${name:World}", { name: "Developer" });
// → "Hello Developer"

// Get pattern descriptions
variables.getPatternDescription("double_bracket"); // → "[[...]]"

Supported Formats

| Format | Example | Pattern Name | |--------|---------|--------------| | ${var} | ${name} | dollar_curly | | ${var:default} | ${name:World} | dollar_curly | | {{var}} | {{name}} | double_curly | | [[var]] | [[name]] | double_bracket | | [VAR] | [NAME] | single_bracket | | {VAR} | {NAME} | single_curly | | <VAR> | <NAME> | angle_bracket | | %VAR% | %NAME% | percent |

API Reference

| Function | Description | |----------|-------------| | detect(text) | Detect variables in any format | | normalize(text) | Convert all formats to ${var} | | extractVariables(text) | Extract from ${var} format | | compile(text, values, options?) | Replace variables with values | | convertToSupportedFormat(variable) | Convert a single variable | | getPatternDescription(pattern) | Get human-readable pattern |

📊 Similarity

Content similarity detection for deduplication using Jaccard and n-gram algorithms.

import { similarity } from 'prompts.chat';

// Calculate similarity score (0-1)
const score = similarity.calculate(prompt1, prompt2);
// → 0.87

// Check if prompts are duplicates (default threshold: 0.85)
const isDupe = similarity.isDuplicate(prompt1, prompt2, 0.85);
// → true

// Find groups of duplicate prompts
const groups = similarity.findDuplicates(prompts, 0.85);
// → [[prompt1, prompt3], [prompt2, prompt5]]

// Deduplicate an array (keeps first occurrence)
const unique = similarity.deduplicate(prompts, 0.85);

// Get content fingerprint for indexing
const fingerprint = similarity.getContentFingerprint(prompt);

// Normalize content for comparison
const normalized = similarity.normalizeContent(text);

API Reference

| Function | Description | |----------|-------------| | calculate(content1, content2) | Calculate similarity score (0-1) | | isDuplicate(content1, content2, threshold?) | Check if similar (default 0.85) | | findDuplicates(prompts, threshold?) | Find groups of duplicates | | deduplicate(prompts, threshold?) | Remove duplicates | | normalizeContent(content) | Normalize for comparison | | getContentFingerprint(content) | Get fingerprint for indexing |

🏗️ Builder

Fluent DSL for creating structured text prompts.

import { builder, fromPrompt, templates } from 'prompts.chat';

// Build a custom prompt
const prompt = builder()
  .role("Senior Developer")
  .context("You are helping review a React application")
  .task("Analyze the code for performance issues")
  .constraints([
    "Be concise",
    "Focus on critical issues",
    "Suggest fixes with code examples"
  ])
  .output("JSON with { issues: [], suggestions: [] }")
  .variable("code", { required: true, description: "Code to review" })
  .example("const x = 1;", '{ "issues": [], "suggestions": [] }')
  .section("Additional Notes", "Consider React 18 best practices")
  .build();

console.log(prompt.content);
console.log(prompt.variables);
console.log(prompt.metadata);

// Create from existing prompt
const existing = fromPrompt("You are a helpful assistant...").build();

Builder Methods

| Method | Description | |--------|-------------| | .role(role) | Set AI persona (alias: .persona()) | | .context(context) | Set background info (alias: .background()) | | .task(task) | Set main instruction (alias: .instruction()) | | .constraints(list) | Add multiple constraints (alias: .rules()) | | .constraint(text) | Add single constraint | | .output(format) | Set output format (alias: .format()) | | .example(input, output) | Add input/output example | | .examples(list) | Add multiple examples | | .variable(name, options?) | Define a variable | | .section(title, content) | Add custom section | | .raw(content) | Set raw content | | .build() | Build the prompt | | .toString() | Get content string |

Pre-built Templates

import { templates } from 'prompts.chat';

// Code review template
const review = templates.codeReview({ 
  language: "TypeScript",
  focus: ["performance", "security"]
});

// Translation template
const translate = templates.translation("English", "Spanish");

// Summarization template
const summary = templates.summarize({ 
  maxLength: 100, 
  style: "bullet" 
});

// Q&A template
const qa = templates.qa("You are answering questions about React.");

💬 Chat Builder

Comprehensive model-agnostic builder for conversational AI prompts. Works with GPT-4, Claude, Gemini, Llama, and any chat model.

Quick Start

import { chat } from 'prompts.chat';

const prompt = chat()
  .role("helpful coding assistant")
  .context("Building a React application")
  .task("Explain async/await in JavaScript")
  .stepByStep()
  .detailed()
  .build();

console.log(prompt.systemPrompt);
console.log(prompt.messages);

Full Example

import { chat } from 'prompts.chat';

const prompt = chat()
  // ━━━ Persona ━━━
  .persona({
    name: "Alex",
    role: "senior software architect",
    tone: ["professional", "analytical"],
    expertise: ["system-design", "microservices", "cloud-architecture"],
    personality: ["patient", "thorough", "pragmatic"],
    background: "15 years of experience at FAANG companies",
    language: "English",
    verbosity: "detailed"
  })
  .role("expert code reviewer")                    // Override role
  .tone(["technical", "concise"])                  // Override tone(s)
  .expertise(["coding", "engineering"])            // Override expertise
  .personality(["direct", "helpful"])              // Override personality
  .background("Specialized in distributed systems")
  .speakAs("CodeReviewer")                         // Set a name
  .responseLanguage("English")                     // Response language
  
  // ━━━ Context ━━━
  .context({
    background: "Reviewing a pull request for an e-commerce platform",
    domain: "software engineering",
    audience: "mid-level developers",
    purpose: "improve code quality and maintainability",
    constraints: ["Follow team coding standards", "Consider performance"],
    assumptions: ["Team uses TypeScript", "Project uses React"],
    knowledge: ["Existing codebase uses Redux", "Team prefers functional components"]
  })
  .domain("web development")                       // Set knowledge domain
  .audience("junior developers")                   // Target audience
  .purpose("educational code review")              // Purpose of interaction
  .constraints(["Be constructive", "Explain why"]) // Add constraints
  .constraint("Focus on security issues")          // Single constraint
  .assumptions(["Code compiles successfully"])     // Set assumptions
  .knowledge(["Using React 18", "Node.js backend"]) // Known facts
  
  // ━━━ Task ━━━
  .task({
    instruction: "Review the submitted code and provide actionable feedback",
    steps: [
      "Analyze code structure and organization",
      "Check for potential bugs and edge cases",
      "Evaluate performance implications",
      "Suggest improvements with examples"
    ],
    deliverables: ["Summary of issues", "Prioritized recommendations", "Code examples"],
    criteria: ["Feedback is specific", "Examples are provided", "Tone is constructive"],
    antiPatterns: ["Vague criticism", "No examples", "Harsh language"],
    priority: "accuracy"
  })
  .instruction("Review this React component")      // Main instruction
  .steps([                                         // Override steps
    "Check hooks usage",
    "Verify prop types",
    "Review state management"
  ])
  .deliverables(["Issue list", "Fixed code"])      // Expected deliverables
  .criteria(["Clear explanations"])                // Success criteria
  .avoid(["Being overly critical", "Ignoring context"])  // Anti-patterns
  .priority("thoroughness")                        // accuracy | speed | creativity | thoroughness
  
  // ━━━ Examples (Few-Shot) ━━━
  .example(
    "const [data, setData] = useState()",
    "Consider adding a type parameter: useState<DataType>()",
    "TypeScript generics improve type safety"
  )
  .examples([
    { input: "useEffect(() => { fetch() })", output: "Add cleanup function for async operations" },
    { input: "if(data == null)", output: "Use strict equality (===) for null checks" }
  ])
  .fewShot([                                       // Alternative few-shot syntax
    { input: "var x = 1", output: "Use const or let instead of var" },
    { input: "any[]", output: "Define specific array types" }
  ])
  
  // ━━━ Output Format ━━━
  .output({
    format: { type: "markdown" },
    length: "detailed",
    style: "mixed",
    includeExamples: true,
    includeExplanation: true
  })
  .outputFormat("markdown")                        // text | json | markdown | code | table
  .json()                                          // Shortcut for JSON output
  .jsonSchema("CodeReview", {                      // JSON with schema
    type: "object",
    properties: {
      issues: { type: "array" },
      suggestions: { type: "array" }
    }
  })
  .markdown()                                      // Markdown output
  .code("typescript")                              // Code output with language
  .table()                                         // Table output
  
  // ━━━ Output Length ━━━
  .length("detailed")                              // brief | moderate | detailed | comprehensive | exhaustive
  .brief()                                         // Shortcut for brief
  .moderate()                                      // Shortcut for moderate
  .detailed()                                      // Shortcut for detailed
  .comprehensive()                                 // Shortcut for comprehensive
  .exhaustive()                                    // Shortcut for exhaustive
  
  // ━━━ Output Style ━━━
  .style("mixed")                                  // prose | bullet-points | numbered-list | table | code | mixed | qa | dialogue
  
  // ━━━ Output Includes ━━━
  .withExamples()                                  // Include examples in response
  .withExplanation()                               // Include explanations
  .withSources()                                   // Cite sources
  .withConfidence()                                // Include confidence level
  
  // ━━━ Reasoning ━━━
  .reasoning({
    style: "chain-of-thought",
    showWork: true,
    verifyAnswer: true,
    considerAlternatives: true,
    explainAssumptions: true
  })
  .reasoningStyle("step-by-step")                  // step-by-step | chain-of-thought | tree-of-thought | direct | analytical | ...
  .stepByStep()                                    // Shortcut: step-by-step + showWork
  .chainOfThought()                                // Shortcut: chain-of-thought + showWork
  .treeOfThought()                                 // Shortcut: tree-of-thought + showWork
  .firstPrinciples()                               // Shortcut: first-principles + showWork
  .devilsAdvocate()                                // Shortcut: devil-advocate + considerAlternatives
  .showWork()                                      // Show reasoning process
  .verifyAnswer()                                  // Verify before presenting
  .considerAlternatives()                          // Consider alternatives
  .explainAssumptions()                            // Explain assumptions
  
  // ━━━ Memory ━━━
  .memory({
    summary: "Previously discussed authentication patterns",
    facts: ["User prefers JWT", "API uses REST"],
    preferences: ["Concise answers", "Include code examples"],
    history: [
      { role: "user", content: "How do I handle auth?" },
      { role: "assistant", content: "I recommend JWT with refresh tokens..." }
    ]
  })
  .remember(["User is building a SaaS app"])       // Add facts to memory
  .preferences(["Show code examples"])             // User preferences
  .history([                                       // Previous messages
    { role: "user", content: "Previous question..." },
    { role: "assistant", content: "Previous answer..." }
  ])
  .summarizeHistory("Discussed React patterns")    // Summary of history
  
  // ━━━ Messages ━━━
  .system("You are a helpful assistant.")          // System message
  .user("Please review this code:", "developer")   // User message (with optional name)
  .assistant("I'll analyze the code now.")         // Assistant message
  .message("user", "Here's the code...")           // Generic message
  .messages([                                      // Multiple messages
    { role: "user", content: "First question" },
    { role: "assistant", content: "First answer" }
  ])
  .conversation([                                  // Conversation turns
    { user: "What is X?", assistant: "X is..." },
    { user: "How does it work?" }
  ])
  
  // ━━━ Custom ━━━
  .addSystemPart("Additional system instructions") // Add to system prompt
  .raw("Complete custom system prompt")            // Replace with raw content
  
  .build();

// Access outputs
console.log(prompt.messages);       // Array of ChatMessage objects
console.log(prompt.systemPrompt);   // Built system prompt string
console.log(prompt.userPrompt);     // Latest user message content
console.log(prompt.metadata);       // Structured metadata

// Export formats
const yaml = prompt.toYAML();
const json = prompt.toJSON();
const md = prompt.toMarkdown();
const system = prompt.toSystemPrompt();  // Just the system prompt
const msgs = prompt.toMessages();        // Just the messages array

Types Reference

Message Types

type MessageRole = 'system' | 'user' | 'assistant';

interface ChatMessage {
  role: MessageRole;
  content: string;
  name?: string;
}

Persona Types

type PersonaTone = 
  | 'professional' | 'casual' | 'formal' | 'friendly' | 'academic'
  | 'technical' | 'creative' | 'empathetic' | 'authoritative' | 'playful'
  | 'concise' | 'detailed' | 'socratic' | 'coaching' | 'analytical'
  | 'encouraging' | 'neutral' | 'humorous' | 'serious';

type PersonaExpertise = 
  | 'general' | 'coding' | 'writing' | 'analysis' | 'research'
  | 'teaching' | 'counseling' | 'creative' | 'legal' | 'medical'
  | 'financial' | 'scientific' | 'engineering' | 'design' | 'marketing'
  | 'business' | 'philosophy' | 'history' | 'languages' | 'mathematics';

Reasoning Types

type ReasoningStyle = 
  | 'step-by-step' | 'chain-of-thought' | 'tree-of-thought' 
  | 'direct' | 'analytical' | 'comparative' | 'deductive' | 'inductive'
  | 'first-principles' | 'analogical' | 'devil-advocate';

Output Types

type ResponseFormatType = 'text' | 'json' | 'markdown' | 'code' | 'table';

type OutputLength = 'brief' | 'moderate' | 'detailed' | 'comprehensive' | 'exhaustive';

type OutputStyle = 'prose' | 'bullet-points' | 'numbered-list' | 'table' | 'code' | 'mixed' | 'qa' | 'dialogue';

interface JsonSchema {
  name: string;
  description?: string;
  schema: Record<string, unknown>;
}

Methods Reference

Message Methods

| Method | Signature | Description | |--------|-----------|-------------| | .system() | system(content: string) | Set system message | | .user() | user(content: string, name?: string) | Add user message | | .assistant() | assistant(content: string) | Add assistant message | | .message() | message(role, content, name?) | Add generic message | | .messages() | messages(messages: ChatMessage[]) | Add multiple messages | | .conversation() | conversation(turns[]) | Add conversation turns |

Persona Methods

| Method | Signature | Description | |--------|-----------|-------------| | .persona() | persona(settings: ChatPersona \| string) | Set full persona | | .role() | role(role: string) | Set AI role | | .tone() | tone(tone: PersonaTone \| PersonaTone[]) | Set tone(s) | | .expertise() | expertise(areas: PersonaExpertise \| PersonaExpertise[]) | Set expertise | | .personality() | personality(traits: string[]) | Set personality traits | | .background() | background(background: string) | Set background info | | .speakAs() | speakAs(name: string) | Set persona name | | .responseLanguage() | responseLanguage(language: string) | Set response language |

Context Methods

| Method | Signature | Description | |--------|-----------|-------------| | .context() | context(settings: ChatContext \| string) | Set full context | | .domain() | domain(domain: string) | Set knowledge domain | | .audience() | audience(audience: string) | Set target audience | | .purpose() | purpose(purpose: string) | Set purpose | | .constraints() | constraints(constraints: string[]) | Add constraints | | .constraint() | constraint(constraint: string) | Add single constraint | | .assumptions() | assumptions(assumptions: string[]) | Set assumptions | | .knowledge() | knowledge(facts: string[]) | Set known facts |

Task Methods

| Method | Signature | Description | |--------|-----------|-------------| | .task() | task(instruction: string \| ChatTask) | Set task | | .instruction() | instruction(instruction: string) | Set main instruction | | .steps() | steps(steps: string[]) | Set task steps | | .deliverables() | deliverables(deliverables: string[]) | Set deliverables | | .criteria() | criteria(criteria: string[]) | Set success criteria | | .avoid() | avoid(antiPatterns: string[]) | Set anti-patterns | | .priority() | priority(priority) | Set priority |

Example Methods

| Method | Signature | Description | |--------|-----------|-------------| | .example() | example(input, output, explanation?) | Add single example | | .examples() | examples(examples: ChatExample[]) | Add multiple examples | | .fewShot() | fewShot(examples[]) | Add few-shot examples |

Output Format Methods

| Method | Signature | Description | |--------|-----------|-------------| | .output() | output(settings: ChatOutput) | Set full output settings | | .outputFormat() | outputFormat(format: ResponseFormatType) | Set format type | | .json() | json(schema?: JsonSchema) | JSON output | | .jsonSchema() | jsonSchema(name, schema, description?) | JSON with schema | | .markdown() | markdown() | Markdown output | | .code() | code(language?: string) | Code output | | .table() | table() | Table output |

Output Length Methods

| Method | Signature | Description | |--------|-----------|-------------| | .length() | length(length: OutputLength) | Set length | | .brief() | brief() | Brief output | | .moderate() | moderate() | Moderate output | | .detailed() | detailed() | Detailed output | | .comprehensive() | comprehensive() | Comprehensive output | | .exhaustive() | exhaustive() | Exhaustive output |

Output Style Methods

| Method | Signature | Description | |--------|-----------|-------------| | .style() | style(style: OutputStyle) | Set output style | | .withExamples() | withExamples() | Include examples | | .withExplanation() | withExplanation() | Include explanations | | .withSources() | withSources() | Cite sources | | .withConfidence() | withConfidence() | Include confidence |

Reasoning Methods

| Method | Signature | Description | |--------|-----------|-------------| | .reasoning() | reasoning(settings: ChatReasoning) | Set full reasoning | | .reasoningStyle() | reasoningStyle(style: ReasoningStyle) | Set style | | .stepByStep() | stepByStep() | Step-by-step reasoning | | .chainOfThought() | chainOfThought() | Chain-of-thought | | .treeOfThought() | treeOfThought() | Tree-of-thought | | .firstPrinciples() | firstPrinciples() | First principles | | .devilsAdvocate() | devilsAdvocate() | Devil's advocate | | .showWork() | showWork(show?) | Show reasoning | | .verifyAnswer() | verifyAnswer(verify?) | Verify answer | | .considerAlternatives() | considerAlternatives(consider?) | Consider alternatives | | .explainAssumptions() | explainAssumptions(explain?) | Explain assumptions |

Memory Methods

| Method | Signature | Description | |--------|-----------|-------------| | .memory() | memory(memory: ChatMemory) | Set full memory | | .remember() | remember(facts: string[]) | Add facts | | .preferences() | preferences(prefs: string[]) | Set preferences | | .history() | history(messages: ChatMessage[]) | Set history | | .summarizeHistory() | summarizeHistory(summary: string) | Set summary |

Custom & Output Methods

| Method | Signature | Description | |--------|-----------|-------------| | .addSystemPart() | addSystemPart(part: string) | Add system part | | .raw() | raw(content: string) | Set raw content | | .build() | build(): BuiltChatPrompt | Build the prompt | | .toString() | toString(): string | Get system prompt | | .toSystemPrompt() | toSystemPrompt(): string | Get system prompt | | .toMessages() | toMessages(): ChatMessage[] | Get messages | | .toJSON() | toJSON(): string | Export as JSON | | .toYAML() | toYAML(): string | Export as YAML | | .toMarkdown() | toMarkdown(): string | Export as Markdown |

Output Structure

interface BuiltChatPrompt {
  messages: ChatMessage[];    // Full message array including system
  systemPrompt: string;       // Built system prompt
  userPrompt?: string;        // Latest user message content
  metadata: {
    persona?: ChatPersona;
    context?: ChatContext;
    task?: ChatTask;
    output?: ChatOutput;
    reasoning?: ChatReasoning;
    examples?: ChatExample[];
  };
}

Presets

Pre-configured builders for common use cases:

import { chatPresets } from 'prompts.chat';

// Expert coder
const coder = chatPresets.coder("TypeScript")
  .task("Review this function")
  .user("function add(a, b) { return a + b }");

// Creative/Professional/Academic writer
const writer = chatPresets.writer("creative")
  .task("Write a short story");

// Patient tutor with subject expertise
const tutor = chatPresets.tutor("mathematics")
  .user("Explain derivatives");

// Data analyst with chain-of-thought
const analyst = chatPresets.analyst()
  .user("Analyze these sales figures");

// Socratic philosopher (asks questions)
const socratic = chatPresets.socratic()
  .user("What is justice?");

// Constructive critic
const critic = chatPresets.critic()
  .user("Review my business plan");

// Creative brainstormer
const brainstormer = chatPresets.brainstormer()
  .user("Ideas for a mobile app");

// JSON-only responder with schema
const jsonBot = chatPresets.jsonResponder("Response", {
  type: "object",
  properties: {
    answer: { type: "string" },
    confidence: { type: "number" }
  }
});

// Summarizer with length control
const summarizer = chatPresets.summarizer("brief")
  .user("Summarize this article...");

// Translator to target language
const translator = chatPresets.translator("Japanese")
  .user("Hello, how are you?");

Usage Examples

Code Review Assistant

const codeReview = chat()
  .role("senior code reviewer")
  .expertise("coding")
  .tone(["professional", "constructive"])
  .context("TypeScript React project")
  .task("Review code for bugs, performance, and best practices")
  .steps([
    "Identify potential bugs",
    "Check for performance issues",
    "Suggest improvements"
  ])
  .criteria(["Be specific", "Provide examples"])
  .avoid(["Harsh criticism", "Vague feedback"])
  .markdown()
  .detailed()
  .withExamples()
  .user("Please review this component...")
  .build();

Research Assistant

const research = chat()
  .role("research assistant")
  .expertise(["research", "analysis"])
  .tone("academic")
  .context({
    domain: "machine learning",
    audience: "PhD students",
    purpose: "literature review"
  })
  .task("Analyze and summarize research papers")
  .chainOfThought()
  .withSources()
  .detailed()
  .markdown()
  .build();

JSON API Response

const apiHelper = chat()
  .role("API response generator")
  .tone("concise")
  .jsonSchema("UserData", {
    type: "object",
    properties: {
      users: {
        type: "array",
        items: {
          type: "object",
          properties: {
            id: { type: "number" },
            name: { type: "string" },
            email: { type: "string" }
          }
        }
      },
      total: { type: "number" }
    }
  })
  .avoid(["Include markdown", "Add explanations", "Use code fences"])
  .user("Generate 3 sample users")
  .build();

Multi-Turn Conversation

const conversation = chat()
  .role("helpful assistant")
  .tone("friendly")
  .memory({
    summary: "User is learning Python",
    facts: ["User is a beginner", "Prefers practical examples"],
    preferences: ["Step-by-step explanations"]
  })
  .conversation([
    { user: "What is a variable?", assistant: "A variable is a container for storing data..." },
    { user: "How do I create one?" }
  ])
  .stepByStep()
  .withExamples()
  .build();

🎨 Image Builder

Comprehensive builder for image generation prompts. Works with Midjourney, DALL-E, Stable Diffusion, Flux, and other image AI platforms.

Quick Start

import { image } from 'prompts.chat';

const prompt = image()
  .subject("a lone samurai")
  .environment("bamboo forest at dawn")
  .camera({ angle: "low-angle", shot: "wide", lens: "35mm" })
  .lighting({ type: "rim", time: "golden-hour" })
  .medium("cinematic")
  .build();

console.log(prompt.prompt);

Full Example

import { image } from 'prompts.chat';

const prompt = image()
  // ━━━ Subject ━━━
  .subject({
    main: "a cyberpunk samurai warrior",
    expression: "determined and fierce",
    pose: "dynamic battle stance",
    action: "deflecting bullets with katana",
    clothing: "neon-lit armor with glowing circuits",
    accessories: ["holographic visor", "cyber-enhanced arm"],
    age: "30s",
    gender: "female"
  })
  .subjectDetails(["intricate tattoos", "flowing hair"])   // Additional details
  .expression("intense focus")                             // Override expression
  .pose("mid-swing attack")                                // Override pose
  .action("slicing through rain droplets")                 // Override action
  .clothing("black nano-fiber suit")                       // Override clothing
  .accessories(["glowing katana", "shoulder armor"])       // Override accessories
  .subjectCount("single")                                  // single | couple | group | crowd | number
  
  // ━━━ Environment ━━━
  .environment({
    setting: "rain-soaked Tokyo alley",
    location: "Shibuya district",
    atmosphere: "electric and mysterious",
    props: ["neon signs", "steam vents", "holographic ads"],
    season: "winter"
  })
  .location("Neo-Tokyo, 2087")                             // Specific location
  .props(["flying cars overhead", "robot vendors"])        // Scene props
  .atmosphere("dense fog with neon glow")                  // Atmospheric description
  .season("autumn")                                        // spring | summer | autumn | winter
  
  // ━━━ Camera: Framing ━━━
  .shot("medium")                                          // extreme-close-up | close-up | medium | wide | ...
  .angle("low-angle")                                      // eye-level | low-angle | high-angle | dutch-angle | ...
  .lens("35mm")                                            // wide-angle | 35mm | 50mm | 85mm | telephoto | ...
  .focalLength("35mm")                                     // Specific focal length
  
  // ━━━ Camera: Focus & Depth ━━━
  .focus("shallow")                                        // shallow | deep | soft-focus | tilt-shift | bokeh-heavy | ...
  .aperture("f/1.4")                                       // Aperture setting
  .bokeh("smooth")                                         // smooth | creamy | swirly | soap-bubble | oval-anamorphic | ...
  
  // ━━━ Camera: Equipment ━━━
  .cameraBrand("sony")                                     // sony | canon | nikon | leica | hasselblad | arri | ...
  .cameraModel("sony-a7riv")                               // Specific camera model
  .sensor("full-frame")                                    // full-frame | aps-c | medium-format | ...
  .lensBrand("zeiss")                                      // zeiss | leica | sigma | canon | ...
  .lensModel("zeiss-otus-55")                              // Specific lens model
  
  // ━━━ Camera: Film & Filters ━━━
  .filmStock("kodak-portra-400")                           // Kodak, Fujifilm, CineStill, Ilford stocks
  .filmFormat("35mm")                                      // 35mm | 120-medium-format | instant-film | ...
  .filter("black-pro-mist")                                // nd | polarizer | black-pro-mist | diffusion | ...
  
  // ━━━ Camera: Exposure ━━━
  .iso(800)                                                // ISO sensitivity
  .shutterSpeed("1/250")                                   // Shutter speed
  .whiteBalance("tungsten")                                // daylight | cloudy | tungsten | fluorescent | ...
  .colorProfile("S-Log3")                                  // Color profile
  
  // ━━━ Lighting ━━━
  .lighting({
    type: ["rim", "practical"],
    time: "night",
    direction: "back",
    intensity: "dramatic",
    color: "neon pink and blue",
    sources: ["neon signs", "car headlights"]
  })
  .lightingType(["rim", "backlit"])                        // natural | studio | rim | rembrandt | butterfly | ...
  .timeOfDay("night")                                      // dawn | golden-hour | midday | blue-hour | night | ...
  .weather("rainy")                                        // sunny | cloudy | foggy | rainy | stormy | snowy | ...
  .lightDirection("back")                                  // front | side | back | top | three-quarter
  .lightIntensity("dramatic")                              // soft | medium | hard | dramatic
  
  // ━━━ Composition ━━━
  .composition({
    ruleOfThirds: true,
    symmetry: "none",
    foreground: "rain droplets",
    midground: "samurai figure",
    background: "towering neon buildings"
  })
  .ruleOfThirds()                                          // Enable rule of thirds
  .goldenRatio()                                           // Enable golden ratio
  .symmetry("vertical")                                    // none | horizontal | vertical | radial
  .foreground("splashing water droplets")                  // Foreground element
  .midground("central figure in action")                   // Midground element
  .background("city skyline with flying vehicles")         // Background element
  
  // ━━━ Style ━━━
  .style({
    medium: ["cinematic", "cyberpunk"],
    artist: ["Syd Mead", "Simon Stålenhag"],
    era: "futuristic",
    influence: ["Blade Runner", "Ghost in the Shell"],
    quality: ["highly detailed", "award-winning"]
  })
  .medium("cinematic")                                     // photorealistic | cinematic | anime | oil-painting | ...
  .artist(["Syd Mead", "Masamune Shirow"])                 // Reference artist(s)
  .influence(["Akira", "The Matrix"])                      // Style influences
  
  // ━━━ Color ━━━
  .color({
    palette: "neon",
    primary: ["cyan", "magenta"],
    accent: ["yellow", "white"],
    grade: "teal and orange",
    temperature: "cool",
    saturation: "vibrant",
    contrast: "high"
  })
  .palette("neon")                                         // warm | cool | vibrant | neon | monochrome | ...
  .primaryColors(["electric blue", "hot pink"])            // Primary color scheme
  .accentColors(["neon yellow", "white"])                  // Accent colors
  .colorGrade("cyberpunk teal and orange")                 // Color grading style
  
  // ━━━ Technical ━━━
  .technical({
    aspectRatio: "16:9",
    resolution: "8K",
    quality: "masterpiece",
    detail: "extreme",
    noise: "filmic",
    sharpness: "crisp"
  })
  .aspectRatio("16:9")                                     // 1:1 | 4:3 | 3:2 | 16:9 | 21:9 | 9:16 | ...
  .resolution("8K")                                        // Resolution string
  .quality("masterpiece")                                  // draft | standard | high | ultra | masterpiece
  
  // ━━━ Mood & Misc ━━━
  .mood(["dramatic", "mysterious", "epic"])                // serene | dramatic | tense | epic | intimate | ...
  .negative(["blurry", "low quality", "watermark"])        // Negative prompt items
  .custom("volumetric lighting through rain")              // Custom prompt text
  .custom("lens flare from neon signs")
  
  .build();

// Access outputs
console.log(prompt.prompt);       // Full formatted prompt with --no and --ar flags
console.log(prompt.structure);    // Full structured data object

// Export formats
const yaml = prompt.toYAML();
const json = prompt.toJSON();
const md = prompt.toMarkdown();

Types Reference

Camera Types

type ShotType = 'extreme-close-up' | 'close-up' | 'medium-close-up' | 'medium' 
  | 'medium-wide' | 'wide' | 'extreme-wide' | 'establishing' | 'full-body' | 'portrait' | 'headshot';

type CameraAngle = 'eye-level' | 'low-angle' | 'high-angle' | 'dutch-angle' | 'birds-eye' 
  | 'worms-eye' | 'over-the-shoulder' | 'point-of-view' | 'aerial' | 'drone'
  | 'canted' | 'oblique' | 'hip-level' | 'knee-level' | 'ground-level';

type LensType = 'wide-angle' | 'ultra-wide' | 'standard' | 'telephoto' | 'macro' | 'fisheye'
  | '14mm' | '24mm' | '35mm' | '50mm' | '85mm' | '100mm' | '135mm' | '200mm' | '400mm'
  | 'tilt-shift' | 'anamorphic' | 'spherical' | 'prime' | 'zoom';

type FocusType = 'shallow' | 'deep' | 'soft-focus' | 'tilt-shift' | 'rack-focus' | 'split-diopter'
  | 'zone-focus' | 'hyperfocal' | 'selective' | 'bokeh-heavy' | 'tack-sharp';

type BokehStyle = 'smooth' | 'creamy' | 'swirly' | 'busy' | 'soap-bubble' | 'cat-eye' | 'oval-anamorphic';

Equipment Types

type CameraBrand = 'sony' | 'canon' | 'nikon' | 'fujifilm' | 'leica' | 'hasselblad' | 'phase-one'
  | 'panasonic' | 'olympus' | 'pentax' | 'red' | 'arri' | 'blackmagic' | 'panavision';

type CameraModel = 'sony-a7iv' | 'sony-a7riv' | 'sony-a1' | 'canon-r5' | 'canon-r6' 
  | 'nikon-z9' | 'nikon-z8' | 'leica-m11' | 'leica-q3' | 'hasselblad-x2d'
  | 'fujifilm-x-t5' | 'fujifilm-gfx100s' | 'arri-alexa-35' | 'red-v-raptor' | ...;

type SensorFormat = 'full-frame' | 'aps-c' | 'micro-four-thirds' | 'medium-format' | 'large-format'
  | 'super-35' | 'vista-vision' | 'imax' | '65mm' | '35mm-film' | '16mm-film' | '8mm-film';

type LensBrand = 'zeiss' | 'leica' | 'canon' | 'nikon' | 'sony' | 'sigma' | 'tamron' | 'voigtlander'
  | 'fujifilm' | 'samyang' | 'rokinon' | 'tokina' | 'cooke' | 'arri' | 'panavision';

type LensModel = 'zeiss-otus-55' | 'zeiss-batis-85' | 'leica-summilux-50' | 'leica-noctilux-50'
  | 'canon-rf-50-1.2' | 'sony-gm-85-1.4' | 'sigma-art-35' | 'helios-44-2' | ...;

Film & Filter Types

type FilmStock = 
  // Kodak Color
  | 'kodak-portra-160' | 'kodak-portra-400' | 'kodak-portra-800' | 'kodak-ektar-100' | 'kodak-gold-200'
  // Kodak B&W
  | 'kodak-tri-x-400' | 'kodak-tmax-100' | 'kodak-tmax-400'
  // Kodak Cinema
  | 'kodak-vision3-50d' | 'kodak-vision3-200t' | 'kodak-vision3-500t'
  // Fujifilm
  | 'fujifilm-pro-400h' | 'fujifilm-velvia-50' | 'fujifilm-velvia-100' | 'fujifilm-provia-100f'
  // Ilford
  | 'ilford-hp5-plus' | 'ilford-delta-400' | 'ilford-fp4-plus'
  // CineStill
  | 'cinestill-50d' | 'cinestill-800t'
  // Instant
  | 'polaroid-sx-70' | 'polaroid-600' | 'instax-mini' | ...;

type FilmFormat = '35mm' | '120-medium-format' | '4x5-large-format' | '8x10-large-format'
  | '110-film' | 'instant-film' | 'super-8' | '16mm' | '65mm-imax';

type FilterType = 'uv' | 'polarizer' | 'nd' | 'nd-graduated' | 'black-pro-mist' | 'white-pro-mist'
  | 'glimmer-glass' | 'classic-soft' | 'streak' | 'starburst' | 'diffusion'
  | 'infrared' | 'color-gel' | 'warming' | 'cooling' | 'vintage-look';

Lighting Types

type LightingType = 'natural' | 'studio' | 'dramatic' | 'soft' | 'hard' | 'diffused'
  | 'key' | 'fill' | 'rim' | 'backlit' | 'silhouette' | 'rembrandt'
  | 'split' | 'butterfly' | 'loop' | 'broad' | 'short' | 'chiaroscuro'
  | 'high-key' | 'low-key' | 'three-point' | 'practical' | 'motivated';

type TimeOfDay = 'dawn' | 'sunrise' | 'golden-hour' | 'morning' | 'midday' | 'afternoon'
  | 'blue-hour' | 'sunset' | 'dusk' | 'twilight' | 'night' | 'midnight';

type WeatherLighting = 'sunny' | 'cloudy' | 'overcast' | 'foggy' | 'misty' 
  | 'rainy' | 'stormy' | 'snowy' | 'hazy';

Style & Color Types

type ArtStyle = 'photorealistic' | 'hyperrealistic' | 'cinematic' | 'documentary'
  | 'editorial' | 'fashion' | 'portrait' | 'landscape' | 'street' | 'fine-art'
  | 'conceptual' | 'surreal' | 'abstract' | 'minimalist' | 'maximalist'
  | 'vintage' | 'retro' | 'noir' | 'gothic' | 'romantic'
  | 'impressionist' | 'expressionist' | 'pop-art' | 'art-nouveau' | 'art-deco'
  | 'cyberpunk' | 'steampunk' | 'fantasy' | 'sci-fi' | 'anime' | 'manga'
  | 'comic-book' | 'illustration' | 'digital-art' | 'oil-painting' | 'watercolor'
  | 'sketch' | 'pencil-drawing' | 'charcoal' | 'pastel' | '3d-render';

type ColorPalette = 'warm' | 'cool' | 'neutral' | 'vibrant' | 'muted' | 'pastel' | 'neon'
  | 'monochrome' | 'sepia' | 'desaturated' | 'high-contrast' | 'low-contrast'
  | 'earthy' | 'oceanic' | 'forest' | 'sunset' | 'midnight' | 'golden';

type Mood = 'serene' | 'peaceful' | 'melancholic' | 'dramatic' | 'tense' | 'mysterious'
  | 'romantic' | 'nostalgic' | 'hopeful' | 'joyful' | 'energetic' | 'chaotic'
  | 'ethereal' | 'dark' | 'light' | 'whimsical' | 'eerie' | 'epic' | 'intimate';

type AspectRatio = '1:1' | '4:3' | '3:2' | '16:9' | '21:9' | '9:16' | '2:3' | '4:5' | '5:4';

Methods Reference

Subject Methods

| Method | Signature | Description | |--------|-----------|-------------| | .subject() | subject(main: string \| ImageSubject) | Set main subject | | .subjectDetails() | subjectDetails(details: string[]) | Add subject details | | .expression() | expression(expression: string) | Set facial expression | | .pose() | pose(pose: string) | Set body pose | | .action() | action(action: string) | Set action/activity | | .clothing() | clothing(clothing: string) | Set clothing | | .accessories() | accessories(accessories: string[]) | Set accessories | | .subjectCount() | subjectCount(count) | Set subject count |

Environment Methods

| Method | Signature | Description | |--------|-----------|-------------| | .environment() | environment(setting: string \| ImageEnvironment) | Set environment | | .location() | location(location: string) | Set specific location | | .props() | props(props: string[]) | Set scene props | | .atmosphere() | atmosphere(atmosphere: string) | Set atmosphere | | .season() | season(season) | Set season |

Camera Methods

| Method | Signature | Description | |--------|-----------|-------------| | .camera() | camera(settings: ImageCamera) | Set all camera settings | | .shot() | shot(shot: ShotType) | Set shot type | | .angle() | angle(angle: CameraAngle) | Set camera angle | | .lens() | lens(lens: LensType) | Set lens type | | .focus() | focus(focus: FocusType) | Set focus type | | .aperture() | aperture(aperture: string) | Set aperture | | .bokeh() | bokeh(style: BokehStyle) | Set bokeh style | | .cameraBrand() | cameraBrand(brand: CameraBrand) | Set camera brand | | .cameraModel() | cameraModel(model: CameraModel) | Set camera model | | .sensor() | sensor(sensor: SensorFormat) | Set sensor format | | .lensBrand() | lensBrand(brand: LensBrand) | Set lens brand | | .lensModel() | lensModel(model: LensModel) | Set lens model | | .focalLength() | focalLength(length: string) | Set focal length | | .filmStock() | filmStock(stock: FilmStock) | Set film stock | | .filmFormat() | filmFormat(format: FilmFormat) | Set film format | | .filter() | filter(filter: FilterType) | Set lens filter | | .iso() | iso(iso: number) | Set ISO | | .shutterSpeed() | shutterSpeed(speed: string) | Set shutter speed | | .whiteBalance() | whiteBalance(wb) | Set white balance | | .colorProfile() | colorProfile(profile: string) | Set color profile |

Lighting Methods

| Method | Signature | Description | |--------|-----------|-------------| | .lighting() | lighting(settings: ImageLighting) | Set all lighting | | .lightingType() | lightingType(type) | Set lighting type(s) | | .timeOfDay() | timeOfDay(time: TimeOfDay) | Set time of day | | .weather() | weather(weather: WeatherLighting) | Set weather | | .lightDirection() | lightDirection(direction) | Set light direction | | .lightIntensity() | lightIntensity(intensity) | Set light intensity |

Composition Methods

| Method | Signature | Description | |--------|-----------|-------------| | .composition() | composition(settings: ImageComposition) | Set all composition | | .ruleOfThirds() | ruleOfThirds() | Enable rule of thirds | | .goldenRatio() | goldenRatio() | Enable golden ratio | | .symmetry() | symmetry(type) | Set symmetry type | | .foreground() | foreground(fg: string) | Set foreground | | .midground() | midground(mg: string) | Set midground | | .background() | background(bg: string) | Set background |

Style Methods

| Method | Signature | Description | |--------|-----------|-------------| | .style() | style(settings: ImageStyle) | Set all style settings | | .medium() | medium(medium: ArtStyle) | Set art style/medium | | .artist() | artist(artist: string \| string[]) | Set reference artist(s) | | .influence() | influence(influences: string[]) | Set style influences |

Color Methods

| Method | Signature | Description | |--------|-----------|-------------| | .color() | color(settings: ImageColor) | Set all color settings | | .palette() | palette(palette: ColorPalette) | Set color palette | | .primaryColors() | primaryColors(colors: string[]) | Set primary colors | | .accentColors() | accentColors(colors: string[]) | Set accent colors | | .colorGrade() | colorGrade(grade: string) | Set color grade |

Technical & Output Methods

| Method | Signature | Description | |--------|-----------|-------------| | .technical() | technical(settings: ImageTechnical) | Set all technical | | .aspectRatio() | aspectRatio(ratio: AspectRatio) | Set aspect ratio | | .resolution() | resolution(resolution: string) | Set resolution | | .quality() | quality(quality) | Set quality level | | .mood() | mood(mood: Mood \| Mood[]) | Set mood(s) | | .negative() | negative(items: string[]) | Add negative prompts | | .custom() | custom(text: string) | Add custom text | | .build() | build(): BuiltImagePrompt | Build the prompt | | .toString() | toString(): string | Get prompt string | | .toJSON() | toJSON(): string | Export as JSON | | .toYAML() | toYAML(): string | Export as YAML | | .toMarkdown() | toMarkdown(): string | Export as Markdown |

Output Structure

interface BuiltImagePrompt {
  prompt: string;           // Full formatted prompt with --no and --ar flags
  structure: {
    subject?: ImageSubject;
    camera?: ImageCamera;
    lighting?: ImageLighting;
    composition?: ImageComposition;
    style?: ImageStyle;
    color?: ImageColor;
    environment?: ImageEnvironment;
    technical?: ImageTechnical;
    mood?: Mood | Mood[];
    negative?: string[];
  };
}

Usage Examples

Portrait Photography

const portrait = image()
  .subject({
    main: "elderly fisherman",
    expression: "weathered but kind smile",
    age: "70s",
    clothing: "worn yellow raincoat"
  })
  .environment("misty harbor at dawn")
  .shot("close-up")
  .angle("eye-level")
  .lens("85mm")
  .focus("shallow")
  .aperture("f/1.8")
  .lightingType("natural")
  .timeOfDay("golden-hour")
  .medium("portrait")
  .filmStock("kodak-portra-400")
  .mood("nostalgic")
  .quality("masterpiece")
  .build();

Fantasy Illustration

const fantasy = image()
  .subject({
    main: "elven queen",
    expression: "regal and mysterious",
    pose: "seated on crystal throne",
    clothing: "flowing silver gown with starlight patterns",
    accessories: ["crown of moonstone", "ancient scepter"]
  })
  .environment({
    setting: "ethereal forest palace",
    atmosphere: "magical mist and floating lights",
    props: ["glowing flowers", "ancient trees"]
  })
  .medium(["fantasy", "illustration"])
  .artist(["Alan Lee", "Brian Froud"])
  .palette("cool")
  .primaryColors(["silver", "deep blue", "violet"])
  .lightingType("soft")
  .mood(["ethereal", "mysterious"])
  .aspectRatio("2:3")
  .quality("ultra")
  .negative(["modern elements", "technology"])
  .build();

Product Photography

const product = image()
  .subject("luxury mechanical watch")
  .subjectDetails(["intricate movement visible", "sapphire crystal"])
  .environment("minimalist studio setup")
  .props(["black velvet", "subtle reflections"])
  .shot("extreme-close-up")
  .lens("macro")
  .focus("tack-sharp")
  .aperture("f/8")
  .lightingType(["studio", "rim"])
  .lightDirection("side")
  .lightIntensity("soft")
  .medium("commercial")
  .palette("monochrome")
  .colorGrade("high contrast, deep blacks")
  .aspectRatio("1:1")
  .resolution("8K")
  .quality("masterpiece")
  .build();

Cinematic Landscape

const landscape = image()
  .environment({
    setting: "volcanic Iceland highlands",
    location: "Landmannalaugar",
    terrain: "colorful rhyolite mountains",
    atmosphere: "dramatic storm clouds breaking"
  })
  .season("summer")
  .shot("extreme-wide")
  .angle("aerial")
  .lens("wide-angle")
  .cameraBrand("hasselblad")
  .cameraModel("hasselblad-x2d")
  .sensor("medium-format")
  .timeOfDay("golden-hour")
  .weather("stormy")
  .lightingType("dramatic")
  .medium("landscape")
  .palette(["earthy", "vibrant"])
  .primaryColors(["rust red", "moss green", "volcanic black"])
  .mood(["epic", "dramatic"])
  .aspectRatio("21:9")
  .quality("ultra")
  .build();

🎬 Video Builder

Comprehensive builder for video generation prompts. Works with Sora, Runway, Pika, Kling, and other video AI platforms.

Quick Start

import { video } from 'prompts.chat';

const prompt = video()
  .scene("A samurai walks through a bamboo forest")
  .camera({ movement: "tracking", angle: "low-angle" })
  .lighting({ time: "golden-hour", type: "natural" })
  .duration(5)
  .build();

console.log(prompt.prompt);

Full Example

import { video } from 'prompts.chat';

const prompt = video()
  // ━━━ Scene ━━━
  .scene({
    description: "A lone astronaut walks across the Martian surface",
    setting: "Olympus Mons base camp",
    atmosphere: "dusty red landscape, thin atmosphere"
  })
  .setting("Mars, near the base camp")     // Additional location context
  .timeOfDay("golden-hour")                // dawn | sunrise | golden-hour | midday | blue-hour | night | ...
  .weather("foggy")                        // sunny | cloudy | overcast | foggy | rainy | stormy | snowy | ...
  
  // ━━━ Subject ━━━
  .subject({
    main: "astronaut",
    appearance: "NASA spacesuit with reflective gold visor",
    clothing: "white EVA suit with mission patches",
    age: "30s",
    gender: "female"
  })
  .appearance("determined expression")     // Additional appearance details
  .clothing("dusty, worn spacesuit")       // Override/add clothing
  
  // ━━━ Camera: Framing ━━━
  .shot("wide")                            // extreme-close-up | close-up | medium | wide | establishing | ...
  .angle("low-angle")                      // eye-level | low-angle | high-angle | dutch-angle | birds-eye | ...
  .lens("anamorphic")                      // wide-angle | 35mm | 50mm | 85mm | telephoto | anamorphic | ...
  .focalLength("40mm")                     // Specific focal length
  .anamorphic("2x")                        // Enable anamorphic with ratio
  .aperture("f/2.8")                       // Aperture setting
  
  // ━━━ Camera: Movement ━━━
  .movement("tracking")                    // static | pan | tilt | dolly | tracking | crane | steadicam | ...
  .cameraSpeed("slow")                     // slow | medium | fast
  .movementDirection("forward")            // left | right | forward | backward | up | down | arc-left | arc-right
  .platform("steadicam")                   // handheld | steadicam | tripod | drone | crane | gimbal | dolly | ...
  .rig("slider")                           // tripod | gimbal | steadicam | crane | dolly | slider | ...
  .gimbal("dji-ronin-4d")                  // Specific gimbal model
  
  // ━━━ Camera: Equipment ━━━
  .cameraBrand("arri")                     // arri | red | sony | canon | blackmagic | panavision | ...
  .cameraModel("arri-alexa-65")            // Specific camera model
  .sensor("65mm")                          // full-frame | super-35 | 65mm | imax | ...
  .lensBrand("cooke")                      // zeiss | cooke | arri | panavision | ...
  .lensModel("cooke-anamorphic")           // Specific lens model
  
  // ━━━ Camera: Technical ━━━
  .frameRate(24)                           // 24 | 25 | 30 | 48 | 60 | 120 | 240
  .slowMotion()                            // Enable slow motion
  .shutterAngle(180)                       // Shutter angle in degrees
  .filter("black-pro-mist")                // nd | polarizer | black-pro-mist | diffusion | ...
  .filmStock("kodak-vision3-500t")         // Kodak, Fujifilm, CineStill film stocks
  .filmGrain("subtle")                     // none | subtle | moderate | heavy
  .halation()                              // Enable film halation effect
  
  // ━━━ Lighting ━━━
  .lighting({
    type: "natural",
    time: "golden-hour",
    direction: "back",
    intensity: "soft"
  })
  .lightingType(["natural", "rim"])        // natural | studio | dramatic | rim | rembrandt | ...
  
  // ━━━ Actions ━━━
  .action("walks slowly toward camera")                    // Add action beat
  .action("stops and looks at horizon", { timing: "middle" })
  .action("raises hand to shield eyes", { timing: "end" })
  .actions(["turns around", "begins walking back"])        // Add multiple actions
  
  // ━━━ Motion ━━━
  .motion({
    subject: "astronaut",
    type: "walk",
    direction: "forward",
    speed: "slow"
  })
  .motionBeats(["step", "pause", "step", "turn"])          // Detailed motion beats
  
  // ━━━ Style ━━━
  .style({
    format: "cinematic",
    era: "2020s",
    look: "cinematic"
  })
  .look("cinematic")                       // photorealistic | cinematic | documentary | sci-fi | noir | ...
  .era("futuristic")                       // 1970s | 1980s | modern | futuristic | ...
  .format("widescreen epic")               // Format description
  .styleFilmStock("Kodak Vision3 500T")    // Style reference film stock
  .reference(["Interstellar", "The Martian", "Gravity"])   // Reference films/directors
  
  // ━━━ Color ━━━
  .color({
    palette: "warm",
    temperature: "warm",
    grade: "orange and teal"
  })
  .palette("warm")                         // warm | cool | neutral | vibrant | neon | monochrome | ...
  .colorAnchors(["mars red", "suit white", "visor gold"])  // Key colors
  .colorGrade("orange and teal")           // Color grading style
  
  // ━━━ Audio ━━━
  .audio({
    ambient: "wind howling",
    music: "epic orchestral, building tension",
    dialogue: "breathing sounds in helmet"
  })
  .dialogue("Houston, I've arrived at the site")           // Character dialogue
  .ambient("martian wind, distant rumbling")               // Ambient sounds
  .diegetic(["footsteps on gravel", "suit servos"])        // In-world sounds
  .soundEffects(["radio static", "helmet HUD beeps"])      // Sound effects
  .music("Hans Zimmer style, building brass")              // Music description
  
  // ━━━ Technical ━━━
  .technical({
    duration: 10,
    resolution: "4K",
    fps: 24,
    aspectRatio: "21:9"
  })
  .duration(10)                            // Duration in seconds
  .resolution("4K")                        // 480p | 720p | 1080p | 4K
  .fps(24)                                 // 24 | 30 | 60
  .aspectRatio("21:9")                     // 16:9 | 9:16 | 1:1 | 4:3 | 21:9
  
  // ━━━ Mood & Pacing ━━━
  .mood(["epic", "mysterious"])            // serene | dramatic | tense | epic | intimate | ...
  .pacing("slow")                          // slow | medium | fast | variable | building | contemplative
  .transition("fade")                      // cut | fade | dissolve | wipe | morph | match-cut | ...
  .transitions(["fade", "dissolve"])       // Multiple transitions
  
  // ━━━ Shot List ━━━
  .addShot({
    name: "Opening wide",
    camera: { shot: "extreme-wide", movement: "static" },
    action: "Establish the Martian landscape",
    purpose: "Set the scene"
  })
  .shotList([
    { camera: { shot: "medium", movement: "tracking" }, action: "Follow astronaut" },
    { camera: { shot: "close-up", angle: "low-angle" }, action: "Hero shot" }
  ])
  
  // ━━━ Custom ━━━
  .custom("Lens flare as sun peeks over horizon")
  .custom("Dust particles visible in backlight")
  
  .build();

// Access outputs
console.log(prompt.prompt);       // Full formatted prompt
console.log(prompt.structure);    // Full structured data object

// Export formats
const yaml = prompt.toYAML();
const json = prompt.toJSON();
const md = prompt.toMarkdown();

Types Reference

Camera Types

type ShotType = 'extreme-close-up' | 'close-up' | 'medium-close-up' | 'medium' 
  | 'medium-wide' | 'wide' | 'extreme-wide' | 'establishing' | 'full-body' | 'portrait' | 'headshot';

type CameraAngle = 'eye-level' | 'low-angle' | 'high-angle' | 'dutch-angle' | 'birds-eye' 
  | 'worms-eye' | 'over-the-shoulder' | 'point-of-view' | 'aerial' | 'drone'
  | 'canted' | 'oblique' | 'hip-level' | 'knee-level' | 'ground-level';

type CameraMovement = 'static' | 'pan' | 'tilt' | 'dolly' | 'truck' | 'pedestal' | 'zoom' 
  | 'handheld' | 'steadicam' | 'crane' | 'drone' | 'tracking' | 'arc' | 'whip-pan'
  | 'roll' | 'boom' | 'jib' | 'cable-cam' | 'motion-control' | 'snorricam'
  | 'dutch-roll' | 'vertigo-effect' | 'crash-zoom' | 'slow-push' | 'slow-pull';

type LensType = 'wide-angle' | 'ultra-wide' | 'standard' | 'telephoto' | 'macro' | 'fisheye'
  | '14mm' | '24mm' | '35mm' | '50mm' | '85mm' | '100mm' | '135mm' | '200mm'
  | 'tilt-shift' | 'anamorphic' | 'spherical' | 'prime' | 'zoom';

Equipment Types

type CameraBrand = 'sony' | 'canon' | 'nikon' | 'fujifilm' | 'leica' | 'hasselblad' 
  | 'red' | 'arri' | 'blackmagic' | 'panavision' | 'panasonic';

type CameraModel = 'arri-alexa-35' | 'arri-alexa-mini-lf' | 'arri-alexa-65'
  | 'red-v-raptor' | 'red-komodo' | 'sony-venice' | 'sony-fx6'
  | 'canon-c70' | 'blackmagic-ursa-mini-pro' | 'panavision-dxl2' | ...;

type CameraRig = 'tripod' | 'monopod' | 'gimbal' | 'steadicam' | 'easyrig' | 'shoulder-rig'
  | 'slider' | 'dolly' | 'jib' | 'crane' | 'technocrane' | 'russian-arm'
  | 'cable-cam' | 'drone' | 'fpv-drone' | 'motion-control' | 'handheld';

type GimbalModel = 'dji-ronin-4d' | 'dji-ronin-rs3-pro' | 'dji-ronin-rs4' 
  | 'moza-air-2' | 'zhiyun-crane-3s' | 'freefly-movi-pro' | 'tilta-gravity-g2x';

Lighting Types

type LightingType = 'natural' | 'studio' | 'dramatic' | 'soft' | 'hard' | 'diffused'
  | 'key' | 'fill' | 'rim' | 'backlit' | 'silhouette' | 'rembrandt'
  | 'split' | 'butterfly' | 'loop' | 'broad' | 'short' | 'chiaroscuro'
  | 'high-key' | 'low-key' | 'three-point' | 'practical' | 'motivated';

type TimeOfDay = 'dawn' | 'sunrise' | 'golden-hour' | 'morning' | 'midday' | 'afternoon'
  | 'blue-hour' | 'sunset' | 'dusk' | 'twilight' | 'night' | 'midnight';

type WeatherLighting = 'sunny' | 'cloudy' | 'overcast' | 'foggy' | 'misty' 
  | 'rainy' | 'stormy' | 'snowy' | 'hazy';

Style & Color Types

type ArtStyle = 'photorealistic' | 'hyperrealistic' | 'cinematic' | 'documentary'
  | 'editorial' | 'fashion' | 'portrait' | 'landscape' | 'street' | 'fine-art'
  | 'surreal' | 'abstract' | 'minimalist' | 'vintage' | 'retro' | 'noir'
  | 'cyberpunk' | 'steampunk' | 'fantasy' | 'sci-fi' | 'anime' | '3d-render';

type ColorPalette = 'warm' | 'cool' | 'neutral' | 'vibrant' | 'muted' | 'pastel' | 'neon'
  | 'monochrome' | 'sepia' | 'desaturated' | 'high-contrast' | 'low-contrast'
  | 'earthy' | 'oceanic' | 'forest' | 'sunset' | 'midnight' | 'golden';

type Mood = 'serene' | 'peaceful' | 'melancholic' | 'dramatic' | 'tense' | 'mysterious'
  | 'romantic' | 'nostalgic' | 'hopeful' | 'joyful' | 'energetic' | 'chaotic'
  | 'ethereal' | 'dark' | 'light' | 'whimsical' | 'eerie' | 'epic' | 'intimate';

type FilmStock = 'kodak-portra-400' | 'kodak-vision3-500t' | 'kodak-vision3-50d'
  | 'fujifilm-eterna-500t' | 'cinestill-800t' | 'ilford-hp5-plus' | ...;

Video-Specific Types

type VideoPacing = 'slow' | 'medium' | 'fast' | 'variable' | 'building' | 'frenetic' | 'contemplative';

type VideoTransition = 'cut' | 'fade' | 'dissolve' | 'wipe' | 'morph' | 'match-cut' 
  | 'jump-cut' | 'cross-dissolve' | 'iris' | 'push' | 'slide';

type FilterType = 'uv' | 'polarizer' | 'nd' | 'nd-graduated' | 'black-pro-mist' 
  | 'white-pro-mist' | 'glimmer-glass' | 'classic-soft' | 'diffusion' | 'infrared';

Methods Reference

Scene Methods

| Method | Signature | Description | |--------|-----------|-------------| | .scene() | scene(description: string \| VideoScene) | Set scene description | | .setting() | setting(setting: string) | Set location/setting | | .timeOfDay() | timeOfDay(time: TimeOfDay) | Set time of day | | .weather() | weather(weather: WeatherLighting) | Set weather conditions |

Subject Methods

| Method | Signature | Description | |--------|-----------|-------------| | .subject() | subject(main: string \| VideoSubject) | Set main subject | | .appearance() | appearance(appearance: string) | Set appearance details | | .clothing() | clothing(clothing: string) | Set clothing/costume |

Camera Methods

| Method | Signature | Description | |--------|-----------|-------------| | .camera() | camera(settings: VideoCamera) | Set all camera settings | | .shot() | shot(shot: ShotType) | Set shot type | | .angle() | angle(angle: CameraAngle) | Set camera angle | | .movement() | movement(movement: CameraMovement) | Set camera movement | | .lens() | lens(lens: LensType) | Set lens type | | .platform() | platform(platform) | Set camera platform | | .cameraSpeed() | cameraSpeed(speed) | Set movement speed | | .movementDirection() | movementDirection(direction) | Set movement direction | | .rig() | rig(rig: CameraRig) | Set camera rig | | .gimbal() | gimbal(gimbal: GimbalModel) | Set gimbal model | | .cameraBrand() | cameraBrand(brand: CameraBrand) | Set camera brand | | .cameraModel() | cameraModel(model: CameraModel) | Set camera model | | .sensor() | sensor(sensor: SensorFormat) | Set sensor format | | .lensBrand() | lensBrand(brand: LensBrand) | Set lens brand | | .lensModel() | lensModel(model: LensModel) | Set lens model | | .focalLength() | focalLength(length: string) | Set focal length | | .anamorphic() | anamorphic(ratio?) | Enable anamorphic | | .aperture() | aperture(aperture: string) | Set aperture | | .frameRate() | frameRate(fps) | Set frame rate | | .slowMotion() | slowMotion(enabled?) | Enable slow motion | | .shutterAngle() | shutterAngle(angle: number) | Set shutter angle | | .filter() | filter(filter: FilterType) | Set lens filter | | .filmStock() | filmStock(stock: FilmStock) | Set film stock | | .filmGrain() | filmGrain(grain) | Set film grain level | | .halation() | halation(enabled?) | Enable halation effect |

Lighting Methods

| Method | Signature | Description | |--------|-----------|-------------| | .lighting() | lighting(settings: VideoLighting) | Set all lighting | | .lightingType() | lightingType(type) | Set lighting type(s) |

Action & Motion Methods

| Method | Signature | Description | |--------|-----------|-------------| | .action() | action(action, options?) | Add single action | | .actions() | actions(actions: string[]) | Add multiple actions | | .motion() | motion(settings: VideoMotion) | Set motion settings | | .motionBeats() | motionBeats(beats: string[]) | Set motion beats |

Style Methods

| Method | Signature | Description | |--------|-----------|-------------| | .style() | style(settings: VideoStyle) | Set all style settings | | .look() | look(look: ArtStyle) | Set visual look | | .era() | era(era: string) | Set era/time period | | .format() | format(format: string) | Set format description | | .styleFilmStock() | styleFilmStock(stock: string) | Set style film stock | | .reference() | reference(refs: string[]) | Set reference films |

Color Methods

| Method | Signature | Description | |--------|--------