@mlx-node/lm 0.0.9 → 0.0.12

package/dist/models/model-loader.d.ts

@@ -1,153 +1,105 @@
 /**
- * Model loading utilities for Qwen3 models
- *
- * Handles loading pretrained weights from MLX format or converting from HuggingFace.
+ * Native half of the family registry: one loader binding per
+ * `MODEL_FAMILY_DATA` row, plus `detectModelType` (filesystem + GGUF).
  */
-import { Gemma4Model as NativeGemma4Model, HarrierModel, Lfm2Model as NativeLfm2Model, QianfanOCRModel, Qwen3Model as NativeQwen3Model, Qwen35Model as NativeQwen35Model, Qwen35MoeModel as NativeQwen35MoeModel } from '@mlx-node/core';
+import { Gemma4Model as NativeGemma4Model, HarrierModel, Lfm2Model as NativeLfm2Model, MuseGlimmerModel as NativeMuseGlimmerModel, NemotronHModel as NativeNemotronHModel, QianfanOCRModel, Qwen3Model as NativeQwen3Model, Qwen35Model as NativeQwen35Model, Qwen35MoeModel as NativeQwen35MoeModel } from '@mlx-node/core';
 import { ChatSession, type SessionCapableModel } from '../chat-session.js';
+import { type ModelType, type TrainableFamilyId } from '../family-data.js';
 /** Optional settings for {@link loadModel} / {@link loadSession}. */
 export interface LoadModelOptions {
     /**
-     * Gemma4 only: directory of an external draft checkpoint (config.json +
-     * model.safetensors) loaded alongside the target model for speculative
-     * decoding (forwarded as `Gemma4LoadOptions.draftModelPath`). Accepts
-     * either a DSpark draft or a Google gemma-4 assistant draft
+     * Directory of an external draft checkpoint (config.json +
+     * model.safetensors) loaded alongside the target for speculative decoding.
+     * Gemma4 accepts either a DSpark draft or a Google gemma-4 assistant draft
      * (`google/gemma-4-*-it-assistant`); the variant is auto-detected from
      * the draft's config.json (`model_type` `gemma4_assistant` /
      * `gemma4_unified_assistant` → assistant, `architectures` containing
      * `Gemma4DSparkModel` → DSpark). When omitted, Gemma4 automatically loads
      * an embedded draft from `<modelPath>/draft/` when present. Draft decoding
      * runs on the flat KV-cache path, so the target checkpoint must not
-     * explicitly enable `use_block_paged_cache`. Setting this for any other
-     * model family is a hard error — no other loader accepts a draft model.
+     * explicitly enable `use_block_paged_cache`.
+     *
+     * Dense `qwen3_5` accepts a z-lab `DFlash2DraftModel` companion such as
+     * `z-lab/Qwen3.8-27B-DFlash2`. It shares the Qwen3.8 target embedding and
+     * LM head, validates all companion tensors at load time, and takes
+     * precedence over an inline target MTP head. Other model families reject
+     * this option.
      */
     draftModelPath?: string;
 }
-interface NormalizedModelConfig {
-    readonly usesDefaultModelType: boolean;
-    readonly rawModelType: string | undefined;
-    readonly rawModelTypeLabel: string;
-    readonly architectures: ReadonlySet<string>;
-}
-interface ModelConfigMatchContext extends NormalizedModelConfig {
-    readonly modelType: string | undefined;
-}
 /**
- * Ordered source of truth for every supported model family. Each entry owns
- * its canonical `ModelType`, raw config aliases / architecture probes, loader,
- * and `ChatSession` eligibility:
- *
- *   - `'trainable'` — GRPO/SFT-capable LM (Qwen3 family); chat-capable.
- *   - `'loadable'`  — chat-capable LM with no trainer engine (Gemma4, LFM2).
- *   - `'embedding'` — no chat surface (Harrier); rejected by `loadSession`.
- *   - `'vlm'`       — VLM whose AsyncGenerator wrapper lives in
- *                     `@mlx-node/vlm` (importing it here would create a
- *                     circular package dependency), so `loadSession`
- *                     rejects it and routes callers to `@mlx-node/vlm`.
- *
- * A base family is selected from an explicit alias or the single declarative
- * nullish-model_type default, then architecture probes refine it in declaration
- * order. Gemma's unified architecture is authoritative (matching the native
- * loader); Harrier refines a Qwen3 base. Adding a family means adding one
- * descriptor here, without a second normalization or dispatch branch.
+ * Native half of the family registry: one loader + native class per
+ * `MODEL_FAMILY_DATA` row (the native-free half in `../family-data.ts`).
+ * `satisfies Record<ModelType, LoaderBinding>` makes the zip exhaustive both
+ * ways — a data row without a binding, or a binding without a row, fails to
+ * compile.
  */
