@sogni-ai/sogni-protocol 1.0.0-alpha.2

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@sogni-ai/sogni-protocol",
+  "version": "1.0.0-alpha.2",
+  "description": "Language-neutral protocol artifacts for the Sogni ecosystem: tool schemas, prompts, OpenAI tool manifests, and enums. Consumed by every Sogni SDK (TypeScript, Swift, and future Python/Kotlin/Rust SDKs) so contracts stay in lockstep across languages.",
+  "keywords": [
+    "sogni",
+    "schemas",
+    "json-schema",
+    "openai-tools",
+    "protocol",
+    "language-neutral"
+  ],
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sogni-AI/sogni-protocol.git"
+  },
+  "homepage": "https://github.com/Sogni-AI/sogni-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/Sogni-AI/sogni-protocol/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "schemas/",
+    "manifests/",
+    "prompts/",
+    "enums/",
+    "catalogs/",
+    "version.json",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./version.json": "./version.json",
+    "./schemas/*": "./schemas/*",
+    "./manifests/*": "./manifests/*",
+    "./prompts/*": "./prompts/*",
+    "./enums/*": "./enums/*",
+    "./catalogs/*": "./catalogs/*"
+  },
+  "sideEffects": false
+}

package/prompts/tools/add_subtitles.json

@@ -0,0 +1,12 @@
+{
+  "contractId": "add_subtitles_v1",
+  "version": "1.0.0",
+  "toolName": "add_subtitles",
+  "baseDescription": "add_subtitles burns caller-supplied subtitles, captions, lyrics, or on-screen dialogue into\nan existing video. Use this when the user provides cue text/timing, pastes SRT/VTT, or asks\nto add known caption lines to a generated or uploaded video.\n\nDo not use auto_transcribe. Speech-to-text is not enabled; when the user has not supplied\nsubtitle text or timing, ask for the cue text/timing instead of calling this tool.\n\nException: if the user explicitly authorizes invented caption copy with language like\n\"make them up\", \"write captions\", \"invent subtitles\", or \"add funny captions\", create a few\nshort generic cue lines yourself and call add_subtitles. Do not ask for exact wording when\nthe user has asked you to author the captions.\n\nSplit subtitles into multiple short cues. Do not burn one paragraph across the whole clip.\nUse overlay_video instead for static title cards, labels, logos, watermarks, or non-timed text.",
+  "parameterDocs": {
+    "sourceVideoIndex": "Non-negative generated video index or negative uploaded video index. Omit/default to the latest relevant video.",
+    "cues": "Multiple short cues with startSeconds, endSeconds, and text. Prefer 1.5-4 seconds per cue.",
+    "srt": "Full SRT/VTT string. Provide either srt or cues, not both.",
+    "auto_transcribe": "Do not set. Ask the user for subtitle text/timing until STT is available."
+  }
+}

package/prompts/tools/analyze_image.json

@@ -0,0 +1,12 @@
+{
+  "contractId": "analyze_image_v1",
+  "version": "1.0.0",
+  "toolName": "analyze_image",
+  "baseDescription": "analyze_image answers questions about image content, OCR, objects, style, documents, or\ncomparisons. It does not generate or modify media.\n\nUse only when the user asks to inspect, describe, read, compare, or reason about an image.\nDo not insert it as a quality-control step inside generation workflows unless the user\nexplicitly asks for analysis before continuing.\n\nFor uploaded images, negative indices refer to the upload order. For compare mode, provide\nboth sourceImageIndex and compareImageIndex.",
+  "parameterDocs": {
+    "query": "Specific question/request about the image. Preserve the user question directly.",
+    "analysisType": "Pick describe, ocr, objects, document, compare, or general based on the user request.",
+    "sourceImageIndex": "Omit to auto-select latest result or original upload. Use -1 for first uploaded image.",
+    "compareImageIndex": "Second image for compare mode. Use negative uploaded-image indices when comparing uploads."
+  }
+}

package/prompts/tools/analyze_video.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "analyze_video_v1",
+  "version": "1.0.0",
+  "toolName": "analyze_video",
+  "baseDescription": "analyze_video uses sampled frames to answer questions about an uploaded or generated video:\nsummary, timeline, visual scene description, action breakdown, or visible text.\n\nUse only when the user asks to inspect or understand a video. Do not call it as automatic\nverification after generation, and do not use it before stitch_video when the requested\ngeneration pipeline should continue.\n\nThis is visual sampled-frame analysis only. It does not transcribe audio and does not inspect\nevery frame.",
+  "parameterDocs": {
+    "query": "Specific question/request about the video. State whether summary, timeline, OCR, scene, or action detail is needed.",
+    "analysisType": "Pick summary, timeline, scene, action, ocr, or general based on the user request.",
+    "sourceVideoIndex": "Generated video index or negative uploaded-video index. Omit to auto-select latest generated video or first upload."
+  }
+}

package/prompts/tools/animate_photo.json

