QVAC-17907 chore: adopt canonical model type names in SDK docs, examples, and tests

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);
         },

packages/sdk/client/api/load-model.ts

@@ -78,7 +78,10 @@ export function loadModel<S extends ModelDescriptor>(
  * @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<S extends ModelDescriptor>(
  * // 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://<hyperdrive-key>/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<S extends ModelDescriptor>(
  * // 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<S extends ModelDescriptor>(
  * // 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<S extends ModelDescriptor>(
  *
  * const modelId = await loadModel({
  *   modelSrc: "/path/to/model.gguf",
- *   modelType: "llm",
+ *   modelType: "llamacpp-completion",
  *   logger // Pass logger in options
  * });
  * ```

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",

packages/sdk/schemas/model-types.ts

@@ -72,12 +72,11 @@ const canonicalValuesSet = new Set<string>(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 = {

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) {

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" });
 ```
 

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 },
   });

packages/sdk/test/unit/classification-schemas.test.ts

@@ -202,15 +202,15 @@ 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);
 });
 
 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);

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);

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",
   });

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 },

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);