-declare const MODEL_FAMILY_REGISTRY: readonly [{
-    readonly modelType: 'gemma4';
-    readonly kind: 'loadable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["gemma4", "gemma4_text", "gemma4_unified"];
-        readonly architectureProbe: ({ architectures }: ModelConfigMatchContext) => boolean;
+declare const LOADER_BINDINGS: {
+    readonly gemma4: {
+        readonly load: (modelPath: string, options?: LoadModelOptions) => Promise<import("../stream.js").StreamingInstance<typeof NativeGemma4Model, {
+            readonly recordModelPath: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeGemma4Model;
+    };
+    readonly muse_glimmer: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeMuseGlimmerModel, {
+            readonly recordModelPath: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeMuseGlimmerModel;
+    };
+    readonly harrier: {
+        readonly load: (modelPath: string) => Promise<HarrierModel>;
+        readonly nativeModelClass: typeof HarrierModel;
     };
-    readonly load: (modelPath: string, options?: LoadModelOptions) => Promise<import("../stream.js").StreamingInstance<typeof NativeGemma4Model, {
-        readonly recordModelPath: true;
-    }>>;
-    readonly nativeModelClass: typeof NativeGemma4Model;
-    readonly acceptsDraftModel: true;
-}, {
-    readonly modelType: 'harrier';
-    readonly kind: 'embedding';
-    readonly match: {
-        readonly rawModelTypes: readonly ["harrier"];
-        readonly architectureProbe: ({ modelType, architectures }: ModelConfigMatchContext) => boolean;
+    readonly qwen3: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen3Model, {
+            readonly recordModelPath: true;
+            readonly applyTemplate: false;
+        }>>;
+        readonly nativeModelClass: typeof NativeQwen3Model;
     };
-    readonly load: (modelPath: string) => Promise<HarrierModel>;
-    readonly nativeModelClass: typeof HarrierModel;
-}, {
-    readonly modelType: 'qwen3';
-    readonly kind: 'trainable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["qwen3"];
+    readonly qwen3_5: {
+        readonly load: (modelPath: string, options?: LoadModelOptions) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen35Model, {
+            readonly recordModelPath: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeQwen35Model;
     };
-    readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen3Model, {
-        readonly recordModelPath: true;
-        readonly applyTemplate: false;
-    }>>;
-    readonly nativeModelClass: typeof NativeQwen3Model;
-    readonly defaultForNullishModelType: true;
-}, {
-    readonly modelType: 'qwen3_5';
-    readonly kind: 'trainable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["qwen3_5"];
+    readonly qwen3_5_moe: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen35MoeModel, {
+            readonly recordModelPath: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeQwen35MoeModel;
     };
-    readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen35Model, {
-        readonly recordModelPath: true;
-    }>>;
-    readonly nativeModelClass: typeof NativeQwen35Model;
-}, {
-    readonly modelType: 'qwen3_5_moe';
-    readonly kind: 'trainable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["qwen3_5_moe"];
+    readonly lfm2: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeLfm2Model, {
+            readonly recordModelPath: true;
+            readonly replayAssistantRawText: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeLfm2Model;
     };
-    readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeQwen35MoeModel, {
-        readonly recordModelPath: true;
-    }>>;
-    readonly nativeModelClass: typeof NativeQwen35MoeModel;
-}, {
-    readonly modelType: 'lfm2';
-    readonly kind: 'loadable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["lfm2"];
+    readonly lfm2_moe: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeLfm2Model, {
+            readonly recordModelPath: true;
+            readonly replayAssistantRawText: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeLfm2Model;
     };
-    readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeLfm2Model, {
-        readonly recordModelPath: true;
-        readonly replayAssistantRawText: true;
-    }>>;
-    readonly nativeModelClass: typeof NativeLfm2Model;
-}, {
-    readonly modelType: 'lfm2_moe';
-    readonly kind: 'loadable';
-    readonly match: {
-        readonly rawModelTypes: readonly ["lfm2_moe"];
+    readonly nemotron_h: {
+        readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeNemotronHModel, {
+            readonly recordModelPath: true;
+        }>>;
+        readonly nativeModelClass: typeof NativeNemotronHModel;
     };
-    readonly load: (modelPath: string) => Promise<import("../stream.js").StreamingInstance<typeof NativeLfm2Model, {
-        readonly recordModelPath: true;
-        readonly replayAssistantRawText: true;
-    }>>;
-    readonly nativeModelClass: typeof NativeLfm2Model;
-}, {
-    readonly modelType: 'internvl_chat';
-    readonly kind: 'vlm';
-    readonly match: {
-        readonly rawModelTypes: readonly ["internvl_chat"];
+    readonly internvl_chat: {
+        readonly load: (modelPath: string) => Promise<QianfanOCRModel>;
+        readonly nativeModelClass: typeof QianfanOCRModel;
     };
-    readonly load: (modelPath: string) => Promise<QianfanOCRModel>;
-    readonly nativeModelClass: typeof QianfanOCRModel;
-}, {
-    readonly modelType: 'qianfan-ocr';
-    readonly kind: 'vlm';
-    readonly match: {
-        readonly rawModelTypes: readonly ["qianfan-ocr"];
+    readonly 'qianfan-ocr': {
+        readonly load: (modelPath: string) => Promise<QianfanOCRModel>;
+        readonly nativeModelClass: typeof QianfanOCRModel;
     };
-    readonly load: (modelPath: string) => Promise<QianfanOCRModel>;
-    readonly nativeModelClass: typeof QianfanOCRModel;
-}];
-export type ModelType = (typeof MODEL_FAMILY_REGISTRY)[number]['modelType'];
-type RegisteredModelFamily = (typeof MODEL_FAMILY_REGISTRY)[number];
-type RegisteredTrainableFamily = Extract<RegisteredModelFamily, {
-    readonly kind: 'trainable';
-}>;
+};
+type LoaderBindings = typeof LOADER_BINDINGS;
 /**
  * Union of the native `@mlx-node/core` model classes across every registered
  * family — the public contract of {@link loadModel}. At runtime the chat
@@ -156,21 +108,21 @@ type RegisteredTrainableFamily = Extract<RegisteredModelFamily, {
  * native classes so downstream code can pass instances directly to Rust
  * engine factory methods without type conflicts.
  */
-export type LoadableModel = InstanceType<RegisteredModelFamily['nativeModelClass']>;
+export type LoadableModel = InstanceType<LoaderBindings[ModelType]['nativeModelClass']>;
 /**
  * Union accepted by trainer APIs: registered wrapper results plus their native
- * FFI instances. Both sides derive from the same trainable registry rows.
+ * FFI instances. Both sides derive from the same trainable family ids.
  */
-export type TrainableModel = Awaited<ReturnType<RegisteredTrainableFamily['load']>> | InstanceType<RegisteredTrainableFamily['nativeModelClass']>;
+export type TrainableModel = Awaited<ReturnType<LoaderBindings[TrainableFamilyId]['load']>> | InstanceType<LoaderBindings[TrainableFamilyId]['nativeModelClass']>;
 /**
  * Load a model from disk, auto-detecting architecture from config.json.
  *
  * Supports both language models (Qwen3, Qwen3.5) and vision-language models
  * (Qianfan-OCR / InternVL). Use `instanceof` to narrow the returned type.
  *
- * `options.draftModelPath` attaches an external draft checkpoint (DSpark or
- * Google gemma-4 assistant, auto-detected from the draft's config.json) for
- * speculative decoding — gemma4 only; any other detected family rejects it.
+ * `options.draftModelPath` attaches an external draft checkpoint for
+ * speculative decoding — gemma4 and dense qwen3_5 only; every other family
+ * rejects it.
  * Without the option, Gemma4 loads `<modelPath>/draft/` automatically when
  * that embedded checkpoint is present.
  */
@@ -191,13 +143,17 @@ export declare function loadModel(modelPath: string, options?: LoadModelOptions)
  *     must import `QianfanOCRModel` from `@mlx-node/vlm` and construct
  *     `new ChatSession(model)` directly.
  *
- * `options.draftModelPath` attaches an external draft checkpoint (DSpark or
- * Google gemma-4 assistant, auto-detected from the draft's config.json) for
- * speculative decoding — gemma4 only; any other detected family rejects it.
+ * `options.draftModelPath` attaches an external draft checkpoint for
+ * speculative decoding — gemma4 and dense qwen3_5 only; every other family
+ * rejects it.
  * Without the option, Gemma4 loads `<modelPath>/draft/` automatically when
  * that embedded checkpoint is present.
- * The resulting session auto-enables the speculative path (the model
- * reports `hasMtpWeights()`); pass `enableMtp: false` per call to opt out.
+ * The resulting session auto-enables the speculative path when the model
+ * reports `hasMtpWeights()` AND does not opt out of the auto-default; pass
+ * `enableMtp: false` per call to suppress it, or `enableMtp: true` to force
+ * it on a family that opts out. NemotronH opts out (`mtpAutoEnabled()`
+ * returns false) because forcing MTP moves the turn into the exclusive lane
+ * and out of continuous batching; see `ChatSession.mtpAutoDefaultAllowed`.
  */
 export declare function loadSession(modelPath: string, options?: LoadModelOptions): Promise<ChatSession<SessionCapableModel>>;
 export declare function detectModelType(modelPath: string): Promise<ModelType>;

package/dist/models/model-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-loader.d.ts","sourceRoot":"","sources":["../../src/models/model-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,WAAW,IAAI,iBAAiB,EAChC,YAAY,EACZ,SAAS,IAAI,eAAe,EAC5B,eAAe,EACf,UAAU,IAAI,gBAAgB,EAC9B,WAAW,IAAI,iBAAiB,EAChC,cAAc,IAAI,oBAAoB,EACvC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG3E,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,UAAU,uBAAwB,SAAQ,qBAAqB;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAgCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,qBAAqB;wBAEZ,QAAQ;mBACb,UAAU;;;;;+BAKE,MAAM,YAAY,gBAAgB;;;;;;wBASzC,SAAS;mBACd,WAAW;;;;;+BAMC,MAAM;;;wBAIb,OAAO;mBACZ,WAAW;;iBACR,aAAa;;+BACJ,MAAM;;;;;;;wBAKb,SAAS;mBACd,WAAW;;iBACR,aAAa;;+BACJ,MAAM;;;;;wBAIb,aAAa;mBAClB,WAAW;;iBACR,aAAa;;+BACJ,MAAM;;;;;wBAIb,MAAM;mBACX,UAAU;;iBACP,aAAa;;+BACJ,MAAM;;;;;;wBAIb,UAAU;mBACf,UAAU;;iBACP,aAAa;;+BACJ,MAAM;;;;;;wBAIb,eAAe;mBACpB,KAAK;;iBACF,aAAa;;+BACJ,MAAM;;;wBAIb,aAAa;mBAClB,KAAK;;iBACF,aAAa;;+BACJ,MAAM;;EAGyB,CAAC;AAEtD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AAE5E,KAAK,qBAAqB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,KAAK,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC;AAEhG;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAEpF;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC,GACtD,YAAY,CAAC,yBAAyB,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAsIhE;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAGrG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAa3C;AAED,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAkB3E"}
+{"version":3,"file":"model-loader.d.ts","sourceRoot":"","sources":["../../src/models/model-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EACL,WAAW,IAAI,iBAAiB,EAEhC,YAAY,EACZ,SAAS,IAAI,eAAe,EAC5B,gBAAgB,IAAI,sBAAsB,EAC1C,cAAc,IAAI,oBAAoB,EACtC,eAAe,EACf,UAAU,IAAI,gBAAgB,EAC9B,WAAW,IAAI,iBAAiB,EAChC,cAAc,IAAI,oBAAoB,EACvC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAML,KAAK,SAAS,EACd,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAW3B,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAmBD;;;;;;GAMG;AACH,QAAA,MAAM,eAAe;;iBAEjB,IAAI,cAAc,MAAM,YAAY,gBAAgB;;;iBAKpD,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM,YAAY,gBAAgB;;;iBAKpD,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;;;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;iBACxB,gBAAgB;;;iBAGhB,IAAI,cAAc,MAAM;iBACxB,gBAAgB;;CAEiC,CAAC;AAEtD,KAAK,cAAc,GAAG,OAAO,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAExF;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAC9D,YAAY,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAsCxE;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAGrG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAa3C;AAED,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAwB3E"}

package/dist/models/model-loader.js

@@ -1,203 +1,88 @@
 /**
- * Model loading utilities for Qwen3 models
- *
- * Handles loading pretrained weights from MLX format or converting from HuggingFace.
+ * Native half of the family registry: one loader binding per
+ * `MODEL_FAMILY_DATA` row, plus `detectModelType` (filesystem + GGUF).
  */
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { Gemma4Model as NativeGemma4Model, HarrierModel, Lfm2Model as NativeLfm2Model, QianfanOCRModel, Qwen3Model as NativeQwen3Model, Qwen35Model as NativeQwen35Model, Qwen35MoeModel as NativeQwen35MoeModel, } from '@mlx-node/core';
+import { dirname, extname, join } from 'node:path';
+import { Gemma4Model as NativeGemma4Model, ggufArchitecture, HarrierModel, Lfm2Model as NativeLfm2Model, MuseGlimmerModel as NativeMuseGlimmerModel, NemotronHModel as NativeNemotronHModel, QianfanOCRModel, Qwen3Model as NativeQwen3Model, Qwen35Model as NativeQwen35Model, Qwen35MoeModel as NativeQwen35MoeModel, } from '@mlx-node/core';
 import { ChatSession } from '../chat-session.js';
-import { Gemma4Model, Lfm2Model, Qwen3Model, Qwen35Model, Qwen35MoeModel } from '../stream.js';
+import { familyDataFor, MalformedModelConfigError, matchFamily, MODEL_FAMILY_DATA, UnsupportedModelTypeError, } from '../family-data.js';
+import { Gemma4Model, Lfm2Model, MuseGlimmerModel, NemotronHModel, Qwen3Model, Qwen35Model, Qwen35MoeModel, } from '../stream.js';
 /**
- * Ordered source of truth for every supported model family. Each entry owns
- * its canonical `ModelType`, raw config aliases / architecture probes, loader,
- * and `ChatSession` eligibility:
- *
- *   - `'trainable'` — GRPO/SFT-capable LM (Qwen3 family); chat-capable.
- *   - `'loadable'`  — chat-capable LM with no trainer engine (Gemma4, LFM2).
- *   - `'embedding'` — no chat surface (Harrier); rejected by `loadSession`.
- *   - `'vlm'`       — VLM whose AsyncGenerator wrapper lives in
- *                     `@mlx-node/vlm` (importing it here would create a
- *                     circular package dependency), so `loadSession`
- *                     rejects it and routes callers to `@mlx-node/vlm`.
- *
- * A base family is selected from an explicit alias or the single declarative
- * nullish-model_type default, then architecture probes refine it in declaration
- * order. Gemma's unified architecture is authoritative (matching the native
- * loader); Harrier refines a Qwen3 base. Adding a family means adding one
- * descriptor here, without a second normalization or dispatch branch.
+ * Native half of the family registry: one loader + native class per
+ * `MODEL_FAMILY_DATA` row (the native-free half in `../family-data.ts`).
+ * `satisfies Record<ModelType, LoaderBinding>` makes the zip exhaustive both
+ * ways — a data row without a binding, or a binding without a row, fails to
+ * compile.
  */
-const MODEL_FAMILY_REGISTRY = [
-    {
-        modelType: 'gemma4',
-        kind: 'loadable',
-        match: {
-            rawModelTypes: ['gemma4', 'gemma4_text', 'gemma4_unified'],
-            architectureProbe: ({ architectures }) => architectures.has('Gemma4UnifiedForConditionalGeneration'),
-        },
+const LOADER_BINDINGS = {
+    gemma4: {
         load: (modelPath, options) => Gemma4Model.load(modelPath, options?.draftModelPath === undefined ? null : { draftModelPath: options.draftModelPath }),
         nativeModelClass: NativeGemma4Model,
-        acceptsDraftModel: true,
     },
-    {
-        modelType: 'harrier',
-        kind: 'embedding',
-        match: {
-            rawModelTypes: ['harrier'],
-            architectureProbe: ({ modelType, architectures }) => modelType === 'qwen3' && architectures.has('Qwen3Model') && !architectures.has('Qwen3ForCausalLM'),
-        },
+    muse_glimmer: {
+        load: (modelPath) => MuseGlimmerModel.load(modelPath),
+        nativeModelClass: NativeMuseGlimmerModel,
+    },
+    harrier: {
         load: (modelPath) => HarrierModel.load(modelPath),
         nativeModelClass: HarrierModel,
     },
-    {
-        modelType: 'qwen3',
-        kind: 'trainable',
-        match: { rawModelTypes: ['qwen3'] },
+    qwen3: {
         load: (modelPath) => Qwen3Model.load(modelPath),
         nativeModelClass: NativeQwen3Model,
-        defaultForNullishModelType: true,
     },
-    {
-        modelType: 'qwen3_5',
-        kind: 'trainable',
-        match: { rawModelTypes: ['qwen3_5'] },
-        load: (modelPath) => Qwen35Model.load(modelPath),
+    qwen3_5: {
+        load: (modelPath, options) => Qwen35Model.load(modelPath, options?.draftModelPath === undefined ? null : { draftModelPath: options.draftModelPath }),
         nativeModelClass: NativeQwen35Model,
     },
-    {
-        modelType: 'qwen3_5_moe',
-        kind: 'trainable',
-        match: { rawModelTypes: ['qwen3_5_moe'] },
+    qwen3_5_moe: {
         load: (modelPath) => Qwen35MoeModel.load(modelPath),
         nativeModelClass: NativeQwen35MoeModel,
     },
-    {
-        modelType: 'lfm2',
-        kind: 'loadable',
-        match: { rawModelTypes: ['lfm2'] },
+    lfm2: {
         load: (modelPath) => Lfm2Model.load(modelPath),
         nativeModelClass: NativeLfm2Model,
     },
-    {
-        modelType: 'lfm2_moe',
-        kind: 'loadable',
-        match: { rawModelTypes: ['lfm2_moe'] },
+    lfm2_moe: {
         load: (modelPath) => Lfm2Model.load(modelPath),
         nativeModelClass: NativeLfm2Model,
     },
-    {
-        modelType: 'internvl_chat',
-        kind: 'vlm',
-        match: { rawModelTypes: ['internvl_chat'] },
+    nemotron_h: {
+        load: (modelPath) => NemotronHModel.load(modelPath),
+        nativeModelClass: NativeNemotronHModel,
+    },
+    internvl_chat: {
         load: (modelPath) => QianfanOCRModel.load(modelPath),
         nativeModelClass: QianfanOCRModel,
     },
-    {
-        modelType: 'qianfan-ocr',
-        kind: 'vlm',
-        match: { rawModelTypes: ['qianfan-ocr'] },
+    'qianfan-ocr': {
         load: (modelPath) => QianfanOCRModel.load(modelPath),
         nativeModelClass: QianfanOCRModel,
     },
-];
-function buildModelFamilyIndex(registry) {
-    const byModelType = new Map();
-    const byRawModelType = new Map();
-    let defaultForNullishModelType;
-    for (const family of registry) {
-        const previousFamily = byModelType.get(family.modelType);
-        if (previousFamily !== undefined) {
-            throw new Error(`Duplicate canonical model type "${family.modelType}" in model family registry`);
-        }
-        byModelType.set(family.modelType, family);
-        for (const rawModelType of family.match.rawModelTypes) {
-            const previous = byRawModelType.get(rawModelType);
-            if (previous !== undefined) {
-                throw new Error(`Duplicate model_type alias "${rawModelType}" for "${previous.modelType}" and "${family.modelType}"`);
-            }
-            byRawModelType.set(rawModelType, family);
-        }
-        if (family.defaultForNullishModelType === true) {
-            if (defaultForNullishModelType !== undefined) {
-                throw new Error(`Duplicate nullish-model_type defaults for "${defaultForNullishModelType.modelType}" and "${family.modelType}"`);
-            }
-            defaultForNullishModelType = family;
-        }
-    }
-    if (defaultForNullishModelType === undefined) {
-        throw new Error('Model family registry must declare exactly one nullish-model_type default');
-    }
-    return { byModelType, byRawModelType, defaultForNullishModelType };
-}
-const MODEL_FAMILY_INDEX = buildModelFamilyIndex(MODEL_FAMILY_REGISTRY);
-function findFamily(modelType) {
-    const family = MODEL_FAMILY_INDEX.byModelType.get(modelType);
+};
+// Only families whose native `load(path)` accepts a GGUF file carry a
+// `ggufArchitectures` row entry (see family-data.ts).
+const GGUF_ARCHITECTURE_MODEL_TYPES = new Map(MODEL_FAMILY_DATA.flatMap((row) => 'ggufArchitectures' in row ? row.ggufArchitectures.map((architecture) => [architecture, row.id]) : []));
+function requireFamilyData(modelType) {
+    const family = familyDataFor(modelType);
     if (family === undefined) {
         throw new Error(`Internal error: missing model family descriptor for "${modelType}"`);
     }
     return family;
 }
-function matchesArchitectureProbe(family, config) {
-    return family.match.architectureProbe?.(config) === true;
-}
-class MalformedModelConfigError extends Error {
-    constructor(modelPath, reason) {
-        super(`Malformed config.json in ${modelPath}: ${reason}`);
-        this.name = 'MalformedModelConfigError';
-    }
-}
-/**
- * Fail-closed validation: a config.json whose root is not a plain object,
- * or whose `architectures` is neither an array nor a string, is rejected
- * instead of coerced (coercion would fall through to the qwen3
- * nullish-model_type default and silently misroute the checkpoint).
- * Blessed lenient shapes stay accepted: `{}` root (qwen3 default),
- * missing/`null` `architectures` (empty set), bare-string `architectures`
- * (single-element set), and non-string array entries (filtered out).
- */
-function normalizeConfig(modelPath, config) {
-    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
-        throw new MalformedModelConfigError(modelPath, 'root must be a JSON object');
-    }
-    const object = config;
-    const hasModelType = Object.hasOwn(object, 'model_type');
-    const rawModelTypeValue = hasModelType ? object.model_type : undefined;
-    const usesDefaultModelType = !hasModelType || rawModelTypeValue === null;
-    const rawModelType = typeof rawModelTypeValue === 'string' ? rawModelTypeValue : undefined;
-    const rawModelTypeLabel = hasModelType ? String(rawModelTypeValue) : '<missing>';
-    const rawArchitectures = 'architectures' in object ? object.architectures : undefined;
-    if (rawArchitectures !== undefined &&
-        rawArchitectures !== null &&
-        !Array.isArray(rawArchitectures) &&
-        typeof rawArchitectures !== 'string') {
-        throw new MalformedModelConfigError(modelPath, '"architectures" must be an array or a string');
-    }
-    const architectures = Array.isArray(rawArchitectures)
-        ? rawArchitectures.filter((architecture) => typeof architecture === 'string')
-        : typeof rawArchitectures === 'string'
-            ? [rawArchitectures]
-            : [];
-    return { usesDefaultModelType, rawModelType, rawModelTypeLabel, architectures: new Set(architectures) };
-}
-class UnsupportedModelTypeError extends Error {
-    constructor(modelPath, rawModelTypeLabel) {
-        super(`Unsupported model_type "${rawModelTypeLabel}" in ${modelPath}/config.json`);
-        this.name = 'UnsupportedModelTypeError';
-    }
-}
 /**
- * Dispatch a load through the registry, validating gemma4-only options.
- * `draftModelPath` reaches ONLY the gemma4 row; every other family rejects
- * it loudly instead of silently ignoring a caller's speculative-decode
- * intent.
+ * Dispatch a load through the registry, validating draft-capable families.
+ * `draftModelPath` reaches only gemma4 and dense qwen3_5; every other family
+ * rejects it loudly instead of silently ignoring speculative-decode intent.
  */
 function dispatchLoad(modelType, modelPath, options) {
-    const family = findFamily(modelType);
-    if (options?.draftModelPath !== undefined && family.acceptsDraftModel !== true) {
-        throw new Error(`draftModelPath (speculative-decoding draft) is only supported by gemma4 models; ` +
+    if (options?.draftModelPath !== undefined && requireFamilyData(modelType).acceptsDraftModel !== true) {
+        throw new Error(`draftModelPath (speculative-decoding draft) is only supported by gemma4 and qwen3_5 models; ` +
             `${modelPath} has model_type "${modelType}"`);
     }
-    return family.load(modelPath, options);
+    const binding = LOADER_BINDINGS[modelType];
+    return binding.load(modelPath, options);
 }
 /**
  * Load a model from disk, auto-detecting architecture from config.json.
@@ -205,9 +90,9 @@ function dispatchLoad(modelType, modelPath, options) {
  * Supports both language models (Qwen3, Qwen3.5) and vision-language models
  * (Qianfan-OCR / InternVL). Use `instanceof` to narrow the returned type.
  *
- * `options.draftModelPath` attaches an external draft checkpoint (DSpark or
- * Google gemma-4 assistant, auto-detected from the draft's config.json) for
- * speculative decoding — gemma4 only; any other detected family rejects it.
+ * `options.draftModelPath` attaches an external draft checkpoint for
+ * speculative decoding — gemma4 and dense qwen3_5 only; every other family
+ * rejects it.
  * Without the option, Gemma4 loads `<modelPath>/draft/` automatically when
  * that embedded checkpoint is present.
  */
@@ -231,17 +116,21 @@ export async function loadModel(modelPath, options) {
  *     must import `QianfanOCRModel` from `@mlx-node/vlm` and construct
  *     `new ChatSession(model)` directly.
  *
- * `options.draftModelPath` attaches an external draft checkpoint (DSpark or
- * Google gemma-4 assistant, auto-detected from the draft's config.json) for
- * speculative decoding — gemma4 only; any other detected family rejects it.
+ * `options.draftModelPath` attaches an external draft checkpoint for
+ * speculative decoding — gemma4 and dense qwen3_5 only; every other family
+ * rejects it.
  * Without the option, Gemma4 loads `<modelPath>/draft/` automatically when
  * that embedded checkpoint is present.
- * The resulting session auto-enables the speculative path (the model
- * reports `hasMtpWeights()`); pass `enableMtp: false` per call to opt out.
+ * The resulting session auto-enables the speculative path when the model
+ * reports `hasMtpWeights()` AND does not opt out of the auto-default; pass
+ * `enableMtp: false` per call to suppress it, or `enableMtp: true` to force
+ * it on a family that opts out. NemotronH opts out (`mtpAutoEnabled()`
+ * returns false) because forcing MTP moves the turn into the exclusive lane
+ * and out of continuous batching; see `ChatSession.mtpAutoDefaultAllowed`.
  */
 export async function loadSession(modelPath, options) {
     const modelType = await detectModelType(modelPath);
-    const kind = findFamily(modelType).kind;
+    const kind = requireFamilyData(modelType).kind;
     if (kind === 'embedding') {
         throw new Error('loadSession: embedding models (Harrier) cannot be wrapped in a ChatSession');
     }
@@ -252,19 +141,25 @@ export async function loadSession(modelPath, options) {
     return new ChatSession(m);
 }
 export async function detectModelType(modelPath) {
+    const isGguf = extname(modelPath).toLowerCase() === '.gguf';
+    const configPath = isGguf ? join(dirname(modelPath), 'config.json') : join(modelPath, 'config.json');
+    let raw;
+    try {
+        raw = await readFile(configPath, 'utf-8');
+    }
+    catch (e) {
+        if (isGguf && typeof e === 'object' && e !== null && 'code' in e && e.code === 'ENOENT') {
+            const architecture = ggufArchitecture(modelPath);
+            const modelType = GGUF_ARCHITECTURE_MODEL_TYPES.get(architecture);
+            if (modelType === undefined) {
+                throw new Error(`Unsupported GGUF architecture "${architecture}" in ${modelPath}`);
+            }
+            return modelType;
+        }
+        throw new Error(`Cannot detect model type: config.json not found in ${modelPath}`);
+    }
     try {
-        const raw = await readFile(join(modelPath, 'config.json'), 'utf-8');
-        const config = normalizeConfig(modelPath, JSON.parse(raw));
-        const baseFamily = config.usesDefaultModelType
-            ? MODEL_FAMILY_INDEX.defaultForNullishModelType
-            : config.rawModelType === undefined
-                ? undefined
-                : MODEL_FAMILY_INDEX.byRawModelType.get(config.rawModelType);
-        const matchContext = { ...config, modelType: baseFamily?.modelType };
-        const family = MODEL_FAMILY_REGISTRY.find((candidate) => matchesArchitectureProbe(candidate, matchContext)) ?? baseFamily;
-        if (family === undefined)
-            throw new UnsupportedModelTypeError(modelPath, config.rawModelTypeLabel);
-        return family.modelType;
+        return matchFamily(modelPath, JSON.parse(raw));
     }
     catch (e) {
         if (e instanceof UnsupportedModelTypeError || e instanceof MalformedModelConfigError)

package/dist/models/paged-config-override.d.ts

@@ -9,8 +9,6 @@
  * Gemma4 `draft/`) remain hidden unless a caller explicitly preserves the
  * Gemma draft for flat speculative decoding.
  */
-/** Every chat-capable family currently discovered by `@mlx-node/agent`. */
-export declare const AGENT_PAGED_MODEL_TYPES: readonly ['qwen3', 'qwen3_5', 'qwen3_5_moe', 'gemma4', 'lfm2', 'lfm2_moe'];
 /** Families historically forced paged by `mlx launch claude`. */
 export declare const QWEN35_PAGED_MODEL_TYPES: readonly ['qwen3_5', 'qwen3_5_moe'];
 export interface PagedConfigOverrideManagerOptions {

package/dist/models/paged-config-override.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paged-config-override.d.ts","sourceRoot":"","sources":["../../src/models/paged-config-override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,YAAI,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAElH,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,YAAI,SAAS,EAAE,aAAa,CAAU,CAAC;AAO5E,MAAM,WAAW,iCAAiC;IAChD,qFAAqF;IACrF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,OAAO,GAAE,iCAAsC,EAI1D;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1G;YAEa,eAAe;IAuE7B,6EAA6E;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvB;YAEa,cAAc;YAad,cAAc;IAsD5B,OAAO,CAAC,OAAO;CAIhB"}
+{"version":3,"file":"paged-config-override.d.ts","sourceRoot":"","sources":["../../src/models/paged-config-override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,YAAI,SAAS,EAAE,aAAa,CAAU,CAAC;AAQ5E,MAAM,WAAW,iCAAiC;IAChD,qFAAqF;IACrF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,OAAO,GAAE,iCAAsC,EAI1D;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1G;YAEa,eAAe;IAgF7B,6EAA6E;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvB;YAEa,cAAc;YAad,cAAc;IA+D5B,OAAO,CAAC,OAAO;CAIhB"}