@@ -0,0 +1,13 @@
+{
+  "contractId": "animate_photo_v1",
+  "version": "1.0.0",
+  "toolName": "animate_photo",
+  "baseDescription": "animate_photo produces video from one or more source images using LTX 2.3.\n\nVIDEO PROMPT QUOTING: In video prompts, ONLY use double quotes for spoken dialogue.\nSpeaker tags are allowed outside the quotes for screenplay-style dialogue, e.g.\nCHARACTER: \"We made it.\" Never put on-screen text, overlay text, titles, captions, signs,\nwatermarks, or any visual text in quotes — describe them without quotes (e.g. bold white text\nreading CONGRATULATIONS overlays the lower third). Quotes signal speech to the model;\nquoting non-speech text confuses audio generation.\n\nDIALOGUE DURATION: Spoken dialogue in video prompts must fit the clip duration. Estimate\nat 2.5 words per second for natural cinematic delivery, plus ~1 second per acting beat\n(pauses, gestures, glances between lines). If the user did NOT explicitly request a specific\nduration (using default 5s), extend the duration to fit the dialogue (max 20s). If the user\nexplicitly requested a specific duration, condense the dialogue to fit while preserving meaning.\nAlways check: total dialogue words ÷ 2.5 + beat count ≤ clip duration.\n\nLATEST GENERATED IMAGE FOLLOW-UP: When the newest user turn asks to animate, make a video,\nor make a clip from a generated image/result (for example \"the apple\", \"this one\",\n\"the latest image\"), use animate_photo with that latest generated image. Do not inherit an\nolder Seedance model, resolution, or duration from an unrelated prior turn unless the newest\nuser turn explicitly says Seedance or confirms an immediately suggested Seedance video stage.\nLTX supports exact 2-20s durations, so honor requests like 3s exactly.\n\nWORD BUDGET PER CLIP: The handler REJECTS clips whose spoken dialogue exceeds the budget\n— there is NO auto-trim, so plan dialogue lengths up-front. Hard maximum is 3.75 spoken\nwords per second. Ceilings: 5s = 18 words, 6s = 22 words, 8s = 30 words, 10s = 37 words,\n15s = 56 words, 20s = 75 words. Aim below these ceilings. If a scene's dialogue won't fit,\ntighten the lines, raise the per-clip duration, or split into two segments — do NOT submit\nand hope it works. Spoken words inside double quotes count toward the budget; speaker tags\nand visual/action prose are free.\n\nBATCH VIDEO PER-CLIP DURATION: For a multi-segment animate_photo batch\n(sourceImageIndices + prompts) when the user states a TOTAL video length but NO per-clip\nlength, target 15 seconds per clip when dialogue is involved, and pass that duration\nexplicitly. Example: 60s total → 4 segments × 15s, NOT 6×10s or 12×5s. There is NO 3-clip\nbatch cap: sourceImageIndices supports up to 16 clips, so never split one planned batch into\n\"first 3\" and \"remaining clips\" calls. Do NOT split a planned 15s dialogue scene into multiple\nshorter clips just because a retry complains about word budget; keep duration=15 and tighten\nthe line. Use 5s clips only for single short motion beats or one very short spoken phrase.\nIf the user explicitly specifies a per-clip duration, honor that instead.\n\nN-VERSIONS-OF-A-VIDEO PATTERN: NEVER call animate_photo N times sequentially — ALWAYS\nuse sourceImageIndices in ONE call so all N projects run in parallel. Two flavors:\n(A) SHARED CONTENT — one edit_image/generate_image call with numberOfVariations=N + {|}\nDynamic Prompts to make N distinct source images, then ONE animate_photo call with\nsourceImageIndices=[start..start+N-1] and a single shared prompt.\n(B) PER-CLIP CONTENT — when each clip has DIFFERENT dialogue, jokes, narration, or motion,\npass BOTH sourceImageIndices AND prompts (array of N strings, one per clip) in the SAME\nsingle animate_photo call. The top-level prompt is still required — pass a brief batch summary.\n\nCRITICAL: sourceImageIndices values MUST be read from the latest edit_image/generate_image\ntool result's startIndex field — if startIndex=3 and 4 images were generated, pass\nsourceImageIndices=[3,4,5,6], NOT [0,1,2,3]. Negative indices refer to uploaded images:\n-1 first upload, -2 second upload, -3 third upload. Use repeated -1 entries only when\nintentionally reusing the primary uploaded image. When prompts is supplied, prompts.length\nMUST equal sourceImageIndices.length.\n\nSEEDANCE UPLOADED STORYBOARD DEFAULT: If the user uploaded a storyboard, shot sheet,\nor visual trailer board and asks to make a trailer/video/movie/clip from it, do NOT use\nanimate_photo on the board image and do NOT split it into four LTX clips. Use generate_video\nwith Seedance referenceImageIndices for one continuous clip unless the user explicitly asks\nfor separate LTX clips or first-frame/last-frame animation.\n\nSCREENPLAY / STORYBOARD ANIMATE RULE: For full storyboard projects, use one\nanimate_photo batch with sourceImageIndices + prompts so each clip keeps its own exact\nscene text, stable cast anchors, and screenplay-style speaker-tagged dialogue, and all video\nclips render in parallel. Every speaking clip's video prompt must include that clip's actual\nquoted dialogue, not placeholders such as \"while speaking\", \"dialogue begins\", \"explaining\",\nor \"final line lands\". If each generated scene keyframe should be both the first and last frame\nof its own stitched segment, call animate_photo with sourceImageIndices=[start..end],\nframeRole=\"both\", prompts=[...], and OMIT endImageIndex/endImageIndices so the handler\nuses each source as its own end frame.\n\nUPLOADED REFERENCE LOOPED SKITS: When the user supplies one uploaded reference image and\nasks for several scripted/storyboard/dialogue segments to reuse that same image as BOTH the\nfirst frame and last frame of each segment before stitching, do it in ONE animate_photo call:\nsourceImageIndices=[-1,-1,...], frameRole=\"both\", endImageIndex=-1 (or matching\nendImageIndices=[-1,-1,...]), duration equal to the requested per-segment duration, and\nprompts=[one full scene prompt per segment]. Each prompt must preserve the exact screenplay\nspeaker tags and quoted dialogue from that scene, e.g. HOST: \"...\" GUEST: \"...\". Do not\ndrop speaker tags, convert them to generic narration, omit the last-frame contract, analyze\nthe image first, generate new keyframes first, or split the batch into serial calls. After\nthe single animate_photo batch completes, call stitch_video with the returned video indices.\n\nFor adjacent transition chains: N images create N-1 clips — call animate_photo with\nframeRole=\"both\", sourceImageIndices=[start..end-1], endImageIndices=[start+1..end],\nprompts=[one transition prompt per adjacent pair], then stitch_video. If 5 uploaded images\nare the keyframe sequence, use sourceImageIndices=[-1,-2,-3,-4],\nendImageIndices=[-2,-3,-4,-5], frameRole=\"both\", prompts length 4, then stitch_video.\nDo NOT set endImageIndex=-1 in generated-keyframe patterns — that means every clip ends\non the primary uploaded image.\n\nUPLOADED FIRST-FRAME/LAST-FRAME TRANSITION CHAINS: If the user uploads multiple images\nand asks for a video that transitions from image to image, changes country/version every\nN seconds, or says to use first-frame/last-frame for each pair, call animate_photo directly.\nDo not call edit_image, generate_image, analyze_image, or map_assets_for_model first — the\nuploaded images are already the keyframes. For N uploaded images, create N-1 adjacent clips\nunless the user explicitly asks for a loop back to the first image. Use per-clip duration\nfrom \"every N seconds\" when present; otherwise divide the requested total by the number of\nadjacent clips. After animate_photo returns the batch videos, always call stitch_video with\nthose video indices before finalizing.",
+  "parameterDocs": {
+    "sourceImageIndices": "Batch source image indices. Read startIndex from prior generate_image/edit_image result. Negative = uploaded images (-1 = first upload).",
+    "prompts": "Per-clip prompt array. Length MUST equal sourceImageIndices.length when both are set.",
+    "duration": "Per-clip duration in seconds. Target 15s when dialogue is involved and total length is given without per-clip spec.",
+    "frameRole": "Set to \"both\" for first+last frame transitions using sourceImageIndices + endImageIndices.",
+    "endImageIndices": "End frames for adjacent-chain transitions. N images → N-1 clips."
+  }
+}

package/prompts/tools/apply_style.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "apply_style_v1",
+  "version": "1.0.0",
+  "toolName": "apply_style",
+  "baseDescription": "apply_style transfers an artistic style, era, franchise, medium, or photographic look onto\nan uploaded or generated image. It automatically uses the latest result unless the user\nspecifies a result number or asks for the original upload.\n\nTransfer visual style only. Do not let a style reference override identity, pose, or\ncomposition unless the user asked for those changes. For people, state identity preservation\nbefore the style instructions and finish by preserving pose and composition.\n\nUse refine_result instead when the user wants a targeted non-style edit to an existing\nresult. Use restore_photo only when they explicitly want to restart from the original upload.",
+  "parameterDocs": {
+    "prompt": "Style-transfer prompt. Name the style/era/artist/franchise and preserve identity, pose, and composition for people.",
+    "sourceImageIndex": "Omit for the latest result. Use -1 only when the user explicitly says original/source upload.",
+    "scale": "Set only when the user asks to upscale, enlarge, or increase resolution."
+  }
+}

package/prompts/tools/ask_clarifying_question.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "ask_clarifying_question_v1",
+  "version": "1.1.0",
+  "toolName": "ask_clarifying_question",
+  "baseDescription": "ask_clarifying_question pauses the workflow and asks the user for missing required input.\nUse only when no reasonable safe default exists, when required media/content is missing, or\nwhen confirmation is required for a destructive or credit-sensitive action.\n\nFor creative briefs, do not over-question. Ask at most 3 concise high-leverage questions only\nwhen the answer would materially change audience, product promise, format/duration/platform,\ntone, required assets, dialogue/no-dialogue, safety/legal/factual claims, or credit-sensitive\nexecution. Otherwise make reasonable assumptions and continue.\n\nThis ends the turn. Do not call another tool after it. Ask short concrete question(s) and\navoid preamble.",
+  "parameterDocs": {
+    "question": "One short concrete question surfaced verbatim to the user.",
+    "reason": "Short telemetry tag such as missing_source_asset, ambiguous_subject, or destructive_confirm."
+  }
+}

package/prompts/tools/change_angle.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "change_angle_v1",
+  "version": "1.0.0",
+  "toolName": "change_angle",
+  "baseDescription": "change_angle creates a new still image from a different camera perspective. Use when the\nuser asks for a left/right/back/three-quarter/front view, elevated/low-angle view, close-up,\nmedium shot, or wide shot of an existing image subject.\n\nThe description must be exactly one azimuth, one elevation, and one distance phrase in the\ntool schema format. Default unspecified elevation to eye-level shot and distance to medium\nshot. Use the latest result unless the user specifies another source or says original.\n\nUse orbit_video for a full video orbit. Do not pre-generate angles for orbit_video; that tool\nowns its own angle pipeline.",
+  "parameterDocs": {
+    "description": "Exact format: \"[azimuth] [elevation] [distance]\". Pick one value from each schema category.",
+    "sourceImageIndex": "Omit for latest result. Use -1 only when the user explicitly says original/source upload.",
+    "loraStrength": "Omit unless the user explicitly asks to control the strength of the angle change."
+  }
+}

package/prompts/tools/compose_instrumental.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "compose_instrumental_v1",
+  "version": "1.0.0",
+  "toolName": "compose_instrumental",
+  "baseDescription": "compose_instrumental composes an instrumental music structure and suggested musical\nparameters. Use for background scores, beds, cues, themes, and music requests without\nlyrics.\n\nDo not use compose_instrumental when the user wants sung lyrics, vocal hooks, or a jingle\nwith words — use compose_lyrics instead. Do not use it to actually render audio — the\nresponse is musical guidance; the caller hands it to generate_music for synthesis.",
+  "parameterDocs": {
+    "prompt": "The instrumental music topic, mood, genre, scene, campaign, or composition request.",
+    "music_prompt": "Optional musical style context, instrumentation, mood, or production direction.",
+    "duration_seconds": "Optional desired track duration in seconds (10-600)."
+  }
+}

package/prompts/tools/compose_lyrics.json

