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

package/README.md

@@ -0,0 +1,80 @@
+# @sogni-ai/sogni-protocol
+
+The language-neutral protocol artifacts for the [Sogni](https://sogni.ai) ecosystem.
+
+This package ships pure data — JSON Schemas, OpenAI tool manifests, prompt contracts, and enums — that every Sogni SDK consumes so contracts stay in lockstep across languages.
+
+## What's inside
+
+| Path | What it is | Who consumes it |
+|---|---|---|
+| `schemas/tools/*.json` | JSON Schema for each hosted creative tool's arguments. | All SDKs (codegen types + runtime validation). |
+| `schemas/errors/*.json` | Error envelope + repair-control shape. | All SDKs. |
+| `schemas/events/*.json` | Chat-run + workflow event shapes. | All SDKs. |
+| `schemas/workflows/*.json` | Durable workflow record + step shapes. | All SDKs. |
+| `schemas/storyboards/*.json` | Storyboard planning contract. | TS SDK + chat product. |
+| `schemas/prompt-contract.schema.json` | Shape every `prompts/tools/*.json` file validates against. | Editors of prompt prose. |
+| `manifests/openai-tools.json` | Merged hosted-tool OpenAI function manifest (generation + composition). | TS SDK runtime, future agent SDKs. |
+| `manifests/generation-tools.json` | Generation subset of the hosted manifest. | TS SDK. |
+| `manifests/composition-tools.json` | Composition subset of the hosted manifest. | TS SDK. |
+| `manifests/app-tools.json` | Chat-app local tools (analyze_image, manage_memory, etc.). | Chat product SDKs. |
+| `prompts/tools/*.json` | Per-tool LLM-visible descriptions + parameter docstrings (`PromptContract`). | All SDKs that surface tools to an LLM. |
+| `enums/tool-names.json` | Canonical tool name catalogs (hosted / app / chatLocal / all). | Validators, codegen. |
+| `enums/chat-run-status.json` | Chat-run lifecycle states. | All SDKs. |
+| `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. |
+| `version.json` | Protocol version for compatibility checks. | All SDKs. |
+
+## Why a separate package
+
+Sogni ships SDKs in multiple languages (TypeScript `@sogni-ai/sogni-client`, Swift `SogniKit`, more on the way). Tool schemas, prompts, and enums need to be the same everywhere. Holding them in a TS-centric package would force non-TS SDKs to either reimplement them or depend on Node tooling just for codegen.
+
+This package has **zero runtime dependencies**, no compile step, and no native binaries. Any language can pull it down (npm install, git submodule, or just `wget`-ing the tarball) and read the JSON directly.
+
+## Consumer examples
+
+**TypeScript (Node 20+):**
+
+```ts
+import manifest from '@sogni-ai/sogni-protocol/manifests/openai-tools.json' with { type: 'json' };
+import statuses from '@sogni-ai/sogni-protocol/enums/chat-run-status.json' with { type: 'json' };
+
+type ChatRunStatus = (typeof statuses.values)[number];
+```
+
+**Swift (codegen via `quicktype`):**
+
+```bash
+quicktype \
+  --src-lang schema \
+  --lang swift \
+  --src node_modules/@sogni-ai/sogni-protocol/schemas/tools/*.schema.json \
+  --out Sources/SogniKit/Models/Generated/ToolSchemas.swift
+```
+
+**Python (or any language) — direct JSON read:**
+
+```python
+import json, pathlib
+manifest = json.loads(pathlib.Path("node_modules/@sogni-ai/sogni-protocol/manifests/openai-tools.json").read_text())
+```
+
+## Versioning policy
+
+The package is versioned independently of any SDK. `version.json#protocolVersion` follows semver:
+
+- **Major** — removing or renaming any schema / enum / manifest field. Breaks consumers.
+- **Minor** — adding new optional fields, new tools, new manifests. Backwards-compatible.
+- **Patch** — description / prose changes (prompt text, schema descriptions). No shape change.
+
+SDKs may check `protocolVersion` at startup and refuse to run against an incompatible major.
+
+## Editing prose
+
+Tool prompt prose lives in `prompts/tools/*.json`. Each file is one [`PromptContract`](./schemas/prompt-contract.schema.json). Edit the JSON, bump `version.json#protocolVersion` patch, publish. SDKs pick up new prose on their next install — no code change required in any SDK.
+
+## 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.

package/catalogs/audio-models.json

@@ -0,0 +1,34 @@
+{
+  "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.",
+  "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 },
+      "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 }
+    }
+  },
+  "constraints": {
+    "duration": {
+      "min": 10,
+      "max": 600,
+      "default": 30,
+      "unit": "seconds"
+    },
+    "bpm": {
+      "min": 30,
+      "max": 300,
+      "default": 120
+    },
+    "timeSignatures": [2, 3, 4, 6]
+  }
+}

package/catalogs/quality-presets.json

@@ -0,0 +1,30 @@
+{
+  "description": "Quality tier presets for image generation and editing. Maps tier name -> model + sampling parameters. SDKs use this catalog to render quality-toggle UI and resolve a tier into concrete generation parameters.",
+  "default": "fast",
+  "tiers": {
+    "fast": {
+      "model": "qwen_image_edit_2511_fp8_lightning",
+      "steps": 5,
+      "guidance": 1.0,
+      "outputFormat": "jpg",
+      "label": "Fast",
+      "description": "Faster"
+    },
+    "hq": {
+      "model": "qwen_image_edit_2511_fp8",
+      "steps": 25,
+      "guidance": 4.0,
+      "outputFormat": "jpg",
+      "label": "High Quality",
+      "description": "More detail"
+    },
+    "pro": {
+      "model": "flux2_dev_fp8",
+      "steps": 40,
+      "guidance": 4.0,
+      "outputFormat": "jpg",
+      "label": "Pro",
+      "description": "Flux.2 Dev"
+    }
+  }
+}

package/enums/chat-run-status.json

@@ -0,0 +1,12 @@
+{
+  "description": "Chat-run lifecycle states. Mirrors @sogni-ai/sogni-intelligence-client/chatRun ChatRunStatus.",
+  "values": [
+    "queued",
+    "running",
+    "waiting_for_user",
+    "completed",
+    "partial_failure",
+    "failed",
+    "cancelled"
+  ]
+}

package/enums/chat-run-waiting-reasons.json

@@ -0,0 +1,10 @@
+{
+  "description": "Reason a chat run is in waiting_for_user. Mirrors ChatRunWaitingReason.",
+  "values": [
+    "ask_clarifying_question",
+    "select_media_required",
+    "cost_approval_required",
+    "safety_review_required",
+    "other"
+  ]
+}

package/enums/token-types.json

@@ -0,0 +1,7 @@
+{
+  "description": "Sogni billing token types. sogni = native (earned/staked); spark = cash-purchased (required for external-vendor models).",
+  "values": [
+    "sogni",
+    "spark"
+  ]
+}

package/enums/tool-names.json

@@ -0,0 +1,85 @@
+{
+  "description": "Canonical Sogni tool names. hosted = creative tools executed by the server; app = chat-app tools shipped via app-tools manifest (server-bound discovery); chatLocal = tools defined and executed inside sogni-chat (schemas in schemas/tools/, executed client-side); all = union.",
+  "hosted": [
+    "add_subtitles",
+    "animate_photo",
+    "apply_style",
+    "change_angle",
+    "compose_instrumental",
+    "compose_lyrics",
+    "compose_script",
+    "compose_workflow",
+    "compose_workflow_template",
+    "dance_montage",
+    "edit_image",
+    "enhance_prompt",
+    "extend_video",
+    "generate_image",
+    "generate_music",
+    "generate_video",
+    "orbit_video",
+    "overlay_video",
+    "refine_result",
+    "replace_video_segment",
+    "restore_photo",
+    "sound_to_video",
+    "stitch_video",
+    "video_to_video"
+  ],
+  "app": [
+    "analyze_image",
+    "analyze_video",
+    "ask_clarifying_question",
+    "create_asset_manifest",
+    "extract_metadata",
+    "finalize_response",
+    "inspect_asset",
+    "label_asset",
+    "map_assets_for_model",
+    "validate_asset_references"
+  ],
+  "all": [
+    "add_subtitles",
+    "analyze_image",
+    "analyze_video",
+    "animate_photo",
+    "apply_style",
+    "ask_clarifying_question",
+    "change_angle",
+    "compose_instrumental",
+    "compose_lyrics",
+    "compose_script",
+    "compose_workflow",
+    "compose_workflow_template",
+    "create_asset_manifest",
+    "dance_montage",
+    "edit_image",
+    "enhance_prompt",
+    "extend_video",
+    "extract_metadata",
+    "finalize_response",
+    "generate_image",
+    "generate_music",
+    "generate_video",
+    "inspect_asset",
+    "label_asset",
+    "manage_memory",
+    "map_assets_for_model",
+    "orbit_video",
+    "overlay_video",
+    "refine_result",
+    "replace_video_segment",
+    "resolve_personas",
+    "restore_photo",
+    "set_content_filter",
+    "sound_to_video",
+    "stitch_video",
+    "validate_asset_references",
+    "video_to_video"
+  ],
+  "chatLocal": [
+    "manage_memory",
+    "resolve_personas",
+    "set_content_filter"
+  ]
+}

package/manifests/app-tools.json

@@ -0,0 +1,297 @@
+{
+  "version": "2026-04-27.1",
+  "source": "sogni-creative-agent/src/backbone/openai-tools/app-tools.json",
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "analyze_image",
+        "description": "Analyze an uploaded or generated image using a vision model. Use for image questions, descriptions, OCR, object identification, document reading, or comparing two images. Does not generate or modify images.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "The user's question or request about the image."
+            },
+            "analysisType": {
+              "type": "string",
+              "enum": ["describe", "ocr", "objects", "document", "compare", "general"],
+              "description": "Type of analysis. Use general when answering the user's specific question."
+            },
+            "sourceImageIndex": {
+              "type": "number",
+              "description": "Image to analyze. Non-negative indexes refer to generated images; negative indexes refer to uploaded images (-1 first upload, -2 second upload). Omit to auto-select latest image."
+            },
+            "compareImageIndex": {
+              "type": "number",
+              "description": "Second image for compare mode, using the same indexing convention as sourceImageIndex."
+            },
+            "detailed": {
+              "type": "boolean",
+              "description": "Whether to provide a more detailed analysis."
+            }
+          },
+          "required": ["query"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "analyze_video",
+        "description": "Analyze an uploaded or generated video using sampled frames and a vision model. Use for video summaries, timelines, visual scene descriptions, action breakdowns, or visible text. Does not generate or modify videos.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "The user's question or request about the video."
+            },
+            "analysisType": {
+              "type": "string",
+              "enum": ["summary", "timeline", "scene", "action", "ocr", "general"],
+              "description": "Type of analysis. Use general when answering the user's specific question."
+            },
+            "sourceVideoIndex": {
+              "type": "number",
+              "description": "Video to analyze. Non-negative indexes refer to generated videos; negative indexes refer to uploaded videos (-1 first upload, -2 second upload). Omit to auto-select latest video."
+            },
+            "detailed": {
+              "type": "boolean",
+              "description": "Whether to sample more context and provide a more detailed analysis."
+            }
+          },
+          "required": ["query"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "extract_metadata",
+        "description": "Extract available technical metadata from an uploaded or generated media asset. Use when the user asks for duration, dimensions, MIME type, file size, model/prompt/settings metadata, or generation metadata embedded in or attached to a media file. For visual content questions, use analyze_image or analyze_video instead.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "mediaType": {
+              "type": "string",
+              "enum": ["image", "video", "audio"],
+              "description": "Media type to inspect. Omit when the available context makes it unambiguous."
+            },
+            "sourceImageIndex": {
+              "type": "number",
+              "description": "Image to inspect, using generated indexes or negative uploaded indexes."
+            },
+            "sourceVideoIndex": {
+              "type": "number",
+              "description": "Video to inspect, using generated indexes or negative uploaded indexes."
+            },
+            "audioSourceIndex": {
+              "type": "number",
+              "description": "Audio asset to inspect, using generated indexes or negative uploaded indexes."
+            },
+            "fileIndex": {
+              "type": "number",
+              "description": "Legacy 0-based uploaded-file index. Prefer mediaType plus sourceImageIndex/sourceVideoIndex/audioSourceIndex when possible."
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "ask_clarifying_question",
+        "description": "Pause the workflow and ask the user a clarifying question. The host treats this as the end of the turn; do not call other tools after it.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "question": {
+              "type": "string",
+              "description": "The exact short question to surface to the user."
+            },
+            "reason": {
+              "type": "string",
+              "description": "Short telemetry tag explaining why clarification is needed."
+            }
+          },
+          "required": ["question"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "finalize_response",
+        "description": "Mark the turn complete and surface a final assistant message. The host stops the tool loop when this is called. Do not call other tools after finalize_response.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "summary": {
+              "type": "string",
+              "description": "Short user-visible summary. Leave empty when prior tool output already says enough."
+            },
+            "outcome": {
+              "type": "string",
+              "enum": ["success", "partial", "asked_user", "failed", "no_action"],
+              "description": "How the turn ended."
+            }
+          },
+          "required": ["outcome"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "create_asset_manifest",
+        "description": "Reset and seed the session asset manifest with stable asset_id values so later tool calls can refer to assets reliably.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "assets": {
+              "type": "array",
+              "description": "Ordered list of assets to register.",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "user_label": {
+                    "type": "string",
+                    "description": "Human-readable asset name."
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": ["image", "video", "audio"],
+                    "description": "Asset media type."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Optional short description."
+                  },
+                  "url": {
+                    "type": "string",
+                    "description": "Optional URL for the asset."
+                  },
+                  "must_preserve": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Features to preserve when regenerating from this asset."
+                  },
+                  "avoid": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Features to avoid."
+                  },
+                  "asset_id": {
+                    "type": "string",
+                    "description": "Optional stable id override."
+                  }
+                },
+                "required": ["user_label", "type"]
+              }
+            }
+          },
+          "required": ["assets"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "inspect_asset",
+        "description": "Return one asset record by asset_id or user_label, or the full asset manifest when no selector is provided.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "asset_id": {
+              "type": "string",
+              "description": "Stable asset id."
+            },
+            "user_label": {
+              "type": "string",
+              "description": "Human-readable asset label."
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "label_asset",
+        "description": "Update labels or preservation notes on an existing asset manifest entry.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "asset_id": {
+              "type": "string",
+              "description": "Stable asset id to update."
+            },
+            "user_label": {
+              "type": "string",
+              "description": "Replacement human-readable label."
+            },
+            "description": {
+              "type": "string",
+              "description": "Replacement description. Empty string clears it."
+            },
+            "must_preserve": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Replacement preserve list."
+            },
+            "avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Replacement avoid list."
+            },
+            "url": {
+              "type": "string",
+              "description": "Replacement URL. Empty string clears it."
+            }
+          },
+          "required": ["asset_id"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "map_assets_for_model",
+        "description": "Return model-specific reference tokens for each asset in the manifest, such as @Image1 for Seedance or Image 1 for GPT Image 2.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "model_id": {
+              "type": "string",
+              "description": "Target model identifier."
+            }
+          },
+          "required": ["model_id"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "validate_asset_references",
+        "description": "Check whether model-specific asset reference tokens in a prompt resolve to registered manifest assets.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "model_id": {
+              "type": "string",
+              "description": "Target model identifier."
+            },
+            "prompt": {
+              "type": "string",
+              "description": "Prompt text to validate."
+            }
+          },
+          "required": ["model_id", "prompt"]
+        }
+      }
+    }
+  ]
+}