@mlx-node/lm 0.0.13 → 0.0.15

package/src/gguf-metadata.ts

@@ -0,0 +1,117 @@
+/** Read GGUF metadata without linking the native addon or loading tensor weights. */
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+
+const MAX_GGUF_LENGTH = 256 * 1024 * 1024;
+const SCALAR_BYTES = new Map([
+  [0, 1],
+  [1, 1],
+  [2, 2],
+  [3, 2],
+  [4, 4],
+  [5, 4],
+  [6, 4],
+  [7, 1],
+  [10, 8],
+  [11, 8],
+  [12, 8],
+]);
+
+/** Buffered header cursor; skipping an array never allocates its payload. */
+class HeaderReader {
+  private readonly buffer = Buffer.alloc(64 * 1024);
+  private start = 0;
+  private end = 0;
+  private position = 0;
+
+  constructor(
+    private readonly fd: number,
+    private readonly size: number,
+  ) {}
+
+  skip(length: number): void {
+    if (!Number.isSafeInteger(length) || length < 0 || length > this.size - this.position) {
+      throw new Error('Truncated or oversized GGUF metadata');
+    }
+    this.position += length;
+  }
+
+  bytes(length: number): Buffer {
+    const position = this.position;
+    this.skip(length);
+    if (length > MAX_GGUF_LENGTH) throw new Error('GGUF string exceeds maximum length');
+    const result = Buffer.alloc(length);
+    let offset = 0;
+    while (offset < length) {
+      const current = position + offset;
+      if (current < this.start || current >= this.end) {
+        this.start = current;
+        this.end = current + readSync(this.fd, this.buffer, 0, this.buffer.length, current);
+        if (this.end === current) throw new Error('Truncated GGUF metadata');
+      }
+      const count = Math.min(length - offset, this.end - current);
+      this.buffer.copy(result, offset, current - this.start, current - this.start + count);
+      offset += count;
+    }
+    return result;
+  }
+
+  u32(): number {
+    return this.bytes(4).readUInt32LE();
+  }
+  u64(): number {
+    const value = this.bytes(8).readBigUInt64LE();
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('Oversized GGUF metadata length');
+    return Number(value);
+  }
+  length(): number {
+    const length = this.u64();
+    if (length > MAX_GGUF_LENGTH) throw new Error('GGUF metadata exceeds maximum length');
+    return length;
+  }
+  string(): string {
+    return new TextDecoder('utf-8', { fatal: true }).decode(this.bytes(this.length()));
+  }
+
+  skipValue(type: number, depth = 0): void {
+    const size = SCALAR_BYTES.get(type);
+    if (size !== undefined) return this.skip(size);
+    if (type === 8) return this.skip(this.length());
+    if (type !== 9 || depth > 16) throw new Error('Unsupported GGUF metadata type');
+    const element = this.u32();
+    const count = this.length();
+    const elementSize = SCALAR_BYTES.get(element);
+    if (elementSize !== undefined) return this.skip(count * elementSize);
+    if (element !== 8 && element !== 9) throw new Error('Unsupported GGUF array element type');
+    for (let index = 0; index < count; index++) this.skipValue(element, depth + 1);
+  }
+}
+
+export function readGgufArchitecture(path: string): string {
+  // O_NONBLOCK plus the descriptor type check prevents a renamed FIFO from
+  // hanging model discovery in the control-panel worker.
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw new Error('GGUF path must be a regular file');
+    const reader = new HeaderReader(fd, info.size);
+    if (reader.bytes(4).toString() !== 'GGUF') throw new Error('Not a GGUF file');
+    if (reader.u32() < 3) throw new Error('Unsupported GGUF version (only v3+ supported)');
+    reader.u64(); // Tensor count: discovery only needs the metadata section.
+    const count = reader.u64();
+    let architecture: string | undefined;
+    for (let index = 0; index < count; index++) {
+      const key = reader.string();
+      const type = reader.u32();
+      if (key === 'general.architecture') {
+        architecture = type === 8 ? reader.string() : undefined;
+        if (type !== 8) reader.skipValue(type);
+      } else {
+        reader.skipValue(type);
+      }
+    }
+    if (!architecture) throw new Error('GGUF does not declare a non-empty general.architecture');
+    return architecture;
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * @mlx-node/lm - High-level inference API for MLX models
+ *
+ * This package provides everything needed for model loading and inference,
+ * aligned with Python's mlx-lm library.
+ *
+ * @example
+ * ```typescript
+ * import { loadModel, Qwen3Model } from '@mlx-node/lm';
+ *
+ * const model = await loadModel('./models/qwen3-0.6b');
+ * const result = await model.generate([{ role: 'user', content: 'Hello!' }]);
+ * ```
+ */
+
+// Model classes (for inference)
+export { Qwen3Model } from './stream.js';
+
+// Gemma4 models
+export { Gemma4Model } from './stream.js';
+
+// Muse-Glimmer models
+export { MuseGlimmerModel } from './stream.js';
+
+// Embedding models
+export { HarrierModel } from '@mlx-node/core';
+export { Qwen35Model } from './stream.js';
+export type { Qwen35Config, Qwen35ContextLimits } from '@mlx-node/core';
+
+// LFM2 models
+export { Lfm2Model } from './stream.js';
+export { LFM2_CONFIGS, getLfm2Config } from './models/lfm2-configs.js';
+
+// MoE variant
+export { Qwen35MoeModel } from './stream.js';
+export type { Qwen35MoeConfig } from '@mlx-node/core';
+
+// Nemotron H models
+//
+// The config/limits types ship alongside the class for the same reason
+// Qwen3.5's do: `NemotronHModel` exposes both `getConfig()` and
+// `contextLimits()`, and without these exports a consumer cannot name
+// either return type. (`MuseGlimmerModel` above deliberately exports no
+// config type — that wrapper has no `getConfig()` at all.)
+export { NemotronHModel } from './stream.js';
+export type { NemotronHConfig, NemotronHContextLimits } from '@mlx-node/core';
+
+// Memory hygiene: most management is automatic — the decode loop
+// inside `@mlx-node/core` calls `mlx_clear_cache()` every 256 generated
+// tokens to prevent unbounded free-pool growth during long
+// generations, and `MLX_CACHE_LIMIT_GB` auto-tunes the Metal pool cap
+// at model load. Across-request drains are handled by the
+// `@mlx-node/server` idle sweeper (see `packages/server/src/idle-sweeper.ts`):
+// a single `clearCache()` fires after `idleClearCacheMs` of HTTP
+// inactivity once the in-flight request counter has returned to zero.
+// `memoryStats()` is re-exported as a read-only observability hook for
+// dashboards / debugging.
+//
+// `clearCache()` is DELIBERATELY not re-exported here: the native impl
+// routes through MLX's no-arg `synchronize()` which waits only on the
+// default stream, so calling it while a decode runs on a model's
+// custom stream risks racing live Metal command buffers. The only
+// safe caller today is `@mlx-node/server`'s idle sweeper (fires after
+// the in-flight request counter hits zero AND — for hot-load flows —
+// outside any `withSuspendedDrains()` bracket). Admin / cron code that
+// reaches for a manual drain should deep-import from `@mlx-node/core`
+// directly and read the `@internal` caveat there.
+export { memoryStats } from '@mlx-node/core';
+
+// Unified Chat API types (shared by Qwen3, Qwen3.5, Qwen3.5 MoE)
+export type { ChatConfig, ChatResult, ChatMessage, ToolCallResult, PerformanceMetrics } from '@mlx-node/core';
+
+// Streaming chat API
+export type { ChatStreamDelta, ChatStreamFinal, ChatStreamEvent } from './stream.js';
+// Internal: exported for testing the callback-to-AsyncGenerator bridge
+// Not part of the public API — may change without notice.
+// `_runChatStream` is the generic adapter used by every model wrapper
+// (and the VLM package's QianfanOCR wrapper) to turn a callback-based
+// native stream into an `AsyncGenerator<ChatStreamEvent>`.
+// `makeStreamingModel` is the factory that builds each family's wrapper
+// subclass from its native class; the VLM package reuses it to build
+// `QianfanOCRModel`.
+export { _runChatStream, makeStreamingModel } from './stream.js';
+export type { NativeStreamingInstance, NativeStreamingMethod, StreamingInstance, StreamingModel } from './stream.js';
+// Cross-model chat session wrapper (see chat-session.ts for design notes).
+// `SessionCapableModel` is the structural interface matched by every
+// generative model wrapper and used as the upper-bound for
+// `ChatSession<M>`; exported so the VLM wrapper can pin a compile-time
+// conformance assertion.
+export { ChatSession, ContextCapacityError, isContextCapacityError } from './chat-session.js';
+export type { ChatSessionOptions, SendOptions, SessionCapableModel, SessionContextLimits } from './chat-session.js';
+
+// Model utilities (TypeScript-only)
+export {
+  type Qwen3Config,
+  QWEN3_CONFIGS,
+  type GenerationResult,
+  type GenerationConfig,
+  getQwen3Config,
+} from './models/qwen3-configs.js';
+
+// Model loading
+export {
+  loadModel,
+  loadSession,
+  detectModelType,
+  type LoadableModel,
+  type TrainableModel,
+  type LoadModelOptions,
+} from './models/model-loader.js';
+
+// Native-free per-family registration data (also published as the
+// `@mlx-node/lm/family-data` subpath for consumers that must not dlopen the
+// addon; see family-data.ts).
+export {
+  CHAT_FAMILY_IDS,
+  familyDataFor,
+  familyTraitsFor,
+  GEMMA4_SAMPLING_DEFAULTS,
+  launchPresetFor,
+  LFM2_SAMPLING_DEFAULTS,
+  matchFamily,
+  MODEL_FAMILY_DATA,
+  MUSE_GLIMMER_SAMPLING_DEFAULTS,
+  NEMOTRON_SAMPLING_DEFAULTS,
+  NON_GENERATIVE_FAMILY_IDS,
+  QWEN_SAMPLING_DEFAULTS,
+  rawModelTypeToCanonical,
+  type ChatFamilyId,
+  type FamilyThinkingLevelMap,
+  type FamilyTraits,
+  type LaunchPreset,
+  type ModelFamilyData,
+  type ModelFamilyKind,
+  type ModelType,
+  type TrainableFamilyId,
+} from './family-data.js';
+
+export {
+  PagedConfigOverrideManager,
+  QWEN35_PAGED_MODEL_TYPES,
+  type PagedConfigOverrideManagerOptions,
+} from './models/paged-config-override.js';
+
+export { QWEN35_CONFIGS, getQwen35Config } from './models/qwen3_5-configs.js';
+
+// Tool calling utilities
+export * from './tools/index.js';
+
+// Profiling API
+export { enableProfiling, disableProfiling } from './profiling.js';

package/src/model-detection.ts

@@ -0,0 +1,46 @@
+/** Shared filesystem-only model detection for inference and control-panel discovery. */
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+
+import { MODEL_FAMILY_DATA, matchFamily, type ModelType } from './family-data.js';
+import { readGgufArchitecture } from './gguf-metadata.js';
+
+export { readGgufArchitecture } from './gguf-metadata.js';
+
+const GGUF_ARCHITECTURE_MODEL_TYPES = new Map<string, ModelType>(
+  MODEL_FAMILY_DATA.flatMap((row) =>
+    'ggufArchitectures' in row ? row.ggufArchitectures.map((architecture) => [architecture, row.id] as const) : [],
+  ),
+);
+
+export async function readModelConfig(modelDir: string): Promise<unknown> {
+  const file = await open(join(modelDir, 'config.json'), constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    if (!(await file.stat()).isFile()) throw new Error('Model config must be a regular file');
+    return JSON.parse(await file.readFile('utf8'));
+  } finally {
+    await file.close();
+  }
+}
+
+/** The loader can supply its native header validator without changing family selection. */
+export async function detectModelType(
+  modelPath: string,
+  readArchitecture: (path: string) => string = readGgufArchitecture,
+): Promise<ModelType> {
+  const isGguf = extname(modelPath).toLowerCase() === '.gguf';
+  let config: unknown;
+  try {
+    config = await readModelConfig(isGguf ? dirname(modelPath) : modelPath);
+  } catch (error) {
+    if (isGguf && (error as NodeJS.ErrnoException).code === 'ENOENT') {
+      const architecture = readArchitecture(modelPath);
+      const type = GGUF_ARCHITECTURE_MODEL_TYPES.get(architecture);
+      if (type === undefined) throw new Error(`Unsupported GGUF architecture "${architecture}" in ${modelPath}`);
+      return type;
+    }
+    throw new Error(`Cannot detect model type: config.json not found in ${modelPath}`);
+  }
+  return matchFamily(modelPath, config);
+}

package/src/model-discovery.ts

@@ -0,0 +1,329 @@
+/** Shared, native-free discovery of local chat checkpoints. */
+
+import type { Dirent } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import {
+  launchPresetFor,
+  familyTraitsFor,
+  NON_GENERATIVE_FAMILY_IDS,
+  MODEL_FAMILY_DATA,
+  type FamilyTraits,
+  type LaunchPreset,
+  type ModelType,
+} from './family-data.js';
+import { detectModelType, readGgufArchitecture, readModelConfig } from './model-detection.js';
+
+/** Native-free inventory shared by the agent, setup UI, and inference host. */
+export interface LocalChatModel {
+  name: string;
+  path: string;
+  modelType: ModelType;
+  preset: LaunchPreset;
+  traits: FamilyTraits;
+  contextWindow: number;
+  supportsImages: boolean;
+}
+
+interface DiscoveryMetadata {
+  contextWindow: number;
+  supportsImages: boolean;
+  draftOnly: boolean;
+}
+
+/**
+ * The Qwen3.5/Qwen3.8 discovery filter retains its XL policy. Gemma4 and Muse
+ * accept all supported tensor formats, including Q4_0 QAT checkpoints.
+ * Match the Unsloth Dynamic XL target names users download, while excluding
+ * ordinary Q4_K_M files and companion artifacts such as imatrix/mmproj/draft.
+ */
+const QWEN35_XL_GGUF = /(?:^|[-_.])Q\d+_K_XL\.gguf$/i;
+const GGUF_COMPANION_NAME = /(?:^|[-_.])(?:imatrix|mmproj|dflash|draft)(?:[-_.]|$)/i;
+// Match the native loaders' primary files/shards. A draft or projector
+// SafeTensors file beside a GGUF is not a converted target checkpoint.
+const PRIMARY_SAFETENSORS = /^(?:model|weights)\.safetensors$|^model(?:-|\.safetensors-).+-of-.+\.safetensors$/;
+
+function isQwen35XlGguf(name: string): boolean {
+  return QWEN35_XL_GGUF.test(name) && !GGUF_COMPANION_NAME.test(name);
+}
+
+function ggufModelName(name: string): string {
+  return name.slice(0, -'.gguf'.length);
+}
+
+function requiresGgufAssets(modelType: ModelType): boolean {
+  return modelType === 'gemma4' || modelType === 'muse_glimmer';
+}
+
+function matchesGgufFamily(path: string, modelType: ModelType): boolean {
+  const architecture = readGgufArchitecture(path);
+  return MODEL_FAMILY_DATA.some(
+    (family) =>
+      family.id === modelType &&
+      'ggufArchitectures' in family &&
+      family.ggufArchitectures.some((supported) => supported === architecture),
+  );
+}
+
+async function hasGgufAssets(modelDir: string): Promise<boolean> {
+  try {
+    const assets = await Promise.all(['config.json', 'tokenizer.json'].map((name) => stat(join(modelDir, name))));
+    return assets.every((asset) => asset.isFile());
+  } catch {
+    return false;
+  }
+}
+
+interface ModelFileInventory {
+  xlGgufs: string[];
+  targetGgufs: string[];
+  hasGguf: boolean;
+  hasSafetensors: boolean;
+  hasPrimarySafetensors: boolean;
+}
+
+async function modelFileInventory(modelDir: string): Promise<ModelFileInventory> {
+  try {
+    const files = (await readdir(modelDir, { withFileTypes: true }))
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name);
+    return {
+      xlGgufs: files.filter(isQwen35XlGguf).sort(),
+      targetGgufs: files
+        .filter((name) => name.toLowerCase().endsWith('.gguf') && !GGUF_COMPANION_NAME.test(name))
+        .sort(),
+      hasGguf: files.some((name) => name.toLowerCase().endsWith('.gguf')),
+      hasSafetensors: files.some((name) => name.toLowerCase().endsWith('.safetensors')),
+      hasPrimarySafetensors: files.some((name) => PRIMARY_SAFETENSORS.test(name)),
+    };
+  } catch {
+    return { xlGgufs: [], targetGgufs: [], hasGguf: false, hasSafetensors: false, hasPrimarySafetensors: false };
+  }
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+function nonEmptyRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+
+/**
+ * Read cheap discovery metadata from `<modelPath>/config.json`.
+ *
+ * The trained context window comes from:
+ * root `max_position_embeddings` first (qwen3, lfm2), then
+ * `text_config.max_position_embeddings` (qwen3_5, qwen3_5_moe, gemma4
+ * unified), else the family fallback.
+ *
+ * Image support is advertised only when a family with a native multimodal
+ * implementation carries its valid, non-empty vision marker: `vision_config`
+ * for Qwen, and either `vision_config` or `unified_vision_config` for Gemma.
+ * This lets Pi's model picker and `--list-models` expose checkpoint capability
+ * without loading weights. The first resident load remains authoritative and
+ * reconciles this optimistic config-level advertisement via
+ * `session.supportsImages()` (for example, when conversion stripped an
+ * incompatible vision tower).
+ *
+ * `detectModelType` already parsed this file, so a read/parse failure here
+ * (e.g. a racing rewrite) lands on the context fallback and text-only input
+ * instead of dropping the model or guessing a positive capability.
+ */
+async function readDiscoveryMetadata(
+  modelPath: string,
+  modelType: ModelType,
+  fallbackContextWindow: number,
+): Promise<DiscoveryMetadata> {
+  try {
+    const config = (await readModelConfig(modelPath)) as Record<string, unknown>;
+    const root = positiveInteger(config.max_position_embeddings);
+    const textConfig = config.text_config;
+    const nested = nonEmptyRecord(textConfig) ? positiveInteger(textConfig.max_position_embeddings) : undefined;
+    const hasVisionConfig = nonEmptyRecord(config.vision_config);
+    const supportsImages =
+      modelType === 'gemma4'
+        ? hasVisionConfig || nonEmptyRecord(config.unified_vision_config)
+        : (modelType === 'qwen3_5' || modelType === 'qwen3_5_moe') && hasVisionConfig;
+    const draftOnly = Array.isArray(config.architectures) && config.architectures.includes('DFlash2DraftModel');
+
+    return {
+      contextWindow: root ?? nested ?? fallbackContextWindow,
+      supportsImages,
+      draftOnly,
+    };
+  } catch {
+    return { contextWindow: fallbackContextWindow, supportsImages: false, draftOnly: false };
+  }
+}
+
+/**
+ * Scan `modelsDir` for chat-capable model subdirectories, Gemma4/Muse GGUFs, and
+ * dense Qwen3.5/Qwen3.8 `Q<number>_K_XL.gguf` files. GGUF files may live directly
+ * under `modelsDir` or one level inside a downloaded GGUF repository. Each is
+ * registered by filename stem so quant variants remain independently selectable.
+ *
+ * An unreadable dir yields `[]`. Entries with an undetectable config, a
+ * non-generative type, or no launch preset are skipped silently (warnings only
+ * when `MLX_DEBUG` is set). No weights are loaded. Results are sorted by name.
+ */
+export async function discoverLocalChatModels(modelsDir: string): Promise<LocalChatModel[]> {
+  const debug = Boolean(process.env.MLX_DEBUG);
+
+  let entries: Dirent[];
+  try {
+    entries = await readdir(modelsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  // Collision resolution below gives the first occurrence the bare filename
+  // stem. Directory enumeration order is unspecified, so sort before assigning
+  // IDs to keep persisted `mlx/<id>` selections stable across filesystems.
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  const out: LocalChatModel[] = [];
+  const usedNames = new Set<string>();
+
+  const append = async (
+    preferredName: string,
+    path: string,
+    metadataRoot: string,
+    modelType: ModelType,
+    scopeName: string,
+  ): Promise<void> => {
+    if (NON_GENERATIVE_FAMILY_IDS.has(modelType)) return;
+
+    // Fail-closed guards: dead-by-construction for chat families (the
+    // family-data row type requires traits + a preset), live for any foreign
+    // string that slips through detection.
+    const preset = launchPresetFor(modelType);
+    if (!preset) {
+      if (debug) console.warn(`[mlx] skip ${path}: no launch preset for ${modelType}`);
+      return;
+    }
+    const traits = familyTraitsFor(modelType);
+    if (!traits) {
+      if (debug) console.warn(`[mlx] skip ${path}: no FAMILY_TRAITS entry for ${modelType}`);
+      return;
+    }
+
+    const metadata = await readDiscoveryMetadata(metadataRoot, modelType, traits.fallbackContextWindow);
+    if (metadata.draftOnly) {
+      if (debug) console.warn(`[mlx] skip ${path}: companion draft checkpoint is not a chat model`);
+      return;
+    }
+
+    let name = preferredName;
+    if (usedNames.has(name)) {
+      name = `${scopeName}-${preferredName}`;
+      let suffix = 2;
+      while (usedNames.has(name)) name = `${scopeName}-${preferredName}-${suffix++}`;
+    }
+    usedNames.add(name);
+    // Automatic companions can be installed or removed after this startup
+    // scan. The host resolves them on each load; draftModelPath is reserved
+    // for caller-supplied paths that the loader must treat as authoritative.
+    out.push({
+      name,
+      path,
+      modelType,
+      preset,
+      traits,
+      contextWindow: metadata.contextWindow,
+      supportsImages: metadata.supportsImages,
+    });
+  };
+
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.gguf') && !GGUF_COMPANION_NAME.test(entry.name)) {
+      const full = join(modelsDir, entry.name);
+      try {
+        const modelType = await detectModelType(full);
+        // A shared sibling config can describe another target or a projector.
+        // Never advertise a file under a loader that disagrees with its header.
+        if (!matchesGgufFamily(full, modelType)) continue;
+        if (requiresGgufAssets(modelType) && !(await hasGgufAssets(modelsDir))) {
+          if (debug)
+            console.warn(
+              `[mlx] skip ${full}: native ${modelType} GGUF requires sibling config.json and tokenizer.json`,
+            );
+          continue;
+        }
+        if (
+          modelType === 'gemma4' ||
+          modelType === 'muse_glimmer' ||
+          (modelType === 'qwen3_5' && isQwen35XlGguf(entry.name))
+        ) {
+          await append(ggufModelName(entry.name), full, modelsDir, modelType, basename(modelsDir));
+        } else if (debug) {
+          console.warn(`[mlx] skip ${full}: no supported direct GGUF target for ${modelType}`);
+        }
+      } catch (err) {
+        if (debug) console.warn(`[mlx] skip ${full}: ${(err as Error).message}`);
+      }
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    const full = join(modelsDir, entry.name);
+
+    let modelType: ModelType;
+    try {
+      modelType = await detectModelType(full);
+    } catch (err) {
+      if (debug) console.warn(`[mlx] skip ${full}: ${(err as Error).message}`);
+      continue;
+    }
+
+    const inventory = await modelFileInventory(full);
+    const hasModelWeights = requiresGgufAssets(modelType) ? inventory.hasPrimarySafetensors : inventory.hasSafetensors;
+    if (requiresGgufAssets(modelType) && !hasModelWeights && inventory.targetGgufs.length > 0) {
+      if (!(await hasGgufAssets(full))) {
+        if (debug)
+          console.warn(`[mlx] skip ${full}: native ${modelType} GGUF requires sibling config.json and tokenizer.json`);
+        continue;
+      }
+      for (const gguf of inventory.targetGgufs) {
+        const path = join(full, gguf);
+        try {
+          if (!matchesGgufFamily(path, modelType)) continue;
+          await append(ggufModelName(gguf), path, full, modelType, entry.name);
+        } catch (err) {
+          if (debug) console.warn(`[mlx] skip ${path}: ${(err as Error).message}`);
+        }
+      }
+      continue;
+    }
+    const { xlGgufs } = inventory;
+    if (xlGgufs.length > 0 && !inventory.hasPrimarySafetensors) {
+      if (modelType !== 'qwen3_5') {
+        if (debug) {
+          console.warn(`[mlx] skip ${full}: direct XL GGUF loading is not supported for ${modelType}`);
+        }
+        continue;
+      }
+      for (const gguf of xlGgufs) {
+        const path = join(full, gguf);
+        try {
+          if (matchesGgufFamily(path, modelType)) await append(ggufModelName(gguf), path, full, modelType, entry.name);
+        } catch (err) {
+          if (debug) console.warn(`[mlx] skip ${path}: ${(err as Error).message}`);
+        }
+      }
+      continue;
+    }
+
+    // Present each supported GGUF variant separately in the picker. Keep
+    // converted model directories discoverable when they retain
+    // an imatrix/source GGUF beside their actual SafeTensors weights.
+    if (inventory.hasGguf && !hasModelWeights) {
+      if (debug) console.warn(`[mlx] skip ${full}: no supported direct GGUF target`);
+      continue;
+    }
+
+    await append(basename(full), full, full, modelType, entry.name);
+  }
+
+  out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return out;
+}