From 5880148b22883a415a11a53d27362aa9d5ecc40c Mon Sep 17 00:00:00 2001 From: Arun Mani J Date: Tue, 16 Jun 2026 16:51:04 +0530 Subject: [PATCH] chore: adopt canonical model type names in SDK docs, examples, and tests Signed-off-by: Arun Mani J --- packages/sdk/README.md | 1 - packages/sdk/client/api/load-model.ts | 19 +++++++++++-------- packages/sdk/examples/diffusion-img2vid.ts | 2 +- packages/sdk/schemas/model-types.ts | 9 ++++----- .../sdk/test/bare/tts-resolve-config.test.ts | 2 +- packages/sdk/test/mocks/pr-body-bc-valid.md | 2 +- packages/sdk/test/unit/bci-schemas.test.ts | 2 +- .../test/unit/classification-schemas.test.ts | 4 ++-- .../unit/inference-handler-migrations.test.ts | 6 +++--- .../unit/profiler-operation-transport.test.ts | 10 +++++----- packages/sdk/test/unit/sdcpp-plugin.test.ts | 4 ++-- packages/sdk/test/unit/vla-schemas.test.ts | 2 +- 12 files changed, 32 insertions(+), 31 deletions(-) diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 804d1da3a1..0ce94d0077 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -46,7 +46,6 @@ try { // Load a model into memory const modelId = await loadModel({ modelSrc: LLAMA_3_2_1B_INST_Q4_0, - modelType: "llm", onProgress: (progress) => { console.log(progress); }, diff --git a/packages/sdk/client/api/load-model.ts b/packages/sdk/client/api/load-model.ts index dbc826be05..9f23290ea8 100644 --- a/packages/sdk/client/api/load-model.ts +++ b/packages/sdk/client/api/load-model.ts @@ -78,7 +78,10 @@ export function loadModel( * @overloadLabel "Load new model" * @param options - An object that defines all configuration parameters required for loading the model, including: * - modelSrc: The location from which the model weights are fetched (local path, remote URL, or Hyperdrive URL) - * - modelType: The type of model ("llm", "whisper", "embeddings", "nmt", or "tts") + * - modelType: The canonical type of model ("llamacpp-completion", + * "whispercpp-transcription", "llamacpp-embedding", "nmtcpp-translation", + * "tts-ggml", ...). May be omitted when `modelSrc` is a registry descriptor + * that already carries the engine. * - modelConfig: Model-specific configuration options (companion sources, model parameters, etc.) * - onProgress: Callback for download progress updates * - logger: Logger instance for model operation logs @@ -95,27 +98,27 @@ export function loadModel( * // Local file path - absolute path * const localModelId = await loadModel({ * modelSrc: "/home/user/models/llama-7b.gguf", - * modelType: "llm", + * modelType: "llamacpp-completion", * modelConfig: { ctx_size: 2048 } * }); * * // Local file path - relative path * const relativeModelId = await loadModel({ * modelSrc: "./models/whisper-base.gguf", - * modelType: "whisper" + * modelType: "whispercpp-transcription" * }); * * // Hyperdrive URL with key and path * const hyperdriveId = await loadModel({ * modelSrc: "pear:///llama-7b.gguf", - * modelType: "llm", + * modelType: "llamacpp-completion", * modelConfig: { ctx_size: 2048 } * }); * * // Remote HTTP/HTTPS URL with progress tracking * const remoteId = await loadModel({ * modelSrc: "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/main/llama-2-7b-chat.Q4_K_M.gguf", - * modelType: "llm", + * modelType: "llamacpp-completion", * onProgress: (progress) => { * console.log(`Downloaded: ${progress.percentage}%`); * } @@ -124,7 +127,7 @@ export function loadModel( * // Multimodal model with projection * const multimodalId = await loadModel({ * modelSrc: "https://huggingface.co/.../main-model.gguf", - * modelType: "llm", + * modelType: "llamacpp-completion", * modelConfig: { * ctx_size: 512, * projectionModelSrc: "https://huggingface.co/.../projection-model.gguf" @@ -137,7 +140,7 @@ export function loadModel( * // Whisper with VAD model * const whisperId = await loadModel({ * modelSrc: "https://huggingface.co/.../whisper-model.gguf", - * modelType: "whisper", + * modelType: "whispercpp-transcription", * modelConfig: { * mode: "caption", * output_format: "plaintext", @@ -153,7 +156,7 @@ export function loadModel( * * const modelId = await loadModel({ * modelSrc: "/path/to/model.gguf", - * modelType: "llm", + * modelType: "llamacpp-completion", * logger // Pass logger in options * }); * ``` diff --git a/packages/sdk/examples/diffusion-img2vid.ts b/packages/sdk/examples/diffusion-img2vid.ts index a0c7e24911..2a7a2e66e7 100644 --- a/packages/sdk/examples/diffusion-img2vid.ts +++ b/packages/sdk/examples/diffusion-img2vid.ts @@ -38,7 +38,7 @@ try { console.log("Loading Wan 2.1 I2V model (diffusion + UMT5-XXL + VAE + CLIP vision)..."); const modelId = await loadModel({ modelSrc: diffusionModelSrc, - modelType: "diffusion", + modelType: "sdcpp-generation", modelConfig: { mode: "video", device: "gpu", diff --git a/packages/sdk/schemas/model-types.ts b/packages/sdk/schemas/model-types.ts index dc498a91ee..5562cbdf95 100644 --- a/packages/sdk/schemas/model-types.ts +++ b/packages/sdk/schemas/model-types.ts @@ -72,12 +72,11 @@ const canonicalValuesSet = new Set(Object.values(ModelType)); * * @example * ```typescript - * // Using alias (backward compatible) - * loadModel({ modelSrc: "...", modelType: MODEL_TYPES.nmt }); - * // MODEL_TYPES.nmt resolves to "nmtcpp-translation" - * - * // Using canonical name directly + * // Preferred: canonical name * loadModel({ modelSrc: "...", modelType: MODEL_TYPES.nmtcppTranslation }); + * + * // Deprecated: alias (still resolves to "nmtcpp-translation") + * loadModel({ modelSrc: "...", modelType: MODEL_TYPES.nmt }); * ``` */ export const PUBLIC_MODEL_TYPES = { diff --git a/packages/sdk/test/bare/tts-resolve-config.test.ts b/packages/sdk/test/bare/tts-resolve-config.test.ts index 5a168cdcde..b1cab62b43 100644 --- a/packages/sdk/test/bare/tts-resolve-config.test.ts +++ b/packages/sdk/test/bare/tts-resolve-config.test.ts @@ -22,7 +22,7 @@ test( await ttsPlugin.resolveConfig!(legacyConfig, { resolveModelPath: async () => "", modelSrc: "s3:///legacy/model", - modelType: "tts", + modelType: "tts-ggml", }); t.ok(false, "expected LegacyTtsModelDeprecatedError"); } catch (err) { diff --git a/packages/sdk/test/mocks/pr-body-bc-valid.md b/packages/sdk/test/mocks/pr-body-bc-valid.md index ae7ee30f2f..c25d10897f 100644 --- a/packages/sdk/test/mocks/pr-body-bc-valid.md +++ b/packages/sdk/test/mocks/pr-body-bc-valid.md @@ -17,6 +17,6 @@ const model = await loadModel("model-path"); **AFTER:** ```typescript -const modelId = await loadModel("model-path", { modelType: "llm" }); +const modelId = await loadModel("model-path", { modelType: "llamacpp-completion" }); ``` diff --git a/packages/sdk/test/unit/bci-schemas.test.ts b/packages/sdk/test/unit/bci-schemas.test.ts index 4397240b5b..27cc8ed852 100644 --- a/packages/sdk/test/unit/bci-schemas.test.ts +++ b/packages/sdk/test/unit/bci-schemas.test.ts @@ -311,7 +311,7 @@ test("loadModelOptionsToRequestSchema: resolves the 'bci' alias to the canonical test("loadModelOptionsToRequestSchema: rejects unknown modelConfig keys for BCI (strict)", (t) => { const result = loadModelOptionsToRequestSchema.safeParse({ - modelType: "bci", + modelType: "bci-whispercpp-transcription", modelSrc: "ggml-bci-windowed.bin", modelConfig: { notABciField: true }, }); diff --git a/packages/sdk/test/unit/classification-schemas.test.ts b/packages/sdk/test/unit/classification-schemas.test.ts index 14e4607428..983d93c495 100644 --- a/packages/sdk/test/unit/classification-schemas.test.ts +++ b/packages/sdk/test/unit/classification-schemas.test.ts @@ -202,7 +202,7 @@ test("loadModelOptionsBaseSchema: accepts classification alias", (t) => { test("loadModelOptionsBaseSchema: accepts classification with custom modelSrc", (t) => { const result = loadModelOptionsBaseSchema.safeParse({ modelSrc: "/abs/path/to/my-classifier.gguf", - modelType: "classification", + modelType: "ggml-classification", modelConfig: { topK: 3 }, }); t.is(result.success, true); @@ -210,7 +210,7 @@ test("loadModelOptionsBaseSchema: accepts classification with custom modelSrc", test("loadModelOptionsBaseSchema: rejects classification config with unknown key (strict)", (t) => { const result = loadModelOptionsBaseSchema.safeParse({ - modelType: "classification", + modelType: "ggml-classification", modelConfig: { topK: 3, unknownKey: true }, }); t.is(result.success, false); diff --git a/packages/sdk/test/unit/inference-handler-migrations.test.ts b/packages/sdk/test/unit/inference-handler-migrations.test.ts index c78cd8889c..1608428b1c 100644 --- a/packages/sdk/test/unit/inference-handler-migrations.test.ts +++ b/packages/sdk/test/unit/inference-handler-migrations.test.ts @@ -54,7 +54,7 @@ test("translateRequestSchema (NMT): accepts an optional requestId", (t) => { modelId: "m1", text: "hello", stream: true, - modelType: "nmt", + modelType: "nmtcpp-translation", requestId: "req-nmt", }); t.is(result.success, true); @@ -66,7 +66,7 @@ test("translateRequestSchema (LLM): accepts an optional requestId", (t) => { modelId: "m1", text: "hello", stream: true, - modelType: "llm", + modelType: "llamacpp-completion", from: "en", to: "fr", requestId: "req-llm", @@ -80,7 +80,7 @@ test("translateRequestSchema: rejects empty-string requestId", (t) => { modelId: "m1", text: "hello", stream: true, - modelType: "nmt", + modelType: "nmtcpp-translation", requestId: "", }); t.is(result.success, false); diff --git a/packages/sdk/test/unit/profiler-operation-transport.test.ts b/packages/sdk/test/unit/profiler-operation-transport.test.ts index e95696be96..a7971264e3 100644 --- a/packages/sdk/test/unit/profiler-operation-transport.test.ts +++ b/packages/sdk/test/unit/profiler-operation-transport.test.ts @@ -21,7 +21,7 @@ test("operation metrics: loadModel extracts gauges and tags", (t) => { "profile-1", 100, 500, - { modelType: "llm" }, + { modelType: "llamacpp-completion" }, { __profilingMeta: { sourceType: "registry", @@ -37,7 +37,7 @@ test("operation metrics: loadModel extracts gauges and tags", (t) => { ); t.ok(event, "event is built"); - t.alike(event!.tags, { modelType: "llm", sourceType: "registry" }); + t.alike(event!.tags, { modelType: "llamacpp-completion", sourceType: "registry" }); t.is(event!.gauges?.downloadTime, 220); t.is(event!.gauges?.totalBytesDownloaded, 4096); t.is(event!.gauges?.downloadSpeedBps, 18618); @@ -51,7 +51,7 @@ test("operation metrics: omits unavailable gauges (no fabrication)", (t) => { "profile-2", 100, 90, - { modelType: "llm" }, + { modelType: "llamacpp-completion" }, { __profilingMeta: { sourceType: "filesystem", @@ -83,7 +83,7 @@ test("transport: operation event survives injection/extraction round-trip", (t) ms: 500, profileId: "round-trip-test", gauges: { totalLoadTime: 500, downloadTime: 200 }, - tags: { modelType: "llm", sourceType: "registry", cacheHit: "true" }, + tags: { modelType: "llamacpp-completion", sourceType: "registry", cacheHit: "true" }, }; const baseJson = '{"type":"loadModel","success":true}'; @@ -99,7 +99,7 @@ test("transport: operation event survives injection/extraction round-trip", (t) t.is(extracted!.operation!.profileId, "round-trip-test"); t.alike(extracted!.operation!.gauges, { totalLoadTime: 500, downloadTime: 200 }); t.alike(extracted!.operation!.tags, { - modelType: "llm", + modelType: "llamacpp-completion", sourceType: "registry", cacheHit: "true", }); diff --git a/packages/sdk/test/unit/sdcpp-plugin.test.ts b/packages/sdk/test/unit/sdcpp-plugin.test.ts index 0602c0c4e2..03f5153ace 100644 --- a/packages/sdk/test/unit/sdcpp-plugin.test.ts +++ b/packages/sdk/test/unit/sdcpp-plugin.test.ts @@ -839,7 +839,7 @@ test("loadModelOptionsBaseSchema: accepts diffusion with alias", (t) => { test("loadModelOptionsBaseSchema: rejects diffusion with unknown config key (strict)", (t) => { const result = loadModelOptionsBaseSchema.safeParse({ modelSrc: "model.safetensors", - modelType: "diffusion", + modelType: "sdcpp-generation", modelConfig: { device: "gpu", notAField: true }, }); t.is(result.success, false); @@ -848,7 +848,7 @@ test("loadModelOptionsBaseSchema: rejects diffusion with unknown config key (str test("loadModelOptionsBaseSchema: accepts diffusion with mode: 'upscale' (standalone ESRGAN)", (t) => { const result = loadModelOptionsBaseSchema.safeParse({ modelSrc: "RealESRGAN_x4plus_anime_6B.pth", - modelType: "diffusion", + modelType: "sdcpp-generation", modelConfig: { mode: "upscale", upscaler: { tile_size: 128 }, diff --git a/packages/sdk/test/unit/vla-schemas.test.ts b/packages/sdk/test/unit/vla-schemas.test.ts index 21fcfb438c..246a20e188 100644 --- a/packages/sdk/test/unit/vla-schemas.test.ts +++ b/packages/sdk/test/unit/vla-schemas.test.ts @@ -338,7 +338,7 @@ test("loadModelOptionsBaseSchema: accepts vla alias", (t) => { test("loadModelOptionsBaseSchema: rejects vla config with unknown key (strict)", (t) => { const result = loadModelOptionsBaseSchema.safeParse({ modelSrc: "smolvla.gguf", - modelType: "vla", + modelType: "ggml-vla", modelConfig: { backend: "cpu", unknownKey: true }, }); t.is(result.success, false);