@@ -0,0 +1,12 @@
+{
+  "contractId": "compose_lyrics_v1",
+  "version": "1.0.0",
+  "toolName": "compose_lyrics",
+  "baseDescription": "compose_lyrics composes vocal song lyrics and suggested musical parameters. Use for songs\nwith words, choruses, verses, jingles, vocal hooks, or lyric rewrites.\n\nDo not use compose_lyrics for instrumental-only music — use compose_instrumental instead.\nDo not use it for spoken-word scripts, ad copy, or storyboards — use compose_script. Do\nnot use it to plan a multi-step workflow — use compose_workflow.\n\ncompose_lyrics returns lyrics text plus musical guidance. The caller is responsible for\nhanding the lyrics to generate_music to actually synthesize audio.",
+  "parameterDocs": {
+    "prompt": "The song topic, mood, genre, scene, campaign, or lyric request.",
+    "language": "Optional language code or language name for the lyrics.",
+    "music_prompt": "Optional musical style context, genre, instrumentation, mood, or production direction.",
+    "duration_seconds": "Optional desired song duration in seconds (10-600)."
+  }
+}

package/prompts/tools/compose_script.json

@@ -0,0 +1,21 @@
+{
+  "contractId": "compose_script_v1",
+  "version": "1.0.0",
+  "toolName": "compose_script",
+  "baseDescription": "compose_script composes scripts, storyboards, video prompts, ad concepts, trailers, social\nshorts, campaign beats, and talking-head plans. Use for creative writing artifacts where\nthe user wants prose, scenes, beats, or a script-shaped deliverable.\n\nDo not use compose_script for song lyrics — use compose_lyrics. Do not use it for simple\nprompt expansion — use enhance_prompt. Do not use it to plan a runnable multi-step\nworkflow — use compose_workflow or compose_workflow_template.\n\ncompose_script returns a creative-writing deliverable. When the script is meant to feed a\ndownstream video tool, pair it with destination_tool/destination_model so the output is\ntuned for that pipeline; the caller still has to invoke the generation tool itself.",
+  "parameterDocs": {
+    "brief": "The creative writing brief, story idea, product concept, video idea, or revision request.",
+    "script_type": "The kind of script or creative writing artifact to produce. One of video_prompt, screenplay, storyboard, ad_script, trailer, social_short, talking_head, campaign, or revision.",
+    "destination_model": "Optional destination video model selector, such as ltx23, wan22, or seedance2.",
+    "destination_tool": "Optional downstream tool, such as generate_video, animate_photo, sound_to_video, or video_to_video.",
+    "duration_seconds": "Requested runtime in seconds (1-300) for a video prompt, social short, ad, or talking-head script.",
+    "scene_count": "Requested number of scenes, shots, beats, or storyboard panels (1-12).",
+    "aspect_ratio": "Optional target aspect ratio, such as 16:9, 9:16, 1:1, 4:5, or 21:9.",
+    "platform": "Optional target platform or context, such as TikTok, YouTube Shorts, Instagram Reels, broadcast, landing page, game trailer, or pitch deck.",
+    "style": "Optional style, genre, tone, visual treatment, or brand voice to preserve.",
+    "first_frame_description": "Optional description of the starting frame when composing an image-to-video prompt without attached vision content.",
+    "first_frame_data_url": "Optional inline image data URI for the starting frame when composing an image-to-video or first-frame video prompt.",
+    "last_frame_data_url": "Optional inline image data URI for the ending frame when composing an image-to-video transition prompt.",
+    "return_format": "Requested output format. One of script, markdown, or json. Use script unless structured planning output is explicitly needed."
+  }
+}

package/prompts/tools/compose_workflow.json

@@ -0,0 +1,17 @@
+{
+  "contractId": "compose_workflow_v1",
+  "version": "1.0.0",
+  "toolName": "compose_workflow",
+  "baseDescription": "compose_workflow turns a creative brief into a runnable ONE-SHOT durable creative workflow\nplan (the same shape that POST /v1/creative-agent/workflows accepts). Pick this when the\nuser wants to RUN a multi-step pipeline ONCE — they will review the plan, submit it, get\nthe output, and be done. Trigger phrases: \"give me a runnable workflow plan\", \"compose a\none-shot plan\", \"compile a plan I can submit\", \"I want to run this once\", \"I do NOT need\nto save it as a template\", \"just review the steps and run it\", \"5-shot teaser, 9:16, 15s\"\nstyle concrete one-off briefs.\n\nHard line vs compose_workflow_template: if the user wants to SAVE / REUSE / NAME a\nworkflow recipe to re-run later on different inputs, use compose_workflow_template\ninstead. compose_workflow returns a one-time plan with no template wrapper; the user\nCANNOT re-run this output with different inputs without a fresh planner call.\n\nDo not use compose_workflow for ordinary creative writing artifacts — use compose_script for\nscripts, storyboards, ad concepts, or trailers. Do not use it for prompt expansion — use\nenhance_prompt. Do not use it to actually run a workflow — the response is just the plan;\nthe caller is responsible for submitting it to POST /v1/creative-agent/workflows with their\nown Idempotency-Key.\n\nThe returned plan is not idempotent on its own. Pair the eventual workflow submission with\na caller-owned Idempotency-Key. Phase 1 only supports return_format=\"json\".",
+  "parameterDocs": {
+    "brief": "Required free-form natural-language description of what the workflow should produce.",
+    "scene_count": "Suggested number of distinct shots/scenes (1-12). The planner may emit more steps than scenes (for example, a keyframe + clip pair per scene).",
+    "duration_seconds": "Target total duration in seconds for video-bearing plans (1-120).",
+    "aspect_ratio": "Output aspect ratio. One of 1:1, 4:3, 3:4, 16:9, 9:16, 21:9.",
+    "style": "Optional stylistic guidance such as \"cinematic, neon, low-key\" or \"whiteboard illustration\".",
+    "destination_models": "Optional preferred image/video/music model selectors (e.g. flux2, ltx23). Each subkey is optional.",
+    "max_estimated_capacity_units": "Optional coarse capacity budget. If set, the planner tries to keep total estimated cost at or below this value; the API returns fits_budget=false if it cannot.",
+    "include_audio": "When true, include a generate_music step in the plan. Defaults to false.",
+    "return_format": "Reserved for future use; only \"json\" is supported in Phase 1. Omit if unsure."
+  }
+}

package/prompts/tools/compose_workflow_template.json

@@ -0,0 +1,23 @@
+{
+  "contractId": "compose_workflow_template_v1",
+  "version": "1.0.0",
+  "toolName": "compose_workflow_template",
+  "baseDescription": "compose_workflow_template turns a creative brief into a savable, parameterized workflow\ntemplate plus a concrete example plan for the inputs the planner picked. This is the\ntool to use whenever the user wants to CREATE / SAVE / DESIGN / BUILD a reusable\nworkflow recipe — not just run one once. Trigger phrases: \"create a workflow that…\",\n\"save this as a workflow\", \"make me a reusable workflow…\", \"build a workflow that…\",\n\"design a workflow…\", \"I want a recipe for…\", \"I want to be able to re-run this on…\",\n\"save as workflow\", \"turn this into a workflow\", \"workflow that takes X as input\".\n\nThe returned `template_draft` carries typed `inputs[]` (image/audio/video/text/number/\nselect/boolean), parameterized `stages[]` that reference inputs via `$inputs.NAME`\nplaceholders, and an optional `graph` layout the visual builder consumes. A sibling\n`plan` field carries a Phase-1-compatible `steps[]` rendering for the example inputs so\nthe UI can preview the workflow without round-tripping the compiler.\n\nHard line vs direct generation tools: if the user asked to MAKE / SAVE / DESIGN a\nworkflow, never call generate_video, generate_image, edit_image, animate_photo, or any\nother rendering tool directly — that consumes credits to produce one-shot media when\nthe user wanted a reusable recipe. Pick compose_workflow_template instead. After\ncompose_workflow_template returns the template_draft, you MUST immediately call\nfinalize_response next. DO NOT call any other tool after compose_workflow_template —\nno render tools \"to show a preview\", no demonstration runs, nothing. The user reviews\nthe draft in the builder UI, not in chat. Calling generate_image / generate_video /\nedit_image after compose_workflow_template is a fixture-failing mistake.\n\nHard line vs compose_workflow: if the user said \"I do not need to save it as a\ntemplate\", \"give me a runnable plan to submit\", \"one-shot\", \"just run this once\", or\nsimilar single-use phrasing — pick compose_workflow, NOT compose_workflow_template.\ncompose_workflow_template is exclusively for SAVING reusable recipes.\n\nDo not use compose_workflow_template for one-shot turn-by-turn plans — use compose_workflow\ninstead. The returned template is a draft; the caller is responsible for saving it via\nPOST /v1/creative-agent/workflows/templates and minting a stable template id.\n\nEditing an existing template: pass the full template JSON as `existing_template` together\nwith the modification brief and the planner returns a refined `template_draft` that keeps\nthe id stable, bumps the version, preserves stages the brief did not touch, and applies\nthe requested changes. This is the canonical path for \"add a music step\", \"switch the\nstoryboard model to GPT Image 2\", or \"make this 9:16 instead of 16:9\" style edits.\n\nEditing a workflow you cannot see: if the user asks to edit a saved workflow by name or\nid (e.g. \"edit the bobblehead workflow\", \"modify wf_bobblehead_tiktok\") and the\nconversation does not contain the existing template JSON, do NOT call manage_memory and\ndo NOT ask the user to paste the template — just call compose_workflow_template with the\nmodification brief and a sensible name (you may reuse the workflow id the user mentioned).\nOmit existing_template in that case. The planner composes a fresh template_draft that\nrepresents the modification; preserving stage ids only happens when existing_template is\npresent, and that is acceptable — the alternative is a wasted turn.\n\nPhase 2 supports return_format=\"json\" only. Visibility defaults to \"private\"; the \"team\"\nvisibility slot is reserved for a later milestone.",
+  "parameterDocs": {
+    "brief": "Required free-form natural-language description of what the workflow should produce. When editing an existing template, phrase the brief as the modification request (e.g. \"Add a music step at the end and make the duration 12s\").",
+    "name": "Required human-readable template name. Shown in the workflow library and run launcher.",
+    "description": "Optional template description; the planner derives one from the brief if omitted.",
+    "category": "Optional category (portrait, video-social, makeover, cinematic, music, analysis, custom, other). Defaults to \"custom\".",
+    "visibility": "Persistence visibility: \"private\" (default) or \"public\". \"team\" is reserved for a later milestone.",
+    "inputs": "Optional typed input declarations. When omitted, the planner LLM proposes inputs based on the brief. Each entry needs name + type; required, description, default, options, multiple, and internal are optional refinements.",
+    "scene_count": "Suggested number of distinct shots/scenes (1-12).",
+    "duration_seconds": "Target total duration in seconds for video-bearing plans (1-120).",
+    "aspect_ratio": "Output aspect ratio. One of 1:1, 4:3, 3:4, 16:9, 9:16, 21:9.",
+    "style": "Optional stylistic guidance such as \"cinematic, neon, low-key\" or \"whiteboard illustration\".",
+    "destination_models": "Optional preferred image/video/music model selectors (e.g. flux2, ltx23). Each subkey is optional.",
+    "max_estimated_capacity_units": "Optional coarse capacity budget. The planner returns fits_budget=false if it cannot fit under the cap.",
+    "include_audio": "When true, include a generate_music step in the example plan. Defaults to false.",
+    "return_format": "Reserved for future use; only \"json\" is supported in Phase 2. Omit if unsure.",
+    "existing_template": "Optional full WorkflowTemplate JSON. When supplied, the planner edits this template per the brief instead of designing from scratch — preserves stage ids and unchanged stages, bumps version, and applies the requested modifications. Use this for the chat \"edit this workflow\" flow and the builder \"regenerate from prompt\" button."
+  }
+}

