@sogni-ai/sogni-protocol 1.0.0-alpha.25 → 1.0.0-alpha.26

package/manifests/composition-tools.json

@@ -12,26 +12,26 @@
       "type": "function",
       "function": {
         "name": "enhance_prompt",
-        "description": "Enhance or adapt a source prompt into a model-ready image, video, music, or edit prompt. Use for prompt expansion and model-specific prompt preparation. Do not use for lyrics or full scripts.",
+        "description": "Author or adapt a directly runnable image, video, or image-edit prompt in an exact active model's native format. Use this when the requested text deliverable is explicitly a prompt for a named media model, including a commercial prompt; always pass destination_model and the matching target_output. Unknown, sunset, or omitted models fail closed. Do not use for lyrics, music composition, screenplays, storyboards, treatments, or ad scripts.",
         "parameters": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["prompt"],
+          "required": ["prompt", "target_output", "destination_model"],
           "properties": {
             "prompt": { "type": "string", "description": "The source prompt, rough idea, or prompt revision request to enhance." },
-            "target_output": { "type": "string", "enum": ["image_prompt", "video_prompt", "music_prompt", "edit_prompt", "model_prompt", "general_prompt"], "description": "The kind of prompt artifact to produce." },
-            "destination_model": { "type": "string", "description": "Optional destination model selector, such as seedance2, ltx23, wan22, gpt-image-2, or sdxl." },
-            "destination_tool": { "type": "string", "description": "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": { "type": "string", "enum": ["flux", "sdxl", "sd15", "pony", "fast", "sd3", "editing", "video"], "description": "Optional image-prompting family when producing an image prompt." },
-            "model_title": { "type": "string", "description": "Optional human-readable target model name for image prompt guidance." },
+            "target_output": { "type": "string", "enum": ["image_prompt", "video_prompt", "edit_prompt", "model_prompt"], "description": "The model-specific prompt artifact to produce. Use model_prompt only when destination_model unambiguously identifies the modality." },
+            "destination_model": { "type": "string", "description": "Required exact active destination model selector, such as seedance2, ltx25, ltx23, wan22, minimax-h3-turbo, qwen, gpt-image-2, krea-2-turbo, chroma-v46-flash, or sdxl. Unknown and sunset models fail closed." },
+            "destination_tool": { "type": "string", "description": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, or video_to_video." },
+            "prompting_type": { "type": "string", "enum": ["flux", "sdxl", "sd15", "pony", "fast", "sd3", "editing", "video"], "description": "Deprecated compatibility metadata. It never selects or overrides the prompt grammar; destination_model is authoritative." },
+            "model_title": { "type": "string", "description": "Deprecated compatibility label. It never selects or overrides the prompt grammar; destination_model is authoritative." },
             "style_prompt": { "type": "string", "description": "Optional current style, brand, or prompt context to complement without repeating." },
             "prompt_mode": { "type": "string", "enum": ["auto", "preserve", "expand", "compress", "validate", "payload"], "description": "Optional model prompt adaptation mode." },
-            "duration_seconds": { "type": "number", "minimum": 1, "maximum": 300, "description": "Requested runtime when enhancing a video or music prompt." },
+            "duration_seconds": { "type": "number", "minimum": 1, "maximum": 300, "description": "Requested runtime when authoring a video prompt." },
             "aspect_ratio": { "type": "string", "description": "Optional target aspect ratio, such as 16:9, 9:16, 1:1, 4:5, or 21:9." },
             "assets": {
               "type": "array",
-              "maxItems": 12,
-              "description": "Optional available assets the enhanced prompt may reference.",
+              "maxItems": 50,
+              "description": "Optional available assets the authored prompt may reference. The selected exact model contract applies its per-modality and total limits.",
               "items": {
                 "type": "object",
                 "additionalProperties": false,
@@ -89,7 +89,7 @@
       "type": "function",
       "function": {
         "name": "compose_script",
-        "description": "Compose scripts, storyboards, video prompts, ad concepts, trailers, social shorts, campaign beats, and talking-head plans. Use for creative writing artifacts. Do not use for lyrics or simple prompt expansion.",
+        "description": "Compose scripts, screenplays, storyboards, treatments, ad concepts, trailers, social shorts, campaign beats, and talking-head plans. Use for creative-writing artifacts that are not directly runnable model prompts. When the user explicitly asks for a prompt for a named image or video model, use enhance_prompt instead, even if the prompt is for a commercial. Do not use for lyrics.",
         "parameters": {
           "type": "object",
           "additionalProperties": false,

package/manifests/openai-tools.json

@@ -1314,12 +1314,14 @@
       "type": "function",
       "function": {
         "name": "enhance_prompt",
-        "description": "Enhance or adapt a source prompt into a model-ready image, video, music, or edit prompt. Use for prompt expansion and model-specific prompt preparation. Do not use for lyrics or full scripts.",
+        "description": "Author or adapt a directly runnable image, video, or image-edit prompt in an exact active model's native format. Use this when the requested text deliverable is explicitly a prompt for a named media model, including a commercial prompt; always pass destination_model and the matching target_output. Unknown, sunset, or omitted models fail closed. Do not use for lyrics, music composition, screenplays, storyboards, treatments, or ad scripts.",
         "parameters": {
           "type": "object",
           "additionalProperties": false,
           "required": [
-            "prompt"
+            "prompt",
+            "target_output",
+            "destination_model"
           ],
           "properties": {
             "prompt": {
@@ -1331,20 +1333,18 @@
               "enum": [
                 "image_prompt",
                 "video_prompt",
-                "music_prompt",
                 "edit_prompt",
-                "model_prompt",
-                "general_prompt"
+                "model_prompt"
               ],
-              "description": "The kind of prompt artifact to produce."
+              "description": "The model-specific prompt artifact to produce. Use model_prompt only when destination_model unambiguously identifies the modality."
             },
             "destination_model": {
               "type": "string",
-              "description": "Optional destination model selector, such as seedance2, ltx23, wan22, gpt-image-2, or sdxl."
+              "description": "Required exact active destination model selector, such as seedance2, ltx25, ltx23, wan22, minimax-h3-turbo, qwen, gpt-image-2, krea-2-turbo, chroma-v46-flash, or sdxl. Unknown and sunset models fail closed."
             },
             "destination_tool": {
               "type": "string",
-              "description": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, video_to_video, or generate_music."
+              "description": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, or video_to_video."
             },
             "prompting_type": {
               "type": "string",
@@ -1358,11 +1358,11 @@
                 "editing",
                 "video"
               ],
-              "description": "Optional image-prompting family when producing an image prompt."
+              "description": "Deprecated compatibility metadata. It never selects or overrides the prompt grammar; destination_model is authoritative."
             },
             "model_title": {
               "type": "string",
-              "description": "Optional human-readable target model name for image prompt guidance."
+              "description": "Deprecated compatibility label. It never selects or overrides the prompt grammar; destination_model is authoritative."
             },
             "style_prompt": {
               "type": "string",
@@ -1384,7 +1384,7 @@
               "type": "number",
               "minimum": 1,
               "maximum": 300,
-              "description": "Requested runtime when enhancing a video or music prompt."
+              "description": "Requested runtime when authoring a video prompt."
             },
             "aspect_ratio": {
               "type": "string",
@@ -1392,8 +1392,8 @@
             },
             "assets": {
               "type": "array",
-              "maxItems": 12,
-              "description": "Optional available assets the enhanced prompt may reference.",
+              "maxItems": 50,
+              "description": "Optional available assets the authored prompt may reference. The selected exact model contract applies its per-modality and total limits.",
               "items": {
                 "type": "object",
                 "additionalProperties": false,
@@ -1510,7 +1510,7 @@
       "type": "function",
       "function": {
         "name": "compose_script",
-        "description": "Compose scripts, storyboards, video prompts, ad concepts, trailers, social shorts, campaign beats, and talking-head plans. Use for creative writing artifacts. Do not use for lyrics or simple prompt expansion.",
+        "description": "Compose scripts, screenplays, storyboards, treatments, ad concepts, trailers, social shorts, campaign beats, and talking-head plans. Use for creative-writing artifacts that are not directly runnable model prompts. When the user explicitly asks for a prompt for a named image or video model, use enhance_prompt instead, even if the prompt is for a commercial. Do not use for lyrics.",
         "parameters": {
           "type": "object",
           "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-protocol",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.26",
   "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",

package/prompts/tools/compose_script.json

@@ -1,8 +1,8 @@
 {
   "contractId": "compose_script_v1",
-  "version": "1.0.0",
+  "version": "1.1.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.",
+  "baseDescription": "compose_script composes scripts, screenplays, storyboards, treatments, ad concepts, trailers,\nsocial shorts, campaign beats, and talking-head plans. Use it for prose, scenes, beats, or\nother script-shaped creative-writing deliverables.\n\nWhen the user explicitly asks for a directly runnable prompt for a named image or video\nmodel, use enhance_prompt instead, even when the subject is a commercial. Do not use\ncompose_script for song lyrics, instrumental composition, simple prompt authoring, or a\nrunnable multi-step workflow.\n\ncompose_script returns a creative-writing deliverable. When that deliverable will later feed\na video pipeline, destination_tool and destination_model may record the intended handoff;\nthey do not turn the result into the model's native prompt contract.",
   "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.",

package/prompts/tools/enhance_prompt.json

@@ -1,20 +1,20 @@
 {
   "contractId": "enhance_prompt_v1",
-  "version": "1.0.0",
+  "version": "1.1.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.).",
+  "baseDescription": "enhance_prompt authors a directly runnable image, video, or image-edit prompt in the native\nformat of one exact active destination model. Use it when the requested text deliverable is\nexplicitly a prompt for a named media model, including a commercial prompt. The caller must\nprovide destination_model and target_output; unknown, sunset, and omitted models fail closed.\n\nDo not use enhance_prompt for model-neutral prompts, music composition, lyrics, screenplays,\nstoryboards, treatments, ad scripts, or multi-step workflow plans. Use compose_script for\ncreative-writing artifacts, compose_lyrics or compose_instrumental for music, and\ncompose_workflow or compose_workflow_template for workflows.\n\nenhance_prompt returns prompt text only. The caller is responsible for handing it to the\nmatching downstream generation tool.",
   "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, ltx25, ltx23, wan22, 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.",
+    "target_output": "Required model-specific artifact kind: image_prompt, video_prompt, edit_prompt, or model_prompt. Use model_prompt only when destination_model identifies the modality.",
+    "destination_model": "Required exact active model selector. Unknown and sunset models fail closed.",
+    "destination_tool": "Optional matching downstream generation tool for the authored prompt.",
+    "prompting_type": "Deprecated compatibility metadata. It never selects or overrides the prompt grammar; destination_model is authoritative.",
+    "model_title": "Deprecated compatibility label. It never selects or overrides the prompt grammar; destination_model is authoritative.",
     "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.",
+    "duration_seconds": "Requested runtime in seconds (1-300) when authoring a video 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.",
+    "assets": "Optional available assets (schema max 50) the prompt may reference. The exact destination model applies smaller per-modality and total limits.",
     "constraints": "Optional production, brand, model, or user constraints to preserve."
   }
 }

package/schemas/tools/compose_script.schema.json

@@ -1,7 +1,7 @@
 {
   "title": "compose_script tool schema",
   "schemaVersion": "2026-05-14.1",
-  "description": "Synchronous creative writing utility for scripts, storyboards, video prompts, ad concepts, trailers, social shorts, campaign beats, and talking-head plans.",
+  "description": "Synchronous creative-writing utility for scripts, screenplays, storyboards, treatments, ad concepts, trailers, social shorts, campaign beats, and talking-head plans. Directly runnable prompts for named media models belong to enhance_prompt.",
   "type": "object",
   "additionalProperties": false,
   "required": ["brief"],

package/schemas/tools/enhance_prompt.schema.json

@@ -1,10 +1,10 @@
 {
   "title": "enhance_prompt tool schema",
   "schemaVersion": "2026-05-14.1",
-  "description": "Synchronous prompt enhancement utility for expanding or adapting a source prompt into a model-ready image, video, music, or edit prompt.",
+  "description": "Synchronous prompt-authoring utility for expanding or adapting a source prompt into an exact active image, video, or image-edit model's native prompt format.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["prompt"],
+  "required": ["prompt", "target_output", "destination_model"],
   "properties": {
     "prompt": {
       "type": "string",
@@ -12,25 +12,25 @@
     },
     "target_output": {
       "type": "string",
-      "enum": ["image_prompt", "video_prompt", "music_prompt", "edit_prompt", "model_prompt", "general_prompt"],
-      "description": "The kind of prompt artifact to produce."
+      "enum": ["image_prompt", "video_prompt", "edit_prompt", "model_prompt"],
+      "description": "The model-specific prompt artifact to produce. Use model_prompt only when destination_model unambiguously identifies the modality."
     },
     "destination_model": {
       "type": "string",
-      "description": "Optional destination model selector, such as seedance2, ltx25, ltx23, wan22, gpt-image-2, or sdxl."
+      "description": "Required exact active destination model selector, such as seedance2, ltx25, ltx23, wan22, minimax-h3-turbo, qwen, gpt-image-2, krea-2-turbo, chroma-v46-flash, or sdxl. Unknown and sunset models fail closed."
     },
     "destination_tool": {
       "type": "string",
-      "description": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, video_to_video, or generate_music."
+      "description": "Optional downstream generation tool, such as generate_image, edit_image, generate_video, animate_photo, sound_to_video, or video_to_video."
     },
     "prompting_type": {
       "type": "string",
       "enum": ["flux", "sdxl", "sd15", "pony", "fast", "sd3", "editing", "video"],
-      "description": "Optional image-prompting family when producing an image prompt."
+      "description": "Deprecated compatibility metadata. It never selects or overrides the prompt grammar; destination_model is authoritative."
     },
     "model_title": {
       "type": "string",
-      "description": "Optional human-readable target model name for image prompt guidance."
+      "description": "Deprecated compatibility label. It never selects or overrides the prompt grammar; destination_model is authoritative."
     },
     "style_prompt": {
       "type": "string",
@@ -45,7 +45,7 @@
       "type": "number",
       "minimum": 1,
       "maximum": 300,
-      "description": "Requested runtime when enhancing a video or music prompt."
+      "description": "Requested runtime when authoring a video prompt."
     },
     "aspect_ratio": {
       "type": "string",
@@ -53,8 +53,8 @@
     },
     "assets": {
       "type": "array",
-      "maxItems": 12,
-      "description": "Optional available assets the enhanced prompt may reference.",
+      "maxItems": 50,
+      "description": "Optional available assets the authored prompt may reference. The selected exact model contract applies its per-modality and total limits.",
       "items": {
         "type": "object",
         "additionalProperties": false,

package/version.json

@@ -1,4 +1,4 @@
 {
-  "protocolVersion": "2.1.0",
+  "protocolVersion": "3.0.0",
   "description": "Sogni protocol artifact version. SDKs may refuse to operate against a protocolVersion they were not built for. Bump the major when removing or renaming any schema / enum / manifest field; bump the minor when adding new optional fields or new tools; bump the patch for description / prose changes only."
 }