@sogni-ai/sogni-protocol 1.0.0-alpha.4 → 1.0.0-alpha.41

package/README.md

@@ -24,7 +24,7 @@ This package ships pure data — JSON Schemas, OpenAI tool manifests, prompt con
 | `enums/chat-run-waiting-reasons.json` | Why a run is paused for user input. | All SDKs. |
 | `enums/token-types.json` | Sogni billing token types (`sogni`, `spark`). | All SDKs. |
 | `catalogs/quality-presets.json` | Quality tier presets (fast/hq/pro) -> model + sampling parameters. | UI SDKs rendering quality toggles. |
-| `catalogs/audio-models.json` | ACE-Step audio model capability table + duration/BPM/time-signature constraints. | SDKs validating music-gen input. |
+| `catalogs/audio-models.json` | ACE-Step + MiniMax Music 3 audio model capability table + duration/BPM/time-signature constraints. | SDKs validating music-gen input. |
 | `version.json` | Protocol version for compatibility checks. | All SDKs. |
 
 ## Why a separate package
@@ -78,3 +78,12 @@ Tool prompt prose lives in `prompts/tools/*.json`. Each file is one [`PromptCont
 ## Editing schemas
 
 The JSON Schema files under `schemas/` are the authoritative wire-spec shape. Any change here is a protocol bump (minor or major depending on compatibility). Consumers regenerate their language-specific types via their codegen step.
+
+## v2 contract docs
+
+This branch carries the additive schemas for the Sogni Platform v2 execution architecture. Two markdown documents under [`docs/`](./docs/) describe the new surface for downstream consumers:
+
+- [`docs/v2-changes-summary.md`](./docs/v2-changes-summary.md) — concise map of the 8 new schemas (IntentInput, TurnAnalysis, ToolMetadata, ArtifactNode, ArtifactGraph, SpendGate, WorkflowAuthorization, RunEvent) and per-consumer impact.
+- [`docs/v2-consumer-contract.md`](./docs/v2-consumer-contract.md) — full integration contract for native `sogni` (Mac/iOS via SogniKit codegen) and `sogni-creative-agent-skill`. Covers transport choice, classifier/regex replacement plan, artifact-graph projection, tool-surface budget, preserved public API params, and the workflow charging model.
+
+v2 does not implement migration in the native or skill repos; their teams own implementation timing against this contract.

package/catalogs/audio-models.json

@@ -1,20 +1,76 @@
 {
-  "description": "Audio / music generation model catalog. ACE-Step 1.5 family. Each entry lists per-parameter ranges so SDKs can validate user input and render sliders without round-tripping to the server. Cross-cutting audio constraints (duration, BPM, time signatures) live in the top-level `constraints` block.",
+  "description": "Audio / music generation model catalog. ACE-Step 1.5 family plus MiniMax Music 3. Each entry lists per-parameter ranges so SDKs can validate user input and render sliders without round-tripping to the server. Cross-cutting audio constraints (duration, BPM, time signatures) live in the top-level `constraints` block; models with different limits carry a per-model `constraints` override.",
   "default": "turbo",
   "models": {
     "turbo": {
       "id": "ace_step_1.5_turbo",
       "name": "ACE-Step 1.5 Turbo",
-      "steps": { "min": 4, "max": 16, "default": 8 },
-      "shift": { "min": 1, "max": 5, "default": 3 },
+      "steps": {
+        "min": 4,
+        "max": 16,
+        "default": 8
+      },
+      "shift": {
+        "min": 1,
+        "max": 5,
+        "default": 3
+      },
       "guidance": null
     },
     "sft": {
       "id": "ace_step_1.5_sft",
       "name": "ACE-Step 1.5 SFT",
-      "steps": { "min": 10, "max": 200, "default": 50 },
-      "shift": { "min": 1, "max": 5, "default": 3 },
-      "guidance": { "min": 1, "max": 15, "default": 5 }
+      "steps": {
+        "min": 10,
+        "max": 200,
+        "default": 50
+      },
+      "shift": {
+        "min": 1,
+        "max": 5,
+        "default": 3
+      },
+      "guidance": {
+        "min": 1,
+        "max": 15,
+        "default": 5
+      }
+    },
+    "music3": {
+      "id": "minimax_music3",
+      "name": "MiniMax Music 3",
+      "steps": {
+        "min": 10,
+        "max": 100,
+        "default": 30
+      },
+      "shift": null,
+      "guidance": {
+        "min": 1,
+        "max": 5,
+        "default": 1.7
+      },
+      "promptStrength": {
+        "min": 0,
+        "max": 10,
+        "default": 1.7
+      },
+      "topK": {
+        "min": 1,
+        "max": 16384,
+        "default": 50
+      },
+      "constraints": {
+        "duration": {
+          "min": 10,
+          "max": 300,
+          "default": 60,
+          "unit": "seconds",
+          "note": "Maximum duration; the planner composes an ending and may stop earlier."
+        },
+        "bpm": null,
+        "timeSignatures": null
+      }
     }
   },
   "constraints": {
@@ -29,6 +85,11 @@
       "max": 300,
       "default": 120
     },
-    "timeSignatures": [2, 3, 4, 6]
+    "timeSignatures": [
+      2,
+      3,
+      4,
+      6
+    ]
   }
 }

package/catalogs/quality-presets.json

@@ -19,12 +19,12 @@
       "description": "More detail"
     },
     "pro": {
-      "model": "flux2_dev_fp8",
-      "steps": 40,
+      "model": "qwen_image_edit_2511_fp8",
+      "steps": 25,
       "guidance": 4.0,
       "outputFormat": "jpg",
       "label": "Pro",
-      "description": "Flux.2 Dev"
+      "description": "Maximum Qwen detail"
     }
   }
 }

package/catalogs/seedance-reference-limits.json

@@ -1,9 +1,29 @@
 {
-  "description": "Maximum loose-reference assets accepted per Seedance 2.0 video generation request. SDKs use this catalog to validate user input client-side and to render UI affordances (e.g. disable an upload button once the per-modality cap or the combined-total cap is reached). The numbers mirror the BytePlus Dreamina Seedance 2.0 platform limits and are the same values previously hard-coded in sogni-chat's orchestration. Per-video request: at most `images` image refs (start frame + end frame + loose `referenceImageUrls`), `videos` video refs, and `audios` audio refs, with at most `assets` total ref files across all three modalities.",
+  "description": "Maximum loose-reference assets accepted per Seedance video generation request. SDKs use this catalog to validate user input client-side and to render UI affordances (e.g. disable an upload button once the per-modality cap or the combined-total cap is reached). The numbers mirror the BytePlus Dreamina Seedance platform limits and are the same values previously hard-coded in sogni-chat's orchestration. Per-video request: at most `images` image refs (start frame + end frame + loose `referenceImageUrls`), `videos` video refs, and `audios` audio refs, with at most `assets` total ref files across all three modalities. The caps are per-model: model-aware consumers should read `perModel[<canonical model id>]` and reject unknown model IDs rather than guessing. `limits` intentionally remains the backwards-compatible default for consumers that do not select a model and carries the Seedance 2.0 family numbers so an SDK built against an older protocol under-permits rather than over-permits.",
   "limits": {
     "images": 9,
     "videos": 3,
     "audios": 3,
     "assets": 12
+  },
+  "perModel": {
+    "seedance-2-0": {
+      "images": 9,
+      "videos": 3,
+      "audios": 3,
+      "assets": 12
+    },
+    "seedance-2-0-mini": {
+      "images": 9,
+      "videos": 3,
+      "audios": 3,
+      "assets": 12
+    },
+    "seedance-2-5": {
+      "images": 30,
+      "videos": 10,
+      "audios": 10,
+      "assets": 50
+    }
   }
 }

package/enums/tool-names.json

@@ -16,6 +16,7 @@
     "extend_video",
     "generate_image",
     "generate_music",
+    "generate_speech",
     "generate_video",
     "orbit_video",
     "overlay_video",
@@ -24,6 +25,8 @@
     "restore_photo",
     "sound_to_video",
     "stitch_video",
+    "upscale_image",
+    "upscale_video",
     "video_to_video"
   ],
   "app": [
@@ -60,6 +63,7 @@
     "finalize_response",
     "generate_image",
     "generate_music",
+    "generate_speech",
     "generate_video",
     "inspect_asset",
     "label_asset",
@@ -74,6 +78,8 @@
     "set_content_filter",
     "sound_to_video",
     "stitch_video",
+    "upscale_image",
+    "upscale_video",
     "validate_asset_references",
     "video_to_video"
   ],

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, flux2, 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,
@@ -131,7 +131,7 @@
               "type": "object",
               "additionalProperties": false,
               "properties": {
-                "image": { "type": "string", "description": "Preferred image model (e.g., 'flux2', 'gpt-image-2')." },
+                "image": { "type": "string", "description": "Preferred image model (e.g., 'gpt-image-2', 'qwen')." },
                 "video": { "type": "string", "description": "Preferred video model (e.g., 'ltx23', 'wan22', 'seedance2')." },
                 "music": { "type": "string", "description": "Preferred music model." }
               }
@@ -207,7 +207,7 @@
               "type": "object",
               "additionalProperties": false,
               "properties": {
-                "image": { "type": "string", "description": "Preferred image model (e.g., 'flux2', 'gpt-image-2')." },
+                "image": { "type": "string", "description": "Preferred image model (e.g., 'gpt-image-2', 'qwen')." },
                 "video": { "type": "string", "description": "Preferred video model (e.g., 'ltx23', 'wan22', 'seedance2')." },
                 "music": { "type": "string", "description": "Preferred music model." }
               }