feat: canonical model names, lucy-2.1, and deprecation warnings

[AdirAmsalem]

Summary

• Adds canonical model names across the SDK (lucy-2, lucy-clip, lucy-restyle-2, lucy-image-2, live-avatar, etc.) to match the updated API naming convention
• Adds new models: lucy-2.1 (realtime + batch) and lucy-2.1-vton (realtime) with examples and e2e tests
• Deprecated model names (lucy_2_rt, mirage_v2, lucy-pro-v2v, etc.) still work but now emit a one-time console.warn guiding users to migrate
• Models like lucy-2 and lucy-restyle-2 that support both realtime and batch are now available in both models.realtime() and models.video()
• Tightened VideoModelDefinition and ImageModelDefinition types to require queueUrlPath, preventing accidental use of a realtime definition with the queue/process API at compile time

Usage

// New canonical names
const rt = models.realtime("lucy-2.1");
const video = models.video("lucy-2.1");
const clip = models.video("lucy-clip");
const img = models.image("lucy-image-2");

// Old names still work but log a deprecation warning
const old = models.realtime("lucy_2_rt");
// ⚠️ [Decart SDK] Model "lucy_2_rt" is deprecated. Use "lucy-2" instead.

// Dual-surface models work in both contexts
const realtimeLucy2 = models.realtime("lucy-2");
const batchLucy2 = models.video("lucy-2");

// Type safety: this would NOT compile
// client.queue.submit({ model: models.realtime("lucy-2"), ... })
// ✗ realtime definition lacks queueUrlPath required by VideoModelDefinition

Test plan

• All 163 unit tests pass (including new canonical name tests, deprecation warning tests, dual-surface model tests)
• All 36 proxy tests pass
• Build succeeds across all packages and examples

---

Note

Medium Risk
Medium risk because it expands/reshapes the public model registry and tightens TypeScript model definition types, which could cause compile-time breakage for consumers relying on previous model name unions or model typing.

Overview
Adds canonical model names across models.image(), models.video(), and models.realtime() (e.g., lucy-image-2, lucy-clip, lucy-restyle-2, lucy-2, live-avatar) and introduces new models lucy-2.1 (realtime + queue) and lucy-2.1-vton (realtime).

Keeps old names working via expanded model unions but now emits a one-time console.warn deprecation notice (tracked in shared/model.ts), and updates realtime live-avatar handling to recognize both live_avatar and live-avatar. Types are tightened so image/video model definitions used with Process/Queue APIs require queueUrlPath, helping prevent accidentally passing realtime definitions.

Updates examples/docs to use the canonical names and expands unit + e2e coverage to validate canonical models, deprecated-name compatibility, and deprecation-warning behavior.

^{Reviewed by Cursor Bugbot for commit 3b603c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

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

commit: 3b603c7

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1fb1dfb. Configure here.}

[cursor]

Test-only helper exported in public SDK API

Low Severity

_resetDeprecationWarnings is marked @internal and intended as a test-only helper, but it's exported from the SDK's public entry point. This exposes internal module-level state (_warnedAliases) to every consumer of the package, letting them silently reset the deprecation warning tracking. It unnecessarily enlarges the public API surface and could lead to unintended coupling.

Additional Locations (1)

• packages/sdk/src/shared/model.ts#L21-L25

 

^{Reviewed by Cursor Bugbot for commit 1fb1dfb. Configure here.}