@sogni-ai/sogni-intelligence-client 3.0.0-alpha.0

package/dist-esm/tools/definitions/apply-style/definition.js

@@ -0,0 +1,47 @@
+import { LITERAL_PROMPT_OVERRIDE } from '../../../contracts/promptOverrideMarker.js';
+import { ASPECT_RATIO_DESCRIPTION } from '../../../media/index.js';
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'apply_style',
+        description: 'Apply an artistic style, era-specific look, or creative transformation to a photo. Use when the user wants to change the visual style (e.g., "make it look like the 70s", "oil painting style", "vintage polaroid look"). Can handle any creative transformation. One style per call. IMPORTANT: When previous results exist, this tool automatically uses the LATEST result image unless you specify a different sourceImageIndex or the user explicitly says "original". So just call it without sourceImageIndex for follow-up requests.',
+        parameters: {
+            type: 'object',
+            properties: {
+                prompt: {
+                    type: 'string',
+                    description: `Style prompt for Qwen Image Edit 2511 (50-200 words, natural language sentences).
+
+${LITERAL_PROMPT_OVERRIDE}
+
+PROMPT ORDER: [IDENTITY LOCK if people] → [STYLE TRANSFER INSTRUCTION] → [PRESERVE UNMENTIONED DETAILS]
+
+Rules:
+- Use POSITIVE phrasing only. The model ignores negatives ("preserve exact facial likeness" NOT "don't change the face").
+- Transfer the visual STYLE ONLY, not the identity. Borrow palette, texture, contrast behavior, and stylistic treatment — NOT face structure.
+- Reference known art styles, artists, and franchises BY NAME to anchor the style — be specific, never generic.
+- Describe specific visual characteristics: brushstrokes, color palette, texture, composition approach, mood.
+- For era looks: describe the photographic qualities of that era (e.g., "warm faded Kodachrome tones with soft vignette, typical of 1970s amateur photography").
+- CRITICAL for photos with people: FRONT-LOAD identity preservation BEFORE the style instruction. Start with "Preserve exact facial likeness, face structure, eye shape, nose shape, mouth shape, jawline, skin tone, hairline, apparent age, and overall recognizability." Then describe the style. End with "Keep the subject recognizable as the same person. Maintain exact positioning, poses, and composition."
+- Go bold with pop culture and iconic styles: "Andy Warhol pop art with bold neon screen-print colors", "Banksy stencil street art with gritty urban textures", "Studio Ghibli watercolor with soft pastoral warmth", "Pixar 3D render with glossy skin and exaggerated features", "Tim Burton gothic with pale skin and dark spiraling backgrounds", "Van Gogh Starry Night with thick impasto swirls and vibrant blues", "Takashi Murakami superflat with psychedelic flowers and bold outlines".
+- Always end with "Preserve the subject's identity, pose, and composition."`,
+                },
+                sourceImageIndex: {
+                    type: 'number',
+                    description: 'Which result image to apply the style to (0-based index). Omit to use the latest result automatically (or the original if no results exist). Only set explicitly when the user specifies a particular image number or explicitly says "original" (use -1 for original).',
+                },
+                scale: {
+                    type: 'number',
+                    enum: [1, 1.5, 2, 3, 4],
+                    description: 'Output scale multiplier relative to the source image size. 1 = same resolution as source (default). Use higher values when user asks to upscale, enlarge, make bigger, or increase resolution. Small images (<480px) are automatically upscaled to at least 480px regardless of this setting. Default: 1.',
+                },
+                aspectRatio: {
+                    type: 'string',
+                    description: ASPECT_RATIO_DESCRIPTION,
+                },
+            },
+            required: ['prompt'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/apply-style/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/apply-style/definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,6gBAA6gB;QAC/gB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;EAErB,uBAAuB;;;;;;;;;;;;4EAYmD;iBACnE;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,yQAAyQ;iBAC5Q;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;oBACvB,WAAW,EACT,2SAA2S;iBAC9S;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;CACF,CAAC"}

package/dist-esm/tools/definitions/change-angle/definition.js

@@ -0,0 +1,46 @@
+import { ASPECT_RATIO_DESCRIPTION } from '../../../media/index.js';
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'change_angle',
+        description: 'Generate the photo from a different camera angle or perspective. Uses AI to create a new view of the subject as if photographed from a different position. Use when the user wants to see the subject from another angle, generate a different view, create a portrait from a specific direction, or get a closeup/wide shot. Examples: "show me from the left side", "generate a 3/4 portrait view", "closeup from slightly above". IMPORTANT: When previous results exist, this tool automatically uses the LATEST result image unless you specify a different sourceImageIndex or the user explicitly says "original".',
+        parameters: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: `EXACT camera angle string. You MUST construct this by concatenating exactly one value from each category below, separated by single spaces. No commas, no extra words.
+
+Format: "[azimuth] [elevation] [distance]"
+
+Azimuth (pick one): "front view", "front-right quarter view", "right side view", "back-right quarter view", "back view", "back-left quarter view", "left side view", "front-left quarter view"
+Elevation (pick one): "low-angle shot", "eye-level shot", "elevated shot", "high-angle shot"
+Distance (pick one): "close-up", "medium shot", "wide shot"
+
+Examples:
+- "front-right quarter view eye-level shot medium shot"
+- "left side view eye-level shot close-up"
+- "front view low-angle shot wide shot"
+- "right side view elevated shot medium shot"
+
+Map user requests: "from the left" → "left side view", "looking up at" → "low-angle shot", "closeup" → "close-up", "3/4 view" → "front-right quarter view" or "front-left quarter view", "portrait" → "front-right quarter view eye-level shot medium shot".
+Default elevation to "eye-level shot" and distance to "medium shot" when not specified.`,
+                },
+                sourceImageIndex: {
+                    type: 'number',
+                    description: 'Which result image to use as source (0-based index). Omit to use the latest result automatically (or the original if no results exist). Only set explicitly when the user specifies a particular image number or explicitly says "original" (use -1 for original).',
+                },
+                loraStrength: {
+                    type: 'number',
+                    description: 'LoRA strength for angle generation (0.1-1.0). Default: 0.9. Lower values preserve more of the original appearance, higher values produce stronger angle changes. Only set when the user wants to control the transformation intensity.',
+                },
+                aspectRatio: {
+                    type: 'string',
+                    description: ASPECT_RATIO_DESCRIPTION,
+                },
+            },
+            required: ['description'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/change-angle/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/change-angle/definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,2lBAA2lB;QAC7lB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;;;;;;;;;;;;;;wFAeiE;iBAC/E;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,oQAAoQ;iBACvQ;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,wOAAwO;iBAC3O;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,CAAC;SAC1B;KACF;CACF,CAAC"}

package/dist-esm/tools/definitions/dance-montage/dances.js

@@ -0,0 +1,86 @@
+const CDN_BASE = 'https://cdn.sogni.ai/video-samples';
+export const DANCE_PRESETS = [
+    {
+        id: 'rasputin',
+        title: 'Boney M - Rasputin',
+        description: 'Viral Russian TikTok Dance',
+        videoUrl: `${CDN_BASE}/rasputin.mp4`,
+        maxDuration: 32,
+    },
+    {
+        id: 'big-guy',
+        title: 'Ice Spice - Big Guy',
+        description: 'From "The SpongeBob Movie: Search for SquarePants" movie',
+        videoUrl: `${CDN_BASE}/big-guy-dance.mp4`,
+        maxDuration: 11,
+    },
+    {
+        id: 'keep-it-gangsta',
+        title: 'Nhale ft. Dezzy Hollow - Keep it Gangsta',
+        description: 'Hip-hop gangsta dance',
+        videoUrl: `${CDN_BASE}/dance-keep-it-gangsta.mp4`,
+        maxDuration: 21,
+    },
+    {
+        id: 'this-is-america',
+        title: 'Childish Gambino - This Is America',
+        description: 'Iconic choreography from the This Is America music video',
+        videoUrl: `${CDN_BASE}/this-is-america.mp4`,
+        maxDuration: 22,
+    },
+    {
+        id: 'chinese-new-year',
+        title: '弥渡山歌 (Midu Echoing) - Dan Thy',
+        description: 'Chinese New Year Dance, Chinese Military Dance Trend',
+        videoUrl: `${CDN_BASE}/chinese-new-year-dance.mp4`,
+        maxDuration: 18,
+    },
+    {
+        id: 'spongebob',
+        title: 'SpongeBob - Stadium Rave',
+        description: 'Jellyfish Jam Dance from SpongeBob SquarePants',
+        videoUrl: `${CDN_BASE}/spongebob-dance.mp4`,
+        maxDuration: 27,
+    },
+    {
+        id: 'chanel',
+        title: 'Tyla - Chanel',
+        description: 'Put me in Chanel dance',
+        videoUrl: `${CDN_BASE}/chanel.mp4`,
+        maxDuration: 14,
+    },
+    {
+        id: 'crystal-light-aerobics-1988',
+        title: 'Crystal Light National Aerobics Championship 1988',
+        description: '80s aerobics dance from the 1988 Crystal Light National Aerobics Championship',
+        videoUrl: `${CDN_BASE}/crystal-light-aerobics-1988.mp4`,
+        maxDuration: 52,
+    },
+    {
+        id: 'plastic-dream-sequence',
+        title: 'Metric - Black Sheep',
+        description: 'Barbie plastic dream sequence dance',
+        videoUrl: `${CDN_BASE}/plastic-dream-sequence-centered.mp4`,
+        maxDuration: 28,
+        aliases: ['metric', 'black sheep', 'barbie', 'plastic dream'],
+    },
+];
+export function resolveDancePresetForRequest(text, args) {
+    const explicitDance = typeof args?.dance === 'string' ? args.dance.trim() : '';
+    if (explicitDance) {
+        return DANCE_PRESETS.find(preset => preset.id === explicitDance) || null;
+    }
+    if (!text)
+        return null;
+    for (const preset of DANCE_PRESETS) {
+        if (!preset.aliases?.length)
+            continue;
+        for (const alias of preset.aliases) {
+            const escaped = alias.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+            if (new RegExp(`\\b${escaped}\\b`, 'i').test(text))
+                return preset;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=dances.js.map

package/dist-esm/tools/definitions/dance-montage/dances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dances.js","sourceRoot":"","sources":["../../../../src/tools/definitions/dance-montage/dances.ts"],"names":[],"mappings":"AAoBA,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAEtD,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EAAE,4BAA4B;QACzC,QAAQ,EAAE,GAAG,QAAQ,eAAe;QACpC,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,0DAA0D;QACvE,QAAQ,EAAE,GAAG,QAAQ,oBAAoB;QACzC,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,0CAA0C;QACjD,WAAW,EAAE,uBAAuB;QACpC,QAAQ,EAAE,GAAG,QAAQ,4BAA4B;QACjD,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EAAE,0DAA0D;QACvE,QAAQ,EAAE,GAAG,QAAQ,sBAAsB;QAC3C,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,+BAA+B;QACtC,WAAW,EAAE,sDAAsD;QACnE,QAAQ,EAAE,GAAG,QAAQ,6BAA6B;QAClD,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,0BAA0B;QACjC,WAAW,EAAE,gDAAgD;QAC7D,QAAQ,EAAE,GAAG,QAAQ,sBAAsB;QAC3C,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,wBAAwB;QACrC,QAAQ,EAAE,GAAG,QAAQ,aAAa;QAClC,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,6BAA6B;QACjC,KAAK,EAAE,mDAAmD;QAC1D,WAAW,EAAE,+EAA+E;QAC5F,QAAQ,EAAE,GAAG,QAAQ,kCAAkC;QACvD,WAAW,EAAE,EAAE;KAChB;IACD;QACE,EAAE,EAAE,wBAAwB;QAC5B,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EAAE,qCAAqC;QAClD,QAAQ,EAAE,GAAG,QAAQ,sCAAsC;QAC3D,WAAW,EAAE,EAAE;QACf,OAAO,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,CAAC;KAC9D;CACF,CAAC;AASF,MAAM,UAAU,4BAA4B,CAC1C,IAAY,EACZ,IAA8B;IAE9B,MAAM,aAAa,GAAG,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,aAAa,CAAC,IAAI,IAAI,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM;YAAE,SAAS;QACtC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACrF,IAAI,IAAI,MAAM,CAAC,MAAM,OAAO,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,MAAM,CAAC;QACpE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist-esm/tools/definitions/dance-montage/definition.js

@@ -0,0 +1,42 @@
+import { DANCE_PRESETS } from './dances.js';
+const danceEnum = DANCE_PRESETS.map(d => d.id);
+const danceParamDesc = DANCE_PRESETS
+    .map(d => `"${d.id}": ${d.title} (${d.description}, max ${d.maxDuration}s).`)
+    .join(' ');
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'dance_montage',
+        description: 'REQUIRED for ALL dance video requests — do NOT use animate_photo or generate_video for dances. Uses real choreography reference videos to transfer dance motion onto a photo via WAN 2.2 Animate Move. Output is always 9:16 480p portrait. Do NOT use this for bare TikTok/Reels/Shorts/social-video requests unless the user explicitly asks for a dance, choreography, dance trend, or named dance preset. UPLOADED PHOTO: When the user asks for a dance "using this photo" or "with this photo", call dance_montage directly on the uploaded photo; do NOT call edit_image/generate_image first just to prepare, stylize, restyle, reframe, make full-body, or reinterpret the subject. Words that identify a dance preset or vibe, such as "Barbie", "Metric", "Black Sheep", "Rasputin", or "TikTok dance trend", are NOT requests for image prep. Only create image prep first when the user explicitly asks for a new look, outfit, variation set, multiple characters, or loaded persona identity preservation. IMAGE PREP: When generating images for dance (via edit_image or generate_image), ALWAYS use aspectRatio="9:16". CRITICAL — IMAGE COUNT: Generate exactly 1 image (numberOfVariations=1) for dance requests UNLESS the user explicitly asks for variations, different looks, or multiple characters (e.g. "4 different outfits", "alternate between a cat and a dog"). A single consistent image is used for ALL video segments to ensure visual consistency in the final stitched dance video. When the user DOES request multiple variations, batch them into ONE tool call using numberOfVariations + Dynamic Prompts — never split into multiple batches. PERSONAS: When personas are loaded, ALWAYS generate images via edit_image FIRST (using the persona reference photos for identity preservation), then call dance_montage — it will automatically use all generated images. Never use imagePrompt for persona dance requests — edit_image with persona context photos produces far better likeness. USING GENERATED IMAGES: When images have already been generated earlier in the conversation, simply call dance_montage WITHOUT sourceImageIndex — all previously generated images are used automatically as alternating montage segments. Do NOT tell the user to "upload" images that were already generated. Requires at least one uploaded photo, previously generated image, or loaded personas. Best results with photos of people.',
+        parameters: {
+            type: 'object',
+            properties: {
+                dance: {
+                    type: 'string',
+                    enum: danceEnum,
+                    description: `Which dance choreography to use. ${danceParamDesc}.`,
+                },
+                duration: {
+                    type: 'number',
+                    description: 'Total video duration in seconds. Range: 8-30. OMIT this parameter unless the user explicitly requests a specific length — the handler defaults to the chosen dance\'s reference video length (capped at 30s) so the full choreography plays through. Each dance has its own max based on its reference video; the handler caps automatically.',
+                    minimum: 8,
+                    maximum: 30,
+                },
+                sourceImageIndex: {
+                    type: 'number',
+                    description: 'Which previously generated result image to use (0-based index). Use -1 for the original uploaded image. When omitted, all previously generated images are used automatically as alternating montage segments.',
+                },
+                imagePrompt: {
+                    type: 'string',
+                    description: 'Creative style/look for auto-generated images when no pre-generated images are available and no personas are loaded. For persona requests, always generate images via edit_image first — it preserves identity far better. This is a fallback only. If omitted, uses a default full-body portrait style.',
+                },
+                singleClip: {
+                    type: 'boolean',
+                    description: 'When true, renders the entire dance as one continuous clip (no stitching). Only works for durations ≤ 20s. Use when the user explicitly asks for a single video or one unbroken clip. Default: false (splits into segments for faster concurrent rendering).',
+                },
+            },
+            required: ['dance'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/dance-montage/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/dance-montage/definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAE/C,MAAM,cAAc,GAAG,aAAa;KACjC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,WAAW,SAAS,CAAC,CAAC,WAAW,KAAK,CAAC;KAC5E,IAAI,CAAC,GAAG,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,m1EAAm1E;QACr1E,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,oCAAoC,cAAc,GAAG;iBACnE;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,+UAA+U;oBACjV,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;iBACZ;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,+MAA+M;iBAClN;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,0SAA0S;iBAC7S;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,8PAA8P;iBACjQ;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;CACF,CAAC"}

package/dist-esm/tools/definitions/edit-image/definition.js

@@ -0,0 +1,125 @@
+import { LITERAL_PROMPT_OVERRIDE } from '../../../contracts/promptOverrideMarker.js';
+import { ASPECT_RATIO_DESCRIPTION } from '../../../media/index.js';
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'edit_image',
+        description: 'Generate images guided by reference photos. Supports GPT Image 2 up to 16 images, Flux.2 up to 6 images, and Qwen up to 3 images. Best for style-guided generation, combining elements from multiple images, ANY persona image creation, and any uploaded brand asset reuse — logos, brand marks, mascots, product shots, photos, screenshots, sketches, or character designs the user expects to appear in or guide the result. ALWAYS use this (never generate_image) when persona photos OR uploaded image assets meant for reuse are in context — even if a specific model is requested. Exception: explicit Z-image/Z-image Turbo uploaded-image enhancement uses generate_image with sourceImageIndex and starting_image_strength because edit_image does not expose Z-image models. If a previous edit_image attempt did not preserve the uploaded asset well, stay on edit_image and tighten the prompt or switch model — do not fall back to generate_image, which has no access to the upload at all. For direct edits (remove objects, enhance), use restore_photo or refine_result unless the user explicitly requested Z-image.',
+        parameters: {
+            type: 'object',
+            properties: {
+                prompt: {
+                    type: 'string',
+                    description: `Edit instruction describing what to generate using the reference images as guidance. 50-200 words recommended.
+
+${LITERAL_PROMPT_OVERRIDE}
+
+PROMPT CONSTRUCTION ORDER — build the prompt in this sequence:
+1. IDENTITY LOCK — state which picture owns the person's identity (GOLDEN RULE: never leave identity ambiguous when editing a person)
+2. REQUESTED EDIT — describe only what CHANGES (the delta), not the whole image
+3. REFERENCE ROLE MAPPING — assign each picture ONE primary role: base_identity (face/person), pose_reference, outfit_reference, style_reference, background_reference, or color_reference
+4. POSE / COMPOSITION — pose, framing, camera angle (omit if unchanged)
+5. STYLE — artistic style, genre, era (omit if unchanged)
+6. LIGHTING / REALISM — "maintain realistic anatomy, perspective, and lighting integration"
+7. PRESERVE clause — always end with "preserve all unmentioned details"
+
+IDENTITY LOCK (required when a person is in any reference image):
+"Preserve the exact facial likeness from picture N — face structure, eye shape, nose shape, mouth shape, jawline, skin tone, hairline, apparent age, and overall recognizability."
+Never let a style, pose, or clothing reference silently override the face. If multiple images are provided, explicitly state "identity comes only from picture N — do not borrow identity from other pictures."
+
+MINIMAL-CHANGE PRINCIPLE: The base image already contains the subject, composition, camera angle, expression, lighting, and background. Describe only the delta. Use positive constraints ("preserve exact facial likeness") not negative ones ("don't change the face").
+
+SINGLE-IMAGE PATTERN:
+"Preserve the exact facial likeness and recognizability of the person from picture 1. [Describe only the requested change]. Keep the same pose, framing, camera angle, and expression unless the user specifically requests changes to these. Preserve all unmentioned details."
+
+MULTI-IMAGE PATTERN:
+"Use the person from picture 1 as the final subject and preserve their exact facial likeness. [Requested edit]. Identity comes only from picture 1. Pose from picture 2. Outfit from picture 3. Do not borrow identity from pictures 2 or 3. Maintain realistic anatomy, perspective, and lighting integration. Preserve all unmentioned details."
+
+CREATIVE TRANSFORMATIONS — be vivid and reference-specific, name the artist, franchise, or era, but always anchor identity first:
+  - "Preserve the exact facial likeness from picture 1. Transform them into a Renaissance oil painting in the style of Vermeer — rich warm tones, dramatic chiaroscuro lighting, ornate period clothing. Maintain realistic anatomy. Preserve all unmentioned details."
+  - "Preserve the exact facial likeness from picture 1. Reimagine them as a Marvel superhero — cinematic dramatic lighting, heroic pose, detailed costume with cape, glowing energy effects. Preserve all unmentioned details."
+  - "Preserve the exact facial likeness from picture 1. Transform them into a Studio Ghibli anime character — soft watercolor backgrounds, gentle Ghibli-style rendering, whimsical atmosphere. Preserve all unmentioned details."
+  - "Preserve the exact facial likeness from picture 1. Place them into a Star Wars scene — Jedi robes, lightsaber glow, dramatic sci-fi backdrop. Preserve all unmentioned details."
+  - "Preserve the exact facial likeness from picture 1. Turn them into a GTA loading screen character — bold outlines, saturated colors, attitude-filled pose, urban backdrop. Preserve all unmentioned details."
+
+FAILURE MODES TO AVOID:
+- Face drift: identity source not specified, or style/pose reference overrides the face
+- Over-editing: for simple edits, prompt rewrites the entire image instead of describing the delta (creative transformations may intentionally change more)
+- Reference confusion: multiple images provided without explicit role mapping
+
+CHARACTER / MASCOT SHEETS: When the user asks for a character sheet, mascot sheet, model sheet, turnaround, expression sheet, or reusable character reference board using uploaded references, create ONE comprehensive professional reference-board image, not separate variations. Map reference roles clearly first (for example: picture 1 = character identity/style reference, picture 2 = logo/brand asset) and keep the character identity consistent across every panel. Include a large hero pose, front / 3/4 / side / back turnaround views, an expression row, action/personality poses, accessories or props, color palette swatches, and compact notes such as personality, fun facts, or brand usage when appropriate. Preserve exact user-provided brand names, slogans, logo text, and requested copy verbatim; incidental tiny notes may be generated by the image model if the user did not provide exact wording. Use clean readable typography.
+
+BATCH VARIATIONS: When numberOfVariations > 1, the prompt must describe ONE subject in ONE scene — never mention counts, "versions", "different", or "multiple" in the prompt text. NEVER describe multiple copies or duplicates of the subject in a single image (no grids, collages, or side-by-side). Use Dynamic Prompt syntax to vary ONE dimension across separate images. For personas: vary scene, activity, expression, or environment — never vary identity. Example: user asks "4 versions at the beach" → numberOfVariations=4, prompt="[persona] at the beach {building a sandcastle|surfing a wave|reading under a palm tree|flying a kite}" — each output is ONE person doing ONE activity. For direct edits: vary the approach, e.g., numberOfVariations=3, prompt="make the sky {a vibrant sunset|stormy and dramatic|clear blue}". Preserve any requested orientation, aspect ratio, or exact pixel dimensions across every variation.
+
+SELECTION-GATED IMAGE STAGES: If the user asks for multiple reference-guided image options/takes/versions and says they will pick one before a later dance, animation, or video, this edit_image call is still the first step. Generate the complete image batch now with sourceImageIndex set to the relevant reference, the exact requested count, Dynamic Prompt options for each output, and the final video/image aspect ratio. Do not ask the user to choose before the images exist, and do not call video tools until after the user selects an image.
+
+LINKED VARIANTS: If multiple details must stay paired per output — visual style, identity cues, outfit, label text, symbols, setting, character, prop, location, or before/after keyframe details — use ONE top-level Dynamic Prompt branch with one complete prompt per output. Do NOT use separate Dynamic Prompt groups for details that must stay together; unpaired groups can mix attributes. If the user asks for per-variant facial, identity, or appearance changes, repeat that guidance inside EVERY option while also preserving recognizability. When the user names a subject or character, write that name or stable role inside every Dynamic Prompt option; a shared prefix outside the branch is not enough because each option must stand alone as a complete identity contract.
+
+Each option must be a fully concrete description — name the actual garment or styling, the actual setting, the actual accessories, and the literal text or symbol shown on screen when requested. Never use meta-placeholder phrasing such as "style-specific outfit", "variant-specific background", "include the requested symbol", "include a humorous alternate name", or "bake the name and symbol into the image" — those describe the task instead of the image.
+
+ORIGINAL + VARIANT BATCHES: When one option is a remade/preserved original and the other options are themed variants, the original option still needs a concrete visual contract. Say to preserve the original clothing/wardrobe/outfit and original background/setting, then name any requested added text, label, flag, logo, symbol, or prop for that original option. Do not leave the original option as only "unmodified original person"; it must be as fully specified as every themed option.
+
+NEW SETTING PER OPTION: When the variant theme implies a new place, culture, era, or context, every option must name its own setting (location, props, lighting). Do NOT carry the source background forward, do NOT write "in the same pose and placement as the original photo" without also naming the new background, and do NOT rely on "preserve all unmentioned details" to handle the setting — the new setting IS a mentioned detail.
+
+RECOGNIZABILITY OVER FEATURE LOCK: For ethnic / age / character / art-style transformations, do NOT paste the strict IDENTITY LOCK feature list ("face structure, eye shape, nose shape, mouth shape, jawline, skin tone, hairline") inside each option — that list contradicts the requested face change and the source face will pass through unchanged. Anchor recognizability per option through apparent age, signature hair silhouette, build, posture, and expression, and explicitly allow skin tone, facial features, and proportions to shift toward the target.
+
+Correct shape (each option self-contained, concrete, with a fresh setting and a recognizability anchor instead of a strict feature lock):
+"{The subject wearing [specific garment, color, cut, and material], standing in [specific NEW setting with props and lighting — never the source background], bold text at the bottom reads [literal requested text], [specific requested visual symbol] appears as a sign or prop, [requested per-variant facial or appearance shift, e.g. "skin tone, eye shape, and bone structure shift toward <target> features"], recognizable through apparent age, signature hair silhouette, build, posture, and expression|The subject wearing [second specific garment, color, cut, and material], standing in [second specific NEW setting with props and lighting], bold text at the bottom reads [second literal requested text], [second requested visual symbol] appears as a sign or prop, [second requested facial or appearance shift], recognizable through apparent age, signature hair silhouette, build, posture, and expression|...}"
+
+Wrong shape (placeholder labels masquerading as prompts):
+"{First variant with variant-specific facial features, placeholder wardrobe, alternate name, and requested symbol baked in|Second variant with different variant-specific facial features, placeholder wardrobe, alternate name, and requested symbol baked in|...}"
+
+Also wrong (strict feature lock + no new setting — the source face and source background pass through unchanged):
+"{Preserve the exact facial likeness — face structure, eye shape, nose shape, mouth shape, jawline, skin tone, hairline. Reimagine as <variant>: [garment description], standing in the exact same pose and placement as the original photo. Preserve all unmentioned details.|Preserve the exact facial likeness — [same strict lock]. Reimagine as <other variant>: [other garment], standing in the exact same pose and placement as the original photo. Preserve all unmentioned details.|...}"
+
+SCREENPLAY / STORYBOARD BATCHES: For multi-scene story, commercial, or longer-form video keyframes, use one Dynamic Prompt branch with one full scene prompt per option. Recurring characters must keep stable names and repeated visual anchors in every scene option where they appear: face/identity source if available, age range, build, hairstyle, outfit silhouette, color palette, signature prop/accessory, posture, and role. Do not let style, scene changes, or pose references alter identity. Include screenplay-style speaker tags when dialogue matters, e.g. CHARACTER: "We made it."
+
+COMPOSITE GPT IMAGE 2 STORYBOARD SHEETS: When numberOfVariations=1 and the user asks for one composite video storyboard/keyframe sheet using uploaded or generated references, the prompt must be a compiled storyboard prompt, not a concept summary. Include a SCENES: section with exactly the requested number of concrete entries named SCENE_01, SCENE_02, etc. Every scene entry must include Visual/Action, Camera/Motion, Dialogue/VO (or [no dialogue]), Audio/SFX, and any visible text or reference usage for that scene. Do not provide only the source brief or generic layout instructions; malformed compiled storyboard prompts are blocked by quality audit.`,
+                },
+                model: {
+                    type: 'string',
+                    enum: ['gpt-image-2', 'qwen-lightning', 'qwen', 'flux2'],
+                    description: 'DO NOT SET THIS PARAMETER unless the user names a specific edit model, asks for a very complex reference-guided image render, or asks for a video storyboard/storyboard sheet/contact sheet/panel layout image using references. The app auto-selects based on quality settings. Set "gpt-image-2" when the user asks for a ChatGPT, OpenAI, GPT, GPT-2, GPT Image, or gpt-image-2 reference-guided image/edit/model, or by default for complex single-image renders that need dense labels, crisp typography, multi-panel composition, timing notes, foley notes, professional storyboard-sheet layout, or a comprehensive character/mascot/model sheet with turnarounds, expressions, accessories, palette swatches, and brand notes. Z-image and Z-image Turbo are not edit_image models; route those explicit uploaded-image enhancement requests to generate_image with sourceImageIndex and starting_image_strength. If the user names another edit/image model, honor that requested model instead. GPT Image 2 always processes input images at high fidelity; do not set input_fidelity.',
+                },
+                sourceImageIndex: {
+                    type: 'number',
+                    description: 'Index of the primary image to use as the main reference. For follow-up edits when generated image results already exist, use the 0-based generated image result index; for example, editing the latest generated storyboard/image should use that generated result index so the model modifies the existing image instead of redrawing from uploads. When no generated image results exist, use sourceImageIndex=-1 to use the uploaded image references. The primary image and any additional uploaded images are passed as context images to guide generation.',
+                },
+                numberOfVariations: {
+                    type: 'number',
+                    description: 'Number of variations (1-16). Pass the user\'s EXACT requested count in ONE call — never split into multiple calls and never call edit_image again to "add more". "4 variations" → numberOfVariations=4 in a single call. Use the exact requested count for reference-guided images that will feed a later video after the user picks one. For screenplay/storyboard batches, the prompt must contain one Dynamic Prompt branch with one full scene prompt per scene; never set numberOfVariations=N with only scene 1\'s prompt. Use 1 unless the user explicitly asks for multiple. Default: 1.',
+                    minimum: 1,
+                    maximum: 16,
+                },
+                width: {
+                    type: 'number',
+                    description: 'Output image width in pixels. Defaults to the context image width. Supported range is 256-2560 for Qwen/Flux.2 edit models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., "1280 wide", "1280x720", "720p", "3840x2160"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels.',
+                },
+                height: {
+                    type: 'number',
+                    description: 'Output image height in pixels. Defaults to the context image height. Supported range is 256-2560 for Qwen/Flux.2 edit models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., "720 high", "1280x720", "720p", "2160x3840"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels.',
+                },
+                aspectRatio: {
+                    type: 'string',
+                    description: `${ASPECT_RATIO_DESCRIPTION}\n\nSet this whenever the user specifies an image or downstream video orientation/aspect ratio such as 9:16, 16:9, portrait, vertical, landscape, widescreen, TikTok/Reels/Shorts, or exact pixels. This includes selection-gated reference-guided image batches that will feed a later video or dance after the user picks one. For GPT Image 2 exact size requests, preserve exact pixel intent when possible and prefer popular GPT sizes such as 1536x1024, 1024x1536, 2048x1152, 3840x2160, and 2160x3840. GPT Image 2 does not support transparent-background output; do not promise a transparent result for this model.`,
+                },
+                gptImageQuality: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high', 'auto'],
+                    description: 'Optional GPT Image 2 rendering quality. Only set with model="gpt-image-2" when the user explicitly asks for low/fast, medium/balanced, high/final, or auto quality. Otherwise omit it and let the host app media quality setting map Fast to low, HQ to medium, and Pro to high.',
+                },
+                outputFormat: {
+                    type: 'string',
+                    enum: ['png', 'jpg', 'jpeg', 'webp'],
+                    description: 'Optional output file format for generated images. Set only when the user explicitly requests PNG, JPG/JPEG, or WebP. Hosts should normalize "jpeg" to the Sogni project format "jpg".',
+                },
+                personaName: {
+                    type: 'string',
+                    description: 'RARE — only set this when the user EXPLICITLY asks for solo images of one specific person ("a portrait of just [name]", "4 solos of [name] alone"). When set, the handler filters context to ONLY that persona\'s reference photo, so any other personas in your prompt will be missing their reference. DEFAULT for multi-persona requests is to OMIT this and put both faces in one combined call. Never set this for "make us as X", "the two of us", "my wife and I", or any phrasing that puts both personas in the same scene — that\'s a single combined call with no personaName.',
+                },
+            },
+            required: ['prompt'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/edit-image/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/edit-image/definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,8kCAA8kC;QAChlC,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;EAErB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+oBA8DsnB;iBACtoB;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,CAAC;oBACxD,WAAW,EACT,miCAAmiC;iBACtiC;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,kiBAAkiB;iBACriB;gBACD,kBAAkB,EAAE;oBAClB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,kkBAAkkB;oBACpkB,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;iBACZ;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,qzBAAqzB;iBACxzB;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,uzBAAuzB;iBAC1zB;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,GAAG,wBAAwB,imBAAimB;iBAC/nB;gBACD,eAAe,EAAE;oBACf,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;oBACvC,WAAW,EACT,kRAAkR;iBACrR;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;oBACpC,WAAW,EACT,uLAAuL;iBAC1L;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,2jBAA2jB;iBAC9jB;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;CACF,CAAC"}

package/dist-esm/tools/definitions/extend-video/definition.js

@@ -0,0 +1,48 @@
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'extend_video',
+        description: 'Extend a video by adding new time to the end. Works on BOTH videos previously rendered in this session AND user-uploaded videos — set videoIndex to a negative number (e.g. -1) to target an uploaded video when no prior render exists. The base video is auto-selected from the most recent video in this session unless videoIndex is set. ' +
+            'For LTX-2.3 base clips, the tool extracts the last frame and renders an image-to-video continuation. ' +
+            'For Seedance base clips, the tool extracts a trailing reference segment and renders a video-to-video continuation. ' +
+            'Returns both the standalone new segment and a spliced composite (base + new segment).' +
+            ' Use when the user asks to "make it longer", "extend the video", "add another N seconds", "continue the scene", "add an outro/bumper to the end", etc.' +
+            ' Prefer this over generate_image+animate_photo+stitch_video for "add a bumper/outro to this video" — extend_video preserves the original base bytes, audio, and timing instead of re-encoding them.' +
+            ' Do not use this tool to render fresh videos from scratch — call generate_video or animate_photo for that.' +
+            ' Output durations follow each model\'s native limits (LTX 2-20s, Seedance 4-15s) for the new segment alone.',
+        parameters: {
+            type: 'object',
+            properties: {
+                prompt: {
+                    type: 'string',
+                    description: 'What should happen during the extension — describe motion, action, dialogue, and audio for the appended seconds, NOT the entire video. ' +
+                        'For LTX continuations, preserve user-provided spoken dialogue in double quotes; if speech is requested without exact words, describe the delivery without inventing quoted dialogue. ' +
+                        'If the user did not specify what should happen, write a brief continuation that preserves the existing tone (e.g. "the scene continues with the same camera and pacing").',
+                },
+                duration: {
+                    type: 'number',
+                    description: 'Length in seconds of the new appended segment (NOT total final length). LTX 2-20, Seedance 4-15. Default: 5.',
+                    minimum: 2,
+                    maximum: 20,
+                },
+                videoIndex: {
+                    type: 'number',
+                    description: 'Which video result to extend. Default: -1 (most recent video in this session). ' +
+                        'Use 0-based non-negative indices for prior tool result videos. Use negative indices for uploaded videos: -1 = most recent video result OR first uploaded video when no prior render exists.',
+                },
+                videoModel: {
+                    type: 'string',
+                    enum: ['auto', 'ltx23', 'seedance2', 'seedance2-fast'],
+                    description: 'Which model to use for the new segment. Default: "auto" — detect from the base video\'s producer (Seedance base → Seedance, otherwise LTX-2.3). ' +
+                        'Override only when the user explicitly requests a different model.',
+                },
+                keepOriginalAudio: {
+                    type: 'boolean',
+                    description: 'Has no effect for extend_video (the new segment is appended after the base, so the base audio is always preserved through the original portion and the new segment carries its own audio). Reserved for parity with replace_video_segment.',
+                },
+            },
+            required: ['duration'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/extend-video/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/extend-video/definition.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,gVAAgV;YAChV,uGAAuG;YACvG,qHAAqH;YACrH,uFAAuF;YACvF,wJAAwJ;YACxJ,qMAAqM;YACrM,4GAA4G;YAC5G,6GAA6G;QAC/G,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,yIAAyI;wBACzI,uLAAuL;wBACvL,2KAA2K;iBAC9K;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,8GAA8G;oBAChH,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;iBACZ;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,iFAAiF;wBACjF,6LAA6L;iBAChM;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,CAAC;oBACtD,WAAW,EACT,kJAAkJ;wBAClJ,oEAAoE;iBACvE;gBACD,iBAAiB,EAAE;oBACjB,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,4OAA4O;iBAC/O;aACF;YACD,QAAQ,EAAE,CAAC,UAAU,CAAC;SACvB;KACF;CACF,CAAC"}

package/dist-esm/tools/definitions/generate-image/definition.js

@@ -0,0 +1,104 @@
+import { LITERAL_PROMPT_OVERRIDE } from '../../../contracts/promptOverrideMarker.js';
+import { ASPECT_RATIO_DESCRIPTION } from '../../../media/index.js';
+export const definition = {
+    type: 'function',
+    function: {
+        name: 'generate_image',
+        description: 'Generate a new image from a text description. Usually this is text-only: do NOT use this tool when the user expects an existing image to be reused or preserved in the result. That includes (a) people from My Personas, and (b) uploaded assets such as logos, brand marks, mascots, product shots, photos, screenshots, sketches, character designs, or other reference images they want carried through. Use edit_image with sourceImageIndex=-1 (or the appropriate generated index) instead. Exception: when the user explicitly requests Z-image, Z Image, or Z-image Turbo for an uploaded-image enhancement/image-to-image request, use this tool with model="z-turbo" or model="z-image", sourceImageIndex=-1, and starting_image_strength because edit_image does not expose Z-image models.',
+        parameters: {
+            type: 'object',
+            properties: {
+                prompt: {
+                    type: 'string',
+                    description: `Text description of the image (50-200 words). POSITIVE phrasing only. Be specific and vivid — reference real artists, franchises, and aesthetics by name.
+
+${LITERAL_PROMPT_OVERRIDE}
+
+PROMPT ORDER (follow this structure): [SUBJECT] → [ATTRIBUTES] → [ACTION/POSE] → [CAMERA/FRAMING] → [ENVIRONMENT] → [LIGHTING] → [STYLE/MEDIUM] → [MATERIALS/TEXTURES] → [SECONDARY DETAILS]. Always lead with the main subject and its concrete, observable attributes — never start with mood or atmosphere. Put the most visually decisive details early.
+
+SPECIFICITY: Use concrete nouns and observable adjectives ("weathered leather jacket", not "cool outfit"). Specify framing (close-up, medium shot, full body, wide shot), angle (eye level, low angle, high angle, overhead), lighting type ("soft overcast daylight", "warm golden-hour sunlight", "moody neon spill with deep shadows"), and medium/style ("photorealistic editorial photography", "cinematic still frame", "clean anime illustration"). Include materials and textures when relevant ("brushed aluminum", "wet asphalt reflections", "heavy wool texture").
+
+DEFAULTS (fill in when user is underspecified): Framing: medium shot for portraits, wide shot for environments, full-body for fashion/outfits. Angle: eye level unless dramatic perspective requested. Lighting: soft natural light for realism, clean studio light for product shots. Style: photorealistic for realistic models, matching the model's native style for stylized models (e.g. anime illustration for pony/animagine). Reference real artists and franchises by name ("in the style of Monet's Water Lilies", "Wes Anderson symmetrical pastel composition", "cyberpunk Blade Runner neon city", "shot on 85mm f/1.4 with shallow depth of field").
+
+AVOID: Starting with abstract mood words alone. Burying the subject after a long style preamble. Stacking incompatible styles. Overloading with competing focal points. Vague phrases like "very cool" or "epic vibes".
+
+CHARACTER / MASCOT SHEETS: When the user asks for a character sheet, mascot sheet, model sheet, turnaround, expression sheet, or reusable character reference board, create ONE comprehensive professional reference-board image, not separate variations. Include a large hero pose, front / 3/4 / side / back turnaround views, an expression row, action/personality poses, accessories or props, color palette swatches, and compact notes such as personality, fun facts, or brand usage when appropriate. Preserve exact user-provided brand names, slogans, logo text, and requested copy verbatim; incidental tiny notes may be generated by the image model if the user did not provide exact wording. Keep the character consistent across every panel and use clean readable typography.
+
+BATCH VARIATIONS: When numberOfVariations > 1, the prompt must describe ONE subject in ONE scene — never mention counts, "versions", "different", or "multiple" in the prompt text. NEVER describe multiple copies or duplicates of the subject in a single image (no grids, collages, or side-by-side). Use Dynamic Prompt syntax to vary ONE dimension across separate images. Example: user asks "4 cats in different spots" → numberOfVariations=4, prompt="a black cat {lounging in a sunlit window|prowling through autumn leaves|sitting on a vintage bookshelf|curled up by a fireplace}" — each output is ONE cat in ONE spot. Vary setting, style, lighting, expression, or composition — never override what the user specified. Preserve any requested orientation, aspect ratio, or exact pixel dimensions across every variation.
+
+SELECTION-GATED IMAGE STAGES: If the user asks for multiple image options/takes/versions and says they will pick one before a later dance, animation, or video, this tool call is still the first step. Generate the complete image batch now with the exact requested count, Dynamic Prompt options for each output, and the final video/image aspect ratio. Do not ask the user to choose before the images exist, and do not call video tools until after the user selects an image.
+
+LINKED VARIANTS: If multiple details must stay paired per output — visual style, outfit, label text, symbol, setting, character, prop, location, or before/after keyframe details — use ONE top-level Dynamic Prompt branch with one complete prompt per output. Do NOT use separate Dynamic Prompt groups for details that must stay together; unpaired groups can mix attributes. If the user asks for per-variant facial, identity, or appearance changes, repeat that guidance inside EVERY option. When the user names a subject or character, write that name or stable role inside every Dynamic Prompt option; a shared prefix outside the branch is not enough because each option must stand alone. Correct shape: "{full prompt for variant 1 with all paired details|full prompt for variant 2 with all paired details|...}".
+
+SCREENPLAY / STORYBOARD BATCHES: For multi-scene commercials, storyboards, or shot lists, numberOfVariations must equal the scene count and the prompt MUST be a SINGLE top-level dynamic branch containing one full scene prompt per option, e.g. "{scene 1 full prompt|scene 2 full prompt|scene 3 full prompt}". This is the required way to batch scenes with materially different content while still rendering one image per scene. If recurring characters appear, use stable character names and repeat the same visual anchors in every scene option where they appear (age range, build, hairstyle, outfit silhouette, color palette, signature prop/accessory, posture). Do not rename, merge, redesign, or drift characters between scene keyframes unless the user asks. Include speaker-tagged dialogue details when dialogue affects the keyframe, e.g. CHARACTER: "We made it." NEVER set numberOfVariations=N with only scene 1's prompt — that creates N duplicate versions of scene 1, not N scenes. If the scene count is 16 or fewer, do it in ONE call. Do NOT generate scene 1 first or split into smaller batches unless the user explicitly asks.
+
+COMPOSITE GPT IMAGE 2 STORYBOARD SHEETS: When numberOfVariations=1 and the user asks for one composite video storyboard/keyframe sheet, the prompt must be a compiled storyboard prompt, not a concept summary. Include a SCENES: section with exactly the requested number of concrete entries named SCENE_01, SCENE_02, etc. Every scene entry must include Visual/Action, Camera/Motion, Dialogue/VO (or [no dialogue]), Audio/SFX, and any visible text or reference usage for that scene. Do not provide only the source brief or generic layout instructions; malformed compiled storyboard prompts are blocked by quality audit.
+
+VIDEO KEYFRAMES: When generating images intended as first+last frames for video (animate_photo with frameRole="both"), use numberOfVariations=2 with Dynamic Prompts to create both frames in one call. Make each frame a distinct scene that creates a compelling transition. The video handler will inspect both generated frames and build a scene-aware transition prompt, so focus this image prompt on producing strong start/end visuals. Example: "a serene lake {at dawn with mist rising and soft pink sky|at dusk with fireflies and deep blue twilight}".`,
+                },
+                model: {
+                    type: 'string',
+                    enum: [
+                        'gpt-image-2',
+                        'z-turbo', 'z-image', 'chroma-v46-flash', 'chroma-detail', 'flux1-krea', 'flux2', 'pony-v7',
+                        'qwen-2512', 'qwen-2512-lightning',
+                        'albedo-xl', 'animagine-xl', 'anima-pencil-xl', 'art-universe-xl', 'hyphoria-real',
+                        'analog-madness-xl', 'cyberrealistic-xl', 'real-dream-xl', 'faetastic-xl',
+                        'zavychroma-xl', 'pony-faetality', 'dreamshaper-xl',
+                    ],
+                    description: 'DO NOT SET THIS PARAMETER unless the user names a specific model, asks for a very complex image render, asks for a video storyboard/storyboard sheet/contact sheet/panel layout image, or explicitly asks for Z-image/Z-image Turbo image-to-image. The app auto-selects based on quality settings. Set "gpt-image-2" when the user asks for a ChatGPT, OpenAI, GPT, GPT-2, GPT Image, or gpt-image-2 image/model, when they explicitly request very strong text rendering, or by default for complex single-image renders that need dense labels, crisp typography, multi-panel composition, timing notes, foley notes, professional storyboard-sheet layout, or a comprehensive character/mascot/model sheet with turnarounds, expressions, accessories, palette swatches, and brand notes. Set "z-turbo" when the user asks for Z-image Turbo; set "z-image" when they ask for Z-image without Turbo. If the user names another image model, honor that requested model instead. A model preference usually does not change which tool to use; the Z-image image-to-image exception uses sourceImageIndex plus starting_image_strength on this tool. NSFW rule: "gpt-image-2"/"flux2"/"flux1-krea" CANNOT do nudity — use "pony-v7", "chroma-detail", "chroma-v46-flash", or "z-turbo" instead.',
+                },
+                width: {
+                    type: 'number',
+                    description: 'Output image width in pixels. Default: 1024. Supported range is 256-2560 for default Z/Qwen/Flux.2 image models and 256-2048 for legacy/specialized image models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., "1280 wide", "1280x720", "720p", "1080x1920", "3840x2160"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds, so do not ask the user to adjust by a few pixels.',
+                },
+                height: {
+                    type: 'number',
+                    description: 'Output image height in pixels. Default: 1024. Supported range is 256-2560 for default Z/Qwen/Flux.2 image models and 256-2048 for legacy/specialized image models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., "720 high", "1280x720", "720p", "1080x1920", "2160x3840"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds, so do not ask the user to adjust by a few pixels.',
+                },
+                numberOfVariations: {
+                    type: 'number',
+                    description: 'Number of variations (1-16). Use the user\'s exact requested count in one call whenever they ask for multiple images/options/takes/versions, including images that will feed a later video after the user picks one. For screenplay/storyboard batches, this must equal the scene count AND the prompt must contain one Dynamic Prompt branch with one full scene prompt per scene; never set numberOfVariations=N with only one scene prompt. Default: 1.',
+                    minimum: 1,
+                    maximum: 16,
+                },
+                negativePrompt: {
+                    type: 'string',
+                    description: 'Things to avoid in the generated image. Only set when the user explicitly mentions what to avoid. E.g., "no watermarks, no text, no blurry edges".',
+                },
+                starting_image_strength: {
+                    type: 'number',
+                    description: 'Image-to-image strength (0.0-1.0). Only used when a source image is available and model supports img2img. Higher values = more deviation from the source image. 0.35 = conservative enhancement, 0.5 = balanced, 0.8 = creative. Set this with sourceImageIndex when the user explicitly requests Z-image/Z-image Turbo enhancement or any supported img2img starting-image workflow.',
+                },
+                sourceImageIndex: {
+                    type: 'number',
+                    description: 'Which result image to use as starting image for img2img (0-based index). -1 = original upload. Omit to auto-select latest result. Only relevant when starting_image_strength is set.',
+                },
+                seed: {
+                    type: 'integer',
+                    description: 'Random seed for reproducibility. Use -1 for random (default). Set a specific seed when the user wants to reproduce a previous result.',
+                },
+                guidance: {
+                    type: 'number',
+                    description: 'Guidance scale override. Higher values = more prompt adherence. Model-specific defaults are used if omitted. Only set when the user explicitly requests a guidance value.',
+                },
+                gptImageQuality: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high', 'auto'],
+                    description: 'Optional GPT Image 2 rendering quality. Only set with model="gpt-image-2" when the user explicitly asks for low/fast, medium/balanced, high/final, or auto quality. Otherwise omit it and let the host app media quality setting map Fast to low, HQ to medium, and Pro to high.',
+                },
+                outputFormat: {
+                    type: 'string',
+                    enum: ['png', 'jpg', 'jpeg', 'webp'],
+                    description: 'Optional output file format for generated images. Set only when the user explicitly requests PNG, JPG/JPEG, or WebP. Hosts should normalize "jpeg" to the Sogni project format "jpg".',
+                },
+                aspectRatio: {
+                    type: 'string',
+                    description: `${ASPECT_RATIO_DESCRIPTION}\n\nSet this whenever the user specifies an image or downstream video orientation/aspect ratio such as 9:16, 16:9, portrait, vertical, landscape, widescreen, TikTok/Reels/Shorts, or exact pixels. This includes selection-gated image batches that will feed a later video or dance after the user picks one. For GPT Image 2 exact size requests, preserve exact pixel intent when possible and prefer popular GPT sizes such as 1536x1024, 1024x1536, 2048x1152, 3840x2160, and 2160x3840. GPT Image 2 does not support transparent-background output; do not promise a transparent result for this model.`,
+                },
+            },
+            required: ['prompt'],
+        },
+    },
+};
+//# sourceMappingURL=definition.js.map

package/dist-esm/tools/definitions/generate-image/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/tools/definitions/generate-image/definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,ywBAAywB;QAC3wB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;EAErB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;siBAsB6gB;iBAC7hB;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE;wBACJ,aAAa;wBACb,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS;wBAC3F,WAAW,EAAE,qBAAqB;wBAClC,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe;wBAClF,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc;wBACzE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB;qBACpD;oBACD,WAAW,EACT,ouCAAouC;iBACvuC;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,2yBAA2yB;iBAC9yB;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,4yBAA4yB;iBAC/yB;gBACD,kBAAkB,EAAE;oBAClB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,4bAA4b;oBAC9b,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;iBACZ;gBACD,cAAc,EAAE;oBACd,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,oJAAoJ;iBACvJ;gBACD,uBAAuB,EAAE;oBACvB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,uXAAuX;iBAC1X;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,sLAAsL;iBACzL;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,uIAAuI;iBAC1I;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,2KAA2K;iBAC9K;gBACD,eAAe,EAAE;oBACf,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;oBACvC,WAAW,EACT,kRAAkR;iBACrR;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;oBACpC,WAAW,EACT,uLAAuL;iBAC1L;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,GAAG,wBAAwB,glBAAglB;iBAC9mB;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;CACF,CAAC"}