package/prompts/tools/create_asset_manifest.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "create_asset_manifest_v1",
+  "version": "1.0.0",
+  "toolName": "create_asset_manifest",
+  "baseDescription": "create_asset_manifest resets and seeds the session asset manifest with stable asset_id\nrecords. Use at the start of workflows with multiple named uploaded/generated assets that\nwill need durable references across later prompts.\n\nDo not call this just to use ordinary uploaded images in edit_image/generate_image; those\ntools can already reference uploads. Resetting discards prior manifest entries.",
+  "parameterDocs": {
+    "assets": "Ordered assets to register. Each needs user_label and type; include must_preserve/avoid only when they matter later."
+  }
+}

package/prompts/tools/dance_montage.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "dance_montage_v1",
+  "version": "1.0.0",
+  "toolName": "dance_montage",
+  "baseDescription": "dance_montage creates dance videos from an uploaded photo. Dance video requests from an\nuploaded photo go directly to dance_montage; do not call edit_image/generate_image first\nunless the user explicitly asks for a new look, outfit, generated character/image, variations,\nor persona identity prep.\n\nDance preset/vibe words like \"Barbie\", \"Metric\", \"Black Sheep\", \"Rasputin\", or \"TikTok\" are\nnot image-prep requests by themselves.\n\nSELECTION-GATED DANCE FLOW: If the user asks for N image options and says they will pick\none before the dance video, generate the image options first (generate_image or edit_image\nwith numberOfVariations=N), then stop and wait for the user to choose before calling\ndance_montage.",
+  "parameterDocs": {
+    "sourceImageIndex": "Use the uploaded photo directly (-1). Only use a generated image index if the user explicitly requested a new image first."
+  }
+}

package/prompts/tools/edit_image.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "edit_image_v1",
+  "version": "1.0.0",
+  "toolName": "edit_image",
+  "baseDescription": "edit_image applies instruction-based edits to uploaded or generated images. Use when\nuploaded or reference images must guide identity or likeness.\n\nImage-to-Image prompt order: [IDENTITY LOCK] → [REQUESTED EDIT] → [REFERENCE ROLE\nMAPPING] → [POSE/COMPOSITION] → [STYLE] → [LIGHTING/REALISM] → [PRESERVE ALL\nUNMENTIONED DETAILS]. GOLDEN RULE: When editing a person, always state which image owns\nidentity — never leave identity ambiguous. Describe only the DELTA — what changes. Don't\nrewrite the entire image; the base image already contains most of the truth. Default to minimal\nchange. For multi-image edits, assign ONE primary role per reference image (identity, pose,\noutfit, style, environment). Never let a style/pose/clothing reference silently override the face.\nUse positive constraints — \"preserve exact facial likeness, face structure, eye shape, nose\nshape, mouth shape, jawline, skin tone, hairline, apparent age, and overall recognizability\"\n— not vague negatives like \"don't mess up the face\".\n\nUPLOADED IMAGE VARIANT SETS: When the user supplies a photo/portrait/reference image and\nasks for N distinct generated images deriving from that source while changing paired\nper-output details, call edit_image exactly once with sourceImageIndex=-1,\nnumberOfVariations=N, and ONE Dynamic Prompt branch with N complete options. Each option\nmust be a full concrete image prompt for one output, including the uploaded subject/reference\nanchor, requested pose or placement preservation, the specific changed appearance/style/role,\nclothing or surface details when relevant, setting/background, and any requested label text or\nvisual symbol. If one option is a remade original/preserved source and the rest are themed\nvariants, the original option must explicitly say to preserve the original clothing/wardrobe/outfit\nand background/setting, plus any requested added label, flag, logo, symbol, or prop.\nDo not call generate_image, analyze_image, or multiple serial edit_image calls first.\n\nSELECTION-GATED IMAGE STAGES: If the user asks for N image options and says they will pick\none before a later dance/video/animation, call edit_image exactly once with numberOfVariations=N\nand one Dynamic Prompt branch. After images are created, stop and ask the user to choose;\ndo not call dance_montage, animate_photo, or generate_video until they select.\n\nMULTI-PERSONA (COMBINED): When multiple personas must appear in the SAME scene, make\nONE edit_image call with ALL persona faces in one prompt and DO NOT pass personaName.\nPer-persona splits (one call each with personaName set) are RARE — only when the user\nexplicitly asks for solo images of each person individually.\n\nSTORYBOARD IMAGE BATCH RULE: When rendering scene keyframes from a screenplay/storyboard,\nnumberOfVariations is only the count; the prompt MUST be one Dynamic Prompt branch with one\nfull keyframe prompt per scene:\n{scene 1 full keyframe prompt|scene 2 full keyframe prompt|...|scene N full keyframe prompt}.\nNEVER set numberOfVariations=N with only the first scene prompt — that creates N versions of\nscene 1. For full project requests, one edit_image batch for all scene keyframes, then one\nanimate_photo batch for all video clips in parallel.\nException: if the storyboard/shot sheet is already uploaded and the user asks to make a\ntrailer/video/movie/clip from that uploaded board, do not extract panels or redraw keyframes.\nUse generate_video with Seedance references for one continuous clip unless the user explicitly\nasks for separate image keyframes or a storyboard sheet output.\n\nDIRECT UPLOADED GPT IMAGE 2 STORYBOARD SHEETS: If the user uploaded reference images and\nasks for one finished GPT Image 2 storyboard/keyframe sheet now, call edit_image directly\nwith sourceImageIndex=-1, model=\"gpt-image-2\", numberOfVariations=1, and the requested\ncanvas/aspect settings. If the user did not explicitly specify a storyboard page/canvas/sheet\nshape, default the GPT Image 2 storyboard sheet pixel dimensions to a balanced grid that hosts\nthe target cell aspect ratio natively (e.g., 12 cells with 9:16 portrait video target -> ~3:4\nportrait sheet around 1728x2304; 12 cells with 16:9 landscape video target -> ~4:3 landscape\nsheet around 2304x1728; 6 cells with 9:16 target -> ~27:32 portrait sheet around 1840x2176). Do\nNOT default the sheet to 2560x1440 landscape when cells are portrait — a landscape sheet with\na portrait-cell grid physically forces cells to ~4:3 landscape and the model will not render\n9:16 portrait rectangles inside it. Keep individual scene-cell/frame areas at the target video\naspect ratio. Do not call map_assets_for_model, analyze_image, generate_image, or a separate\nplanning tool first. The uploaded files are already available as references; describe their\nroles plainly in the edit_image prompt and generate the sheet in that call.\n\nDO NOT USE edit_image FOR UPLOADED REFERENCE LOOPED VIDEO SEGMENTS: If the user says the\nsame uploaded image/reference should be reused as the first frame and last frame of each\nscripted segment/scene/clip before stitching, they are explicitly asking to animate the\nuploaded image, not to generate new storyboard keyframes. Do not call edit_image for that\nrequest. Call animate_photo once with repeated uploaded source indices and per-scene prompts.",
+  "parameterDocs": {
+    "sourceImageIndex": "Index of uploaded/generated image. Use -1 for the first uploaded image.",
+    "numberOfVariations": "Number of output variants. When > 1, use a Dynamic Prompt branch with one complete prompt per output.",
+    "prompt": "Edit instruction. Start with identity lock (who owns the face), then describe only the delta."
+  }
+}

