> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/ai-and-music/sonic-ai-orchestration-contracts.md). # Sonic AI Orchestration Contracts Canonical Sonic AI v1.0 Pro orchestration contracts for normalized requests, model responsibility, routing, context, providers, tools, artifacts, generation operations and AI Credit usage. > **Architectural contract / early phase** — Sonic AI v1.0 Pro is a product-facing orchestration profile. Documented endpoint families remain **Planned** until backed by released source and the versioned API specification. Sonic AI exposes stable SONIC concepts while provider-specific model IDs, credentials, transport details, fallback chains and provider quirks remain behind server-side registries and adapters. ## Provider responsibility classes Every provider/model registry entry declares a responsibility class so product surfaces cannot blur reasoning and media execution. ```ts type ProviderResponsibility = | "reasoning" | "music" | "image" | "video" | "utility"; ``` Examples: ``` OpenAI reasoning model → reasoning Suno music model → music image provider model → image ``` A reasoning route that refines a music brief does not become the music-generation provider. ## Control plane ``` normalized request → signed-session authority → intent + capability requirements → permission-filtered context → policy → provider/model eligibility → route selection → tool/model execution → result validation → artifact / domain result → normalized usage → AI Credit settlement → audit + telemetry ``` ## Normalized request A normalized request should carry: ``` operationId tenant/workspace context actor/account context taskIntent requiredCapabilities contextPolicy routingPolicy Sonic profile / mode projectId? / resourceId? input idempotency context ``` For brief-refinement workflows preserve both creator input and derived text instead of overwriting the original request. ## Provider registry A provider/model record should retain server-side metadata such as: ``` provider providerModelId responsibility capabilities privacy/local-cloud classification transport latency class cost class health lifecycle status enabled state policy tags fallback group? ``` The safe client projection may expose only approved presentation fields such as display name, logo, responsibility, capability labels and availability. ## Routing Eligibility is a hard-filter stage. Capability, responsibility, privacy, environment, health, authorization/workspace policy and configured provider policy must pass before quality/latency/cost ranking occurs. A `reasoning` model is not eligible for a `music.generate` execution capability merely because it participated earlier in prompt preparation. Creator modes may include `Auto`, `Pro`, `Fast`, `Efficient` and `Private`. Manual overrides fail transparently unless their explicit policy permits fallback. Streaming does not silently switch semantic models after output begins. ## Context Context blocks retain: ``` sourceType sourceId priority provenance scope retrievedAt/version ``` Retrieval is permission-filtered and task-scoped. Large context windows do not justify indiscriminate private-data injection. Use budgeting, ranking and structured compression. ## Tools Every tool declares: ``` id domain requiredPermissions mutating requiresConfirmation ``` Authorization is checked during eligibility and again at execution. Sonic AI cannot elevate roles, sign wallets, move funds, allocate rewards or bypass transaction/settlement policy. ## Artifacts Reviewable AI output may use: ``` DRAFT → APPROVED → APPLIED └────→ REJECTED ``` Artifacts retain originating operation, relevant prompt/context versions and resulting domain action. Examples include `LyricsDraft`, `ReleasePlan`, `MarketplaceListingDraft`, `CampaignDraft`, `ProjectSummary` and `BlinkDraft`. ## Generation operation snapshot Before provider dispatch, persist the execution snapshot required to explain and reconcile the operation later: ``` operationId originalBrief refinedBrief? refinementApplied creativeRoute? musicProvider musicModelSnapshot requestedDurationSeconds routingPolicyVersion creditPolicyVersion reservationId createdAt ``` Provider/model configuration changes after dispatch must not retroactively change the historical operation snapshot. ## Dispatch preconditions Before music execution: * authenticated tenant/account authority is valid; * mutation authorization and entitlement checks pass; * input schema is valid; * remote assets pass public-URL validation; * requested duration/settings are within policy; * music provider/model is eligible and available; * required AI Credit cost is resolved in atomic units; * the idempotent `GenerationOperation` exists; * reservation succeeds. A failed reservation blocks dispatch. ## Unknown dispatch state An upstream timeout after request transmission is not proof the provider did not create a job. ``` dispatch attempt → timeout / ambiguous response → mark dispatch UNKNOWN / REQUIRES_RECONCILIATION → recover by provider correlation/idempotency strategy → only redispatch when duplicate execution is ruled out ``` This is required to prevent duplicate provider work and double settlement. ## Callback progression Provider callbacks/polling may be partial, duplicated or out of order. Merge by stable track identity and monotonic stage/progress rules. Never overwrite a completed/non-null authoritative result with an earlier, null or partial observation. Terminal credit behavior runs exactly once after normalized result validation. ## Usage accounting Normalized usage may retain: ``` operationId Sonic profile mode task creative provider/model? music provider/model? routing reason input/output usage where applicable AI Credits reserved AI Credits settled/released latency terminal status ``` Provider cost and SONIC AI Credit pricing are independent policies. Shadow/evaluation traffic must not create hidden user charges. ## Suggested AI endpoint family These remain **Planned architectural contracts** until released source/OpenAPI confirms them: ```http POST /api/v1/ai/chat POST /api/v1/ai/complete GET /api/v1/ai/models GET /api/v1/ai/providers POST /api/v1/ai/projects/:id/analyze POST /api/v1/ai/prompts/enhance GET /api/v1/ai/usage ``` Do not mark them `Live` merely because they are documented. ## Canonical invariant ``` stable SONIC contract + explicit provider responsibility + server-side registry + permission-filtered context + policy-qualified routing + execution-time tool authorization + immutable execution snapshot + idempotent GenerationOperation + reserve-before-dispatch credits + unknown-state reconciliation + monotonic callback merge + exactly-once terminal financial transition = valid Sonic AI orchestration ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/ai-and-music/sonic-ai-orchestration-contracts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.