feat: support custom model definitions in realtime.connect()

[AdirAmsalem]

Summary

Allow users to provide custom model definitions to realtime.connect() — useful for preview, experimental, or private models that aren't yet in the SDK registry.

Built-in models (models.realtime("mirage_v2"), etc.) retain full autocomplete.

Usage

import { createDecartClient } from "@decartai/sdk";
import type { CustomModelDefinition } from "@decartai/sdk";

const lucy2RtPreview: CustomModelDefinition = {
  name: "lucy_2_rt_preview",
  urlPath: "/v1/stream",
  fps: 20,
  width: 1280,
  height: 720,
};

const client = createDecartClient({ apiKey: "your-api-key" });

const realtimeClient = await client.realtime.connect(stream, {
  model: lucy2RtPreview,
  onRemoteStream: (transformedStream) => {
    videoElement.srcObject = transformedStream;
  },
  initialState: {
    prompt: { text: "cinematic lighting", enhance: true },
  },
});

What changed

• New CustomModelDefinition type exported from the SDK
• realtime.connect() accepts both built-in and custom model definitions
• Model name validation widened from a closed enum to any string
• Added unit tests and an example (examples/sdk-core/realtime/custom-model.ts)

---

Note

Medium Risk
Broadening model-name validation from an enum to string changes a core contract and could allow invalid model identifiers to reach the realtime backend, affecting connection behavior at runtime.

Overview
realtime.connect() now accepts either a built-in ModelDefinition or a new exported CustomModelDefinition, enabling realtime connections to preview/experimental/private models with arbitrary string names.

To support this, modelDefinitionSchema validation is widened to allow any string name, and the WebRTC layer’s modelName typing is loosened from RealTimeModels to string. This PR also adds a browser-only example (examples/sdk-core/realtime/custom-model.ts), updates the examples README, and introduces unit tests covering custom-model schema validation.

^{Written by Cursor Bugbot for commit 46522a2. This will update automatically on new commits. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/DecartAI/sdk/@decartai/sdk@90

commit: 46522a2

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.