package/prompts/tools/enhance_prompt.json

@@ -0,0 +1,20 @@
+{
+  "contractId": "enhance_prompt_v1",
+  "version": "1.0.0",
+  "toolName": "enhance_prompt",
+  "baseDescription": "enhance_prompt enhances or adapts a source prompt into a model-ready image, video, music, or\nedit prompt. Use for prompt expansion and model-specific prompt preparation when the caller\nhas a rough idea, a revision request, or a prompt that needs to be tuned for a specific\ndownstream model or generation tool.\n\nDo not use enhance_prompt for full creative-writing artifacts. Use compose_script for\nscripts, storyboards, ad concepts, trailers, and talking-head plans. Use compose_lyrics for\nsong lyrics and compose_instrumental for instrumental music structure. Do not use\nenhance_prompt to plan a multi-step workflow — use compose_workflow or\ncompose_workflow_template instead.\n\nenhance_prompt returns prompt text. The caller is responsible for handing the enhanced\nprompt to the chosen downstream generation tool (generate_image, edit_image,\ngenerate_video, animate_photo, sound_to_video, video_to_video, generate_music, etc.).",
+  "parameterDocs": {
+    "prompt": "The source prompt, rough idea, or prompt revision request to enhance.",
+    "target_output": "The kind of prompt artifact to produce. One of image_prompt, video_prompt, music_prompt, edit_prompt, model_prompt, or general_prompt.",
+    "destination_model": "Optional destination model selector, such as seedance2, ltx23, wan22, flux2, gpt-image-2, or sdxl.",
+    "destination_tool": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, video_to_video, or generate_music.",
+    "prompting_type": "Optional image-prompting family when producing an image prompt. One of flux, sdxl, sd15, pony, fast, sd3, editing, or video.",
+    "model_title": "Optional human-readable target model name for image prompt guidance.",
+    "style_prompt": "Optional current style, brand, or prompt context to complement without repeating.",
+    "prompt_mode": "Optional model prompt adaptation mode. One of auto, preserve, expand, compress, validate, or payload.",
+    "duration_seconds": "Requested runtime in seconds (1-300) when enhancing a video or music prompt.",
+    "aspect_ratio": "Optional target aspect ratio, such as 16:9, 9:16, 1:1, 4:5, or 21:9.",
+    "assets": "Optional available assets (max 12) the enhanced prompt may reference. Each entry needs media_type (image/video/audio) and may include id, label, role, and url.",
+    "constraints": "Optional production, brand, model, or user constraints to preserve."
+  }
+}

package/prompts/tools/extend_video.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "extend_video_v1",
+  "version": "1.0.0",
+  "toolName": "extend_video",
+  "baseDescription": "Use extend_video when a video already exists in the session — whether previously rendered OR\nuploaded — and the user asks to make it longer, add a segment, or append a bumper, outro,\nintro, tag, or sting to the end (or start). Do NOT call generate_video, animate_photo, or build\na new bumper from scratch via edit_image+animate_photo+stitch_video — those render fresh\nclips and either waste the previous render or ignore the uploaded base.\n\nFor uploaded base videos, set videoIndex to a negative number (-1 for first uploaded video).\nSet duration to the ADDITIONAL seconds (not the new total).\n\nTrigger phrases: \"make it longer\", \"extend the video\", \"add another N seconds\", \"continue the\nscene\", \"add a bumper/outro/intro/tag/sting to the end (or start)\".\n\nBoth extend_video and replace_video_segment auto-detect the base video's model (Seedance\nsource → Seedance continuation; LTX source → LTX continuation; Wan source → Wan continuation), so OMIT videoModel unless\nthe user explicitly demands a different model. This applies regardless of whether the prior\nrender came from generate_video, animate_photo, sound_to_video, or video_to_video.",
+  "parameterDocs": {
+    "videoIndex": "Index of the existing video. Use -1 for first uploaded video, non-negative for generated videos.",
+    "duration": "ADDITIONAL seconds to add — not the new total length.",
+    "videoModel": "Omit to auto-detect from source video. Only set if user explicitly requests a different model."
+  }
+}

package/prompts/tools/extract_metadata.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "extract_metadata_v1",
+  "version": "1.0.0",
+  "toolName": "extract_metadata",
+  "baseDescription": "extract_metadata reads prompt/model/settings metadata from an uploaded media file. Use when\nthe user asks what prompt, model, seed, dimensions, or generation settings are embedded in\nan uploaded file, or when they ask to recreate/remix an uploaded file from its metadata.\n\nThis indexes uploaded files only, not prior generated results already known to chat. Do not\ncall it for ordinary visual analysis; use analyze_image or analyze_video for content.",
+  "parameterDocs": {
+    "file_index": "0-based uploaded-file index. Omit for the first uploaded file."
+  }
+}

package/prompts/tools/finalize_response.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "finalize_response_v1",
+  "version": "1.1.0",
+  "toolName": "finalize_response",
+  "baseDescription": "finalize_response marks the turn complete and stops the tool loop. Use after the requested\nworkflow succeeds, partially succeeds, fails with a surfaced error, or needs no tool action.\n\nWhen the user asked for a script, storyboard, ad concept, trailer, creator video, meme/parody,\nor music prompt and no media tool is required, deliver the final creative in a clean Markdown\ncontract: title, concept/objective, audience if relevant, timed beats or script, audio/text\nnotes, generation prompt(s), CTA, and brief assumptions. For revisions, apply the feedback\ndirectly while preserving approved elements and rejected constraints.\n\nDo not call any other tool after finalize_response. Keep the summary short and grounded in\nactual tool results; do not claim exact metadata that no tool returned.",
+  "parameterDocs": {
+    "summary": "Short user-visible closeout. Mention produced media or the concrete blocker; avoid duplicating prior tool output.",
+    "outcome": "success, partial, asked_user, failed, or no_action based on the actual turn outcome."
+  }
+}

package/prompts/tools/generate_image.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "generate_image_v1",
+  "version": "1.1.0",
+  "toolName": "generate_image",
+  "baseDescription": "generate_image creates images from text descriptions. Use for text-only image generation;\nuse edit_image when uploaded or reference images must guide identity/likeness.\nException: Z-image and Z-image Turbo image-to-image/enhancement requests use generate_image\nwith model=\"z-turbo\" or model=\"z-image\", sourceImageIndex=-1, and starting_image_strength;\ndo not route explicit Z-image Turbo uploaded-image enhancement to edit_image because\nedit_image does not expose Z-image models.\n\nFLUX.2 PROMPT ORDER: [SUBJECT] → [ATTRIBUTES] → [ACTION/POSE] → [CAMERA/FRAMING]\n→ [ENVIRONMENT] → [LIGHTING] → [STYLE/MEDIUM] → [MATERIALS/TEXTURES] →\n[SECONDARY DETAILS]. Always start with the main subject, never mood or atmosphere.\nUse concrete nouns and observable adjectives — \"soft overcast daylight\" not \"nice lighting\".\nGood defaults when user is underspecified: medium shot for portraits, wide shot for\nenvironments, eye-level angle, soft natural light for realism.\n\nDYNAMIC PROMPTS: When numberOfVariations > 1, use Dynamic Prompt syntax to make each\nvariation meaningfully different — not just seed-different. Syntax: {a|b|c} cycles\nsequentially, {@a|b|c} picks randomly, {~a|b} paired cycling across groups. Rules: (1) Vary\nONLY what the user left unspecified — lock in everything they specified. (2) Match option\ncount to numberOfVariations so every result is unique. (3) Briefly tell the user what you're\nvarying — never show raw {|} syntax. (4) Skip when: user wants consistency, prompt is fully\nspecified, user typed their own {|} syntax, or iterating on a specific result. (5) NEVER put\nthe count or the word \"versions\"/\"variations\" inside the prompt — the prompt always describes\na single image. The multiplicity comes ONLY from numberOfVariations + the {|} syntax.\nLINKED VARIANTS: when multiple attributes must stay paired per result, use ONE top-level\nDynamic Prompt branch with one complete self-contained prompt per output. Do NOT split\nlinked fields into separate Dynamic Prompt groups.\n\nSELECTION-GATED IMAGE STAGES: If the user asks for N image options and says they will pick\none before a later dance/video/animation, call generate_image once with numberOfVariations=N.\nAfter images are created, stop and ask the user to choose; do not call dance_montage,\nanimate_photo, or generate_video until they select.\n\nIMAGE→VIDEO DIMENSION RULE: When generating an image that will feed into a video tool\n(animate_photo, sound_to_video, etc.), the image MUST be generated at the SAME aspect\nratio and dimensions as the target video. Default video aspect ratio is 16:9 landscape —\npass aspectRatio=\"16:9\" (or the user's specified/reference ratio) so the source image\nmatches the video output. Never generate a square image for a widescreen video. Exception:\na composite GPT Image 2 storyboard/keyframe sheet for a later Seedance video is a board,\nnot a single source frame; unless the user explicitly specifies a storyboard page/canvas/sheet\nshape, default the sheet image dimensions to a balanced grid that hosts the target\nscene-cell/frame aspect natively (portrait video target -> portrait or square sheet whose\ncolumns x rows grid produces ~9:16 cells; landscape video target -> landscape sheet whose\nrows x columns grid produces ~16:9 cells). Each scene-cell/frame area preserves the target\nvideo aspect ratio.\n\nSTORYBOARD IMAGE BATCH RULE: When rendering scene keyframes from a screenplay/storyboard,\nnumberOfVariations is only the count; the prompt MUST be one Dynamic Prompt branch with one\nfull keyframe prompt per scene:\n{scene 1 full keyframe prompt|scene 2 full keyframe prompt|...|scene N full keyframe prompt}.\nNEVER set numberOfVariations=N with only the first scene prompt — that creates N versions of\nscene 1. For full project requests, one generate_image batch for all scene keyframes, then\none animate_photo batch for all video clips in parallel.\n\nSTORYTELLING / BRAND / SOCIAL IMAGE PROMPTS: If generating a storyboard, ad concept,\ntrailer sheet, meme, creator post, or provocative social concept, make the first frame or\npanel immediately legible. Preserve the user's requested tone and audience. Use concrete\ncomposition, persona, product/brand role, caption placement, readable required text, and a\nclear visual transformation or punchline. For provocative adult social content, keep subjects\nclearly adult and consensual, PG-13/non-explicit, and avoid minor-coded styling or school-coded\nsettings while still optimizing visual magnet, persona, caption bait, and replay/comment value.\n\nGPT IMAGE 2 STORYBOARD SHEET → SEEDANCE AUTO-PROCEED: If the user asks to run the whole\nGPT Image 2 storyboard/keyframe sheet plus Seedance workflow without approval, the FIRST\ngenerate_image call must create ONE composite storyboard/keyframe sheet, not loose concept\nart and not separate keyframes. Use model=\"gpt-image-2\", numberOfVariations=1, and a\ncompiled storyboard prompt that literally includes: \"Create exactly N sequential video\nstoryboard frames as one composite storyboard image\", \"Target final video aspect ratio: X\",\na `SCENES:` section, and exactly N concrete scene entries named `SCENE_01`, `SCENE_02`,\netc. Each scene entry must include `Visual/Action:`, `Camera/Motion:`, `Dialogue/VO:`\n(use `[no dialogue]` when silent), `Audio/SFX:`, and any reference/visible-text notes\nneeded for that scene. Do not send only a source brief, storyboard concept, or generic\nlayout instructions as the prompt; malformed compiled storyboard prompts are blocked by\nquality audit instead of being repaired at runtime. Unless the user explicitly specifies another\nstoryboard page/canvas/sheet shape, default the GPT Image 2 storyboard sheet pixel dimensions\nto a balanced grid that hosts the target cell aspect natively: for a 9:16 portrait video,\npick a portrait-leaning sheet whose columns x rows grid produces ~9:16 cells (e.g., 12 cells\n-> ~3:4 sheet around 1728x2304, 6 cells -> ~27:32 around 1840x2176, 9 cells -> ~9:16 around\n1504x2672); for a 16:9 landscape video, pick a landscape sheet whose rows x columns grid\nproduces ~16:9 cells (e.g., 12 cells -> ~4:3 sheet around 2304x1728). Do not force landscape\n2560x1440 when cells are portrait — a landscape sheet with a portrait-cell grid cannot host\n9:16 cells without crushing them. Preserve the requested final video aspect ratio for every\nframe area. After\nthat image completes, call generate_video once using the generated storyboard board as\n@Image1/referenceImageIndices=[0], with skipPromptProcessing=false only when the user\nexplicitly wants the storyboard text rewritten; otherwise preserve the compiled shot guide\nand use skipPromptProcessing=true, expandPrompt=false.\n\nDO NOT USE generate_image FOR UPLOADED REFERENCE LOOPED VIDEO SEGMENTS: If the user says\nthe same uploaded image/reference should be reused as the first frame and last frame of each\nscripted segment/scene/clip before stitching, they are explicitly asking to animate the\nuploaded image, not to generate new storyboard keyframes. Do not call generate_image for\nthat request. Call animate_photo once with repeated uploaded source indices and per-scene\nprompts.\n\nREUSING RESULTS: When the user asks to redo, retry, or revise (e.g., \"try a new version\",\n\"redo the video with X\"), reuse the existing source images — do NOT regenerate them unless\nthe user explicitly asks for new images or describes changes to the images themselves.\nReference the existing result indices from the prior generation. If unsure whether the user\nwants new images, ask — don't regenerate by default.",
+  "parameterDocs": {
+    "prompt": "Text description. Follow FLUX.2 prompt order: subject first. Use Dynamic Prompt syntax when numberOfVariations > 1.",
+    "numberOfVariations": "Number of distinct outputs. Use Dynamic Prompt {|} syntax to vary one attribute per image. Never put the count in the prompt itself.",
+    "aspectRatio": "For ordinary images feeding a video tool, set to match the target video aspect ratio. For composite GPT Image 2 storyboard sheets, default the sheet pixel dimensions to a balanced grid that hosts the target cell aspect natively (portrait video target -> portrait/square sheet, landscape video target -> landscape sheet) unless the user explicitly specifies a storyboard page/canvas/sheet shape; keep the target video ratio inside each frame area."
+  }
+}

package/prompts/tools/generate_music.json

@@ -0,0 +1,7 @@
+{
+  "contractId": "generate_music_v1",
+  "version": "1.1.0",
+  "toolName": "generate_music",
+  "baseDescription": "generate_music creates music tracks with optional lyrics, BPM, key, and style control.\n\nMUSIC CREATIVE BRIEF: Identify purpose before composing: full song, short social hook,\njingle, trailer score, background underscore, sonic logo, music video cue, or lyric video.\nDefine genre, mood, tempo/BPM, energy curve, instrumentation, vocal style, lyrical point of\nview, hook phrase, section structure, and production notes. Lyrics should be original,\nsingable, sectioned, rhythmically clear, and have a memorable hook. Brand music should make\nthe brand easier to remember without stuffing the name into every line.\n\nFor music visualization (syncing the generated track to video), chain generate_music →\nsound_to_video. Do NOT use animate_photo or generate_video for audio-driven visualization.\n\nAfter generate_music, if the user asks to \"turn that song into a video\" or similar, call\nsound_to_video next — it auto-detects the latest generated music track.",
+  "parameterDocs": {}
+}

package/prompts/tools/generate_video.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "generate_video_v1",
+  "version": "1.1.0",
+  "toolName": "generate_video",
+  "baseDescription": "generate_video produces text-to-video clips and Seedance multimodal reference videos.\nUse for text-only video generation with no source image input. For Seedance, also use this\ntool when uploaded/generated images, videos, or audio are loose references. Use animate_photo\nonly when a non-Seedance source image must become the first frame of an LTX/WAN animation.\n\nSEEDANCE UPLOADED STORYBOARD DEFAULT: When the user uploads a storyboard, shot sheet,\nmood board, or trailer concept image and asks to make a movie trailer/video/clip from it,\ndefault to one Seedance generate_video call with referenceImageIndices=[-1]. Do not first\nextract panels with edit_image, do not generate replacement keyframes, and do not make four\nseparate LTX animate_photo clips unless the user explicitly asks for separate clips or LTX.\nUse seedance2 when premium Spark access is available; if premium access is unavailable,\nexplain the limitation or use the best non-Seedance fallback the user accepts.\n\nSTORYTELLING / COMMERCIAL / TRAILER PROMPTS: For creative video requests, turn the brief\ninto timed, causally connected visual beats before writing the final prompt. Default social\nvideo is 15s 9:16 with a strong first 1-2s, visible escalation, payoff, and brand/CTA/final\nimage. Commercials should show audience desire/problem, transformation, proof/benefit, and\nCTA. Trailers should follow hook → world → disruption → escalation → reveal → title/CTA.\nEvery beat must be generatable: subject, setting, action, camera, lighting, audio, and text\nrole where relevant. Avoid vague \"cinematic\" filler, feature dumps, and beautiful images with\nno visible change.\n\nVIDEO PROMPT QUOTING: ONLY use double quotes for spoken dialogue in video prompts. Never\nquote on-screen text, titles, captions, or visual text elements — describe them without\nquotes. Quotes signal speech to the model and confuse audio generation.\n\nSTORYBOARD TEXT: Structural headings, section numbers, slide titles, panel titles, and\ncaptions in storyboard references may become short audio-only narration/VO or\nkey-message beats, but they are not subtitles, title cards, lower thirds, or visible\noverlays unless the user explicitly asks for visible text, on-screen text, a title\ncard, subtitle, lower third, signage, or CTA. Keep narration as separate brief phrases\nwith pauses; do not concatenate storyboard labels into run-on voiceover.\n\nDIALOGUE DURATION: Spoken dialogue must fit the clip. Estimate 2.5 words per second\nnatural delivery plus ~1s per acting beat. Hard maximum 3.75 words/second.\nCheck: dialogue words ÷ 2.5 + beats ≤ duration. Do not submit oversized dialogue.\n\nLATEST USER DURATION WINS: In follow-up turns, use the newest duration the user states,\neven if a previous assistant message mentioned a longer script/runtime. For example, if\nhistory says \"the full script is 66 seconds\" but the user now says \"do a 30 second version\",\ngenerate the 30 second version. Do not ask a clarification question just because history\ncontains another duration; treat the latest user request as the override.\n\nSEEDANCE SHORT-DURATION LIMIT: Seedance supports 4-15s clips. If the user explicitly asks\nfor Seedance below 4s, do not silently round up. Ask whether they prefer a 4s Seedance clip\nor an exact-duration LTX clip. If the user did not explicitly ask for Seedance, choose the\nmodel/tool that can satisfy the requested duration exactly.",
+  "parameterDocs": {
+    "prompt": "Video prompt. Use double quotes ONLY for spoken dialogue. Describe visual text without quotes.",
+    "duration": "Clip duration in seconds. Plan dialogue word count against the 3.75 words/second ceiling."
+  }
+}

package/prompts/tools/inspect_asset.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "inspect_asset_v1",
+  "version": "1.0.0",
+  "toolName": "inspect_asset",
+  "baseDescription": "inspect_asset returns one manifest asset or the whole manifest. Use when the current\nmanifest state is unclear before referring to a generated asset by asset_id/user_label.\n\nDo not call it for ordinary uploaded references that the generation tools can use directly,\nand do not use it as a substitute for analyze_image/analyze_video content inspection.",
+  "parameterDocs": {
+    "asset_id": "Stable internal asset id. Prefer this when known.",
+    "user_label": "Human label to look up case-insensitively when asset_id is not known."
+  }
+}

package/prompts/tools/label_asset.json

@@ -0,0 +1,13 @@
+{
+  "contractId": "label_asset_v1",
+  "version": "1.0.0",
+  "toolName": "label_asset",
+  "baseDescription": "label_asset updates the label, description, URL, must_preserve, or avoid fields for an\nexisting manifest asset. Use when the user renames an asset, assigns a role, or when a\nprevious tool result adds durable reference constraints.\n\nDo not invent labels or preservation constraints that the user did not provide or that are\nnot present in a tool result.",
+  "parameterDocs": {
+    "asset_id": "Existing asset_id to update.",
+    "user_label": "New human-readable label when the user renames the asset.",
+    "description": "Replacement description. Keep it factual and concise.",
+    "must_preserve": "Replacement preservation list. Use only explicit or tool-result-backed constraints.",
+    "avoid": "Replacement avoid list. Use only explicit or tool-result-backed constraints."
+  }
+}

package/prompts/tools/manage_memory.json

@@ -0,0 +1,12 @@
+{
+  "contractId": "manage_memory_v1",
+  "version": "1.0.0",
+  "toolName": "manage_memory",
+  "baseDescription": "manage_memory reads, writes, or deletes persistent user preferences and facts. Use write\nonly when the user states a durable preference/fact or explicitly asks you to remember\nsomething. Use read when persistent preferences are relevant before generation.\n\nDo not save transient one-off creative instructions as memory. Delete/clear actions require\nexplicit user intent; never infer memory deletion from vague dissatisfaction.",
+  "parameterDocs": {
+    "action": "read, write, or delete. Use write only for durable preferences/facts; delete only on explicit request.",
+    "key": "Stable concise memory key. Required for write/delete.",
+    "value": "Concise durable value. Required for write.",
+    "category": "preference for style/defaults, fact for user facts, context for project context."
+  }
+}

package/prompts/tools/map_assets_for_model.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "map_assets_for_model_v1",
+  "version": "1.0.0",
+  "toolName": "map_assets_for_model",
+  "baseDescription": "map_assets_for_model is an inspection helper for previously generated asset-manifest entries\nwhen you need exact model_ref tokens for a later prompt.\n\nDo NOT call this for ordinary uploaded image references. If the user uploaded images and\nasks GPT Image 2 to use all uploaded assets as visual references, call edit_image directly\nwith sourceImageIndex=-1 and describe the uploaded assets/roles in the prompt. Uploaded\nreference images are already available to edit_image/generate_image; mapping them first\nwastes a tool round and may violate direct-generation requests.\n\nUse this helper only when a previous tool result produced assets in the manifest and the\nnext prompt must name those prior generated assets with provider-specific tokens.",
+  "parameterDocs": {
+    "model_id": "Target model for prior generated manifest refs. Do not use for plain uploaded references."
+  }
+}

package/prompts/tools/orbit_video.json

@@ -0,0 +1,13 @@
+{
+  "contractId": "orbit_video_v1",
+  "version": "1.0.0",
+  "toolName": "orbit_video",
+  "baseDescription": "orbit_video is a self-contained pipeline that handles angle generation, video transitions,\nand stitching internally. If the user uploaded an image, call orbit_video directly — it uses\nthe upload as the front view. If no image exists yet, generate ONE front-view image first,\nthen call orbit_video. Never pre-generate multiple angles or variations for orbit_video.\n\nORBIT DIALOGUE: When the user wants spoken dialogue in an orbit video, ALWAYS use the\ndialogue parameter (NOT prompt). Dialogue goes in ONLY the specified segment — put\nmotion/foley in prompt. If the user says \"only in the first segment\" or \"just at the start\",\nset dialogueSegment=0 (default). Never put dialogue text in the prompt parameter — it will\nbe duplicated across all segments.\n\nORBIT ANGLES: Do NOT send the angles parameter for standard 360° orbits — omit it entirely.\nThe default (right side view, back view, left side view at 90° increments) is correct for all\nnormal orbit requests. Only send angles when the user explicitly asks for specific azimuth\npositions (e.g. \"show me from the front-right and back-left only\") or a partial orbit.\n\nORBIT DIALOGUE UPDATE: For dialogue in multiple/every orbit segment, before every 90-degree\nturn, or with per-turn sequence numbers, use the dialogues array instead of the single dialogue\nparameter. Default 360-degree orbit has 4 transitions, so provide 4 short lines in order; leave\nprompt for subject, action, ambient audio, and foley only. Preserve the real names from the\nrequest/prior result; never invent placeholder speaker tags. For a couple/persona request\nphrased as \"us\", \"we\", or \"my wife and I\", each per-turn line should make the named people\nspeak together. When the user picks a generated image by 1-based number (\"number 3\",\n\"use #3\"), pass sourceImageIndex as that number minus one (number 3 -> sourceImageIndex=2)\ninstead of omitting it.",
+  "parameterDocs": {
+    "dialogue": "Spoken dialogue for the first/default orbit segment. Do NOT put dialogue in prompt — it repeats across all segments.",
+    "dialogues": "Per-segment dialogue lines array. Use for multi-segment dialogue (4 lines for full 360° orbit).",
+    "dialogueSegment": "Which orbit segment gets the dialogue (0-based). Default 0 = first segment.",
+    "angles": "Omit for standard 360° orbits. Only set for explicit azimuth positions or partial orbits.",
+    "sourceImageIndex": "Use uploaded image if present. If user picks by 1-based number, subtract 1."
+  }
+}

package/prompts/tools/overlay_video.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "overlay_video_v1",
+  "version": "1.0.0",
+  "toolName": "overlay_video",
+  "baseDescription": "Use overlay_video when the user wants to overlay/place/show a logo, text, caption, or\nwatermark ON TOP OF existing video frames.\n\nFor uploaded base videos, set sourceVideoIndex=-1; for generated videos, use their\nnon-negative video index. If the overlay should last only part of the video, set the overlay\nitem's startSeconds/endSeconds (e.g. a 2s middle overlay on a 20s video: ~9s to ~11s).\nNegative startSeconds/endSeconds are relative to the end of the base video, so startSeconds=-2\nwith omitted endSeconds means the last 2 seconds.\n\nWhen the user asks to replace a video time window with an uploaded still image, screenshot,\nphoto, frame, logo, or graphic, use an image overlay for that window with widthPct=100 and\nfit=\"cover\"; do not regenerate the video segment.\n\nDo NOT use overlay_video for intro/outro/bumper/end-card/start-card requests — those add or\nregenerate video time and should use extend_video or replace_video_segment. After a successful\noverlay_video call, finalize the turn; do not call overlay_video again just to tweak default\nsize or placement unless the user asks.",
+  "parameterDocs": {
+    "sourceVideoIndex": "Use -1 for first uploaded video, non-negative index for generated videos.",
+    "overlays": "Use startSeconds/endSeconds for time windows. For still/screenshot replacement windows, use kind=\"image\", widthPct=100, fit=\"cover\"."
+  }
+}

package/prompts/tools/refine_result.json

@@ -0,0 +1,11 @@
+{
+  "contractId": "refine_result_v1",
+  "version": "1.0.0",
+  "toolName": "refine_result",
+  "baseDescription": "refine_result is the default follow-up image-edit tool after generated results exist. Use it\nfor targeted changes to a prior result: color, brightness, sharpening, background changes,\nobject edits, further restoration, or small creative adjustments.\n\nDescribe only the delta. The source image already contains the subject, composition, and\nmost details. Do not rewrite the whole image unless the user asks for a broad transformation.\nFor people, front-load exact identity preservation and end with preserving all unmentioned\ndetails.\n\nUse restore_photo instead only when the user explicitly asks to start over from the original\nupload. Use sourceImageIndex only when the user names a specific result.",
+  "parameterDocs": {
+    "prompt": "Targeted delta instruction. Preserve identity first for people, then specify the change, then preserve everything else.",
+    "sourceImageIndex": "Omit for the latest relevant result unless the user names a specific image number.",
+    "numberOfVariations": "Use 1 unless the user asks to compare multiple refinement options."
+  }
+}

package/prompts/tools/replace_video_segment.json

@@ -0,0 +1,14 @@
+{
+  "contractId": "replace_video_segment_v1",
+  "version": "1.0.0",
+  "toolName": "replace_video_segment",
+  "baseDescription": "Use replace_video_segment when the user wants to regenerate a specific time range of an\nexisting video: \"regenerate from Xs to Ys\", \"redo the last N seconds\", \"swap out the middle\",\n\"fix the [start/middle/end] of the video\", or \"replace the [bumper/intro/outro/end card/\ntag/sting] at the [start/end] of the video\". Use explicit startSeconds and endSeconds; use\n-1 sentinels when exact base duration is unknown — the handler probes and resolves.\n\nWhen the replacement is already another uploaded or generated video clip, still use\nreplace_video_segment but pass replacementVideoIndex. Example: \"splice video 2 into video 1\nat 5s\" means videoIndex=-1, replacementVideoIndex=-2, startSeconds=5, endSeconds=5.\nUse endSeconds=startSeconds for insertion; use a wider endSeconds only when the user says to\nreplace/remove that base-video range. Do not use stitch_video for \"into the middle\"/\"insert\"\nrequests, because stitch_video only concatenates full clips end-to-end.\n\nFor time-sliced interleaving from existing videos — \"alternate 1s from each video\", \"weave\none-second clips from video 1 and video 2\", \"cut back and forth every N seconds\" — do NOT\nuse stitch_video and do NOT omit replacementVideoIndex. Start with the first requested video\nas the base, then call replace_video_segment once for each window that should come from the\nother video. Set replacementVideoIndex to that other existing video and set\nreplacementStartSeconds/replacementEndSeconds to the next source slice from that\nreplacement video. For ordinary\nalternation, preserve the base duration: set endSeconds=startSeconds+sliceDuration, not\nendSeconds=startSeconds insertion, unless the user explicitly asks to lengthen the output by\ninserting extra slices. Skip no-op windows that already come from the base video; only splice\nwindows that should come from a different source. Example for two 10s uploads alternating every 1s starting with video\n1: replace base windows 1..2, 3..4,\n5..6, 7..8, and 9..10 with slices 0..1, 1..2, 2..3, 3..4, and 4..5 from video 2. After\neach successful splice, target the newest composite video index for the next splice.\nThe -1 time sentinel applies only to base startSeconds/endSeconds when the base duration is\nunknown. Never use -1 for replacementStartSeconds or replacementEndSeconds; source windows\nmust use concrete non-negative seconds. For uploaded/generated videos with duration metadata,\nuse that known duration directly; do not call analyze_video just to learn the clip length for\nroutine alternating slices. Do not add a final tail splice with an unknown source end — stop at\nthe known clip duration or skip a no-op tail window.\n\nDo NOT call generate_video or animate_photo to re-render an existing video just to change\npart of it (the bumper, the intro, the end card, a single scene, the last few seconds, etc.).\nUse replace_video_segment — it preserves the unchanged portion, keeps the original audio\noutside the replaced window, and costs far less.\n\nAuto-detects the base video's model, so OMIT videoModel unless the user explicitly demands\na different model. Short requested windows are supported by rendering with model-specific\nhandles and trimming the rendered clip before splicing, so still pass the user's exact\nstartSeconds/endSeconds.",
+  "parameterDocs": {
+    "startSeconds": "Start of segment to replace in seconds. Use -1 sentinel if exact base duration is unknown.",
+    "endSeconds": "End of segment to replace in seconds. Use the same value as startSeconds for insertion with replacementVideoIndex.",
+    "replacementVideoIndex": "Existing uploaded/generated replacement clip. Use negative uploaded-video indices, e.g. -2 for the second uploaded video.",
+    "replacementStartSeconds": "Optional start time inside replacementVideoIndex. Use with replacementEndSeconds for time-sliced interleaving. Must be concrete and >= 0; never use -1 here.",
+    "replacementEndSeconds": "Optional end time inside replacementVideoIndex. Must be concrete, >= 0, and greater than replacementStartSeconds; never use -1 here.",
+    "videoModel": "Omit to auto-detect from source. Only set if user explicitly requests a different model."
+  }
+}

package/prompts/tools/resolve_personas.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "resolve_personas_v1",
+  "version": "1.0.0",
+  "toolName": "resolve_personas",
+  "baseDescription": "resolve_personas is the required first step when the user explicitly names a saved Persona\nor says to use a Persona Image, Persona reference photo, Persona Voice, registered voice,\nor voice clone. Do not answer in prose, ask a follow-up, or finalize before calling this\ntool when a listed Persona name is present.\n\nDIRECT PERSONA IMAGE / VOICE VIDEO: If the user says to use the Persona image/reference\ndirectly/originally, call resolve_personas first, then call animate_photo using the injected\npersona photo as an uploaded image index. For one named Persona, use sourceImageIndex=-1\nor sourceImageIndices=[-1,...] for a multi-clip batch. If Persona Voice was explicitly\nrequested, set voicePersonaName to the exact resolved Persona name and use an LTX model.\nDo not call generate_video for Persona image/voice videos. Do not generate a new image first\nwhen the user explicitly requested the existing Persona image directly.\n\nMULTI-CLIP PERSONA BATCHES: If the user asks for several separate clips from the same\nPersona Image, make one animate_photo call after resolve_personas with repeated persona\nsource indices, one prompt per clip, and the requested per-clip duration. If the user asks\nto stitch the clips, call stitch_video with the returned video indices after animate_photo.",
+  "parameterDocs": {
+    "names": "Persona names to load. Use the exact listed Persona name; call this before any Persona image/voice video or image generation."
+  }
+}

package/prompts/tools/restore_photo.json

@@ -0,0 +1,12 @@
+{
+  "contractId": "restore_photo_v1",
+  "version": "1.0.0",
+  "toolName": "restore_photo",
+  "baseDescription": "restore_photo edits or restores the ORIGINAL uploaded photograph. Use this for the first\nrestoration/edit on an upload, or when the user explicitly asks to start over from the\noriginal/source photo. Use refine_result for follow-up edits to an existing generated result.\n\nFor photos with people, front-load identity preservation before the restoration or edit.\nUse positive constraints such as preserve exact facial likeness, face structure, apparent\nage, pose, and composition. End with preservation of unmentioned details.\n\nUse Dynamic Prompt syntax only when the user explicitly asks to compare multiple restoration\napproaches. Default restoration batches should keep the same prompt and vary only by seed.",
+  "parameterDocs": {
+    "prompt": "Natural-language edit/restoration prompt. Start with identity preservation for people, then requested restoration/edit, then preserve unmentioned details.",
+    "numberOfVariations": "Use 1 unless the user explicitly asks for multiple outputs or comparison options.",
+    "scale": "Set only when the user asks to upscale, enlarge, or increase resolution.",
+    "quality": "Omit unless the user explicitly asks for fast or high quality."
+  }
+}