offgrid-ai 0.9.5 → 0.10.0

package/src/hardware.mjs

@@ -0,0 +1,49 @@
+// Hardware detection — pure functions, no side effects.
+// Ported from deprecated-offgrid-desktop/src/main/hardware.ts.
+//
+// This is the canonical source for hardware facts the model-serving logic
+// needs: recommendations, onboarding, MLX context sizing, disk-space guards,
+// and memory estimation.
+
+import { totalmem } from "node:os";
+import { statfsSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Detect system hardware via the Node.js `os` module.
+ * Pure function — no side effects, trivially testable.
+ */
+export function detectHardware() {
+  return {
+    totalRamBytes: totalmem(),
+    platform: process.platform,
+    arch: process.arch,
+  };
+}
+
+/** Installed RAM in GB (integer). */
+export function installedRamGB() {
+  return Math.round(totalmem() / (1024 ** 3));
+}
+
+/**
+ * Get available disk space for a directory (in bytes).
+ *
+ * If the directory doesn't exist yet, walks up to the nearest existing parent
+ * directory. Returns a very large number if the check fails (so we don't block
+ * a download unnecessarily).
+ */
+export function getFreeDiskBytes(dir) {
+  try {
+    let checkDir = dir;
+    while (!existsSync(checkDir)) {
+      const parent = dirname(checkDir);
+      if (parent === checkDir) break; // reached root
+      checkDir = parent;
+    }
+    const stats = statfsSync(checkDir);
+    return stats.bavail * stats.bsize;
+  } catch {
+    return Number.MAX_SAFE_INTEGER;
+  }
+}

package/src/harness-pi.mjs

@@ -5,6 +5,18 @@ import { loadProfiles } from "./profiles.mjs";
 import { readJson, writeJson } from "./json.mjs";
 import pc from "picocolors";
 
+// ── Pi model id ─────────────────────────────────────────────────────────────
+
+/**
+ * The model id Pi must send in requests. mlx-vlm registers the loaded model
+ * with the full --model path as its API id (verified via /v1/models); sending
+ * the repo-id label instead makes mlx-vlm unload the local model and re-fetch
+ * the repo from HuggingFace. Other backends use the friendly modelAlias.
+ */
+export function piApiModelId(profile) {
+  return profile.backend === "mlx-vlm" ? profile.modelPath : profile.modelAlias;
+}
+
 // ── Sync Pi config ─────────────────────────────────────────────────────────
 
 export async function syncPiConfig(profile) {
@@ -30,26 +42,27 @@ export async function removeFromPiConfig(profile) {
   const provider = config.providers[profile.providerId];
   if (!provider?.models) return { cleaned: false, reason: `no ${profile.providerId} provider in Pi config` };
   const before = provider.models.length;
-  provider.models = provider.models.filter((m) => m.id !== profile.modelAlias);
+  const apiId = piApiModelId(profile);
+  provider.models = provider.models.filter((m) => m.id !== apiId);
   if (provider.models.length === 0) delete config.providers[profile.providerId];
   if (before > provider.models.length) {
     await writeJson(PI_CONFIG, config);
     return { cleaned: true, removed: before - provider.models.length };
   }
-  return { cleaned: false, reason: `${profile.modelAlias} not in Pi config` };
+  return { cleaned: false, reason: `${apiId} not in Pi config` };
 }
 
 // ── Check if Pi has the model ──────────────────────────────────────────────
 
 export async function hasPiModel(profile) {
   const config = await readJson(PI_CONFIG, null);
-  return Boolean(config?.providers?.[profile.providerId]?.models?.some?.((m) => m.id === profile.modelAlias));
+  return Boolean(config?.providers?.[profile.providerId]?.models?.some?.((m) => m.id === piApiModelId(profile)));
 }
 
 // ── Launch Pi ──────────────────────────────────────────────────────────────
 
 export async function launchPi(profile) {
-  const model = profile.harnesses?.pi?.model ?? `${profile.providerId}/${profile.modelAlias}`;
+  const model = `${profile.providerId}/${piApiModelId(profile)}`;
   console.log(pc.bold(`[pi] pi --model ${model}`));
   await runForeground("pi", ["--model", model]);
 }
@@ -88,7 +101,7 @@ function piModelConfig(profile) {
   const compat = modelCompat(profile);
   const reasoning = modelReasoning(profile);
   return {
-    id: profile.modelAlias,
+    id: piApiModelId(profile),
     name: profile.label,
     input: modelInput(profile),
     ...(reasoning === undefined ? {} : { reasoning }),
@@ -99,7 +112,9 @@ function piModelConfig(profile) {
 }
 
 function modelInput(profile) {
-  return profile.mmprojPath && existsSync(profile.mmprojPath) ? ["text", "image"] : ["text"];
+  if (profile.mmprojPath && existsSync(profile.mmprojPath)) return ["text", "image"];
+  if (profile.capabilities?.vision) return ["text", "image"];
+  return ["text"];
 }
 
 function modelCompat(profile) {
@@ -119,15 +134,14 @@ function modelReasoning(profile) {
 }
 
 function modelFamily(profile) {
-  return [profile.id, profile.label, profile.modelAlias, profile.modelPath, profile.ollamaModel, profile.omlxModel].filter(Boolean).join(" ").toLowerCase();
+  return [profile.id, profile.label, profile.modelAlias, profile.modelPath, profile.omlxModel].filter(Boolean).join(" ").toLowerCase();
 }
 
-function piApiKey(providerId) {
-  return providerId === "ollama" ? "ollama" : "none";
+function piApiKey() {
+  return "none";
 }
 
-function providerCompat(providerId) {
-  if (providerId === "ollama") return { supportsDeveloperRole: true, supportsReasoningEffort: false };
+function providerCompat() {
   return { supportsDeveloperRole: false, supportsReasoningEffort: false };
 }
 

package/src/huggingface.mjs

@@ -0,0 +1,209 @@
+// HuggingFace model download helpers.
+// Uses the Python huggingface_hub package (the standard, maintained downloader)
+// to download models into the standard HF cache directory.
+// Downloads go to ~/.cache/huggingface/hub, NOT a custom offgrid-ai folder.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join, dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { HF_HUB_DIR } from "./config.mjs";
+
+const execFileAsync = promisify(execFile);
+
+const HF_DOWNLOAD_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "..", "resources", "hf-download.py");
+
+/** Check whether python3 + huggingface_hub is available. */
+export async function hasHuggingfaceHub() {
+  try {
+    const { stdout } = await execFileAsync("python3", ["-c", "import huggingface_hub; print(huggingface_hub.__version__)"]);
+    return Boolean(stdout.trim());
+  } catch {
+    return false;
+  }
+}
+
+/** Parse a HuggingFace reference (URL, repo/filename, or repo ID). */
+export function parseHfRef(input) {
+  const trimmed = input.trim();
+
+  if (trimmed.startsWith("https://huggingface.co/")) {
+    const url = new URL(trimmed);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    const resolveIdx = pathParts.indexOf("resolve");
+    if (resolveIdx > 0 && pathParts[resolveIdx + 1] === "main") {
+      return {
+        repo: pathParts.slice(0, resolveIdx).join("/"),
+        filename: pathParts.slice(resolveIdx + 2).join("/"),
+      };
+    }
+    if (pathParts.length >= 2) {
+      return {
+        repo: pathParts.slice(0, 2).join("/"),
+        filename: pathParts.length > 2 ? pathParts.slice(2).join("/") : undefined,
+      };
+    }
+    throw new Error(`Invalid HuggingFace URL: ${input}`);
+  }
+
+  const parts = trimmed.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(`Invalid HuggingFace reference: "${input}". Expected at least org/name.`);
+  }
+  return {
+    repo: parts.slice(0, 2).join("/"),
+    filename: parts.length > 2 ? parts.slice(2).join("/") : undefined,
+  };
+}
+
+/** Resolve file metadata for a GGUF file from the HF tree API. */
+export async function resolveGgufFile(ref, { fetchImpl = globalThis.fetch } = {}) {
+  const { repo, filename } = parseHfRef(ref);
+  const tree = await getHfTree(repo, { fetchImpl });
+  const entry = tree.find((f) => f.path === filename && f.type === "file");
+  if (!entry) throw new Error(`File '${filename}' not found in HuggingFace repo '${repo}'.`);
+  return {
+    repo,
+    filename,
+    url: `https://huggingface.co/${repo}/resolve/main/${filename}`,
+    sizeBytes: entry.lfs?.size ?? entry.size ?? 0,
+    sha256: entry.lfs?.oid ?? "",
+    relativePath: filename,
+  };
+}
+
+/** Resolve all model files in an MLX repo from the HF tree API. */
+export async function resolveMlxRepo(repo, { fetchImpl = globalThis.fetch } = {}) {
+  const tree = await getHfTree(repo, { fetchImpl });
+  const modelFiles = tree.filter(
+    (f) => f.type === "file" && !f.path.startsWith(".") && f.path !== ".gitattributes" && f.path !== "README.md",
+  );
+  return modelFiles.map((f) => ({
+    repo,
+    filename: f.path,
+    url: `https://huggingface.co/${repo}/resolve/main/${f.path}`,
+    sizeBytes: f.lfs?.size ?? f.size ?? 0,
+    sha256: f.lfs?.oid ?? "",
+    relativePath: f.path,
+  }));
+}
+
+async function getHfTree(repo, { branch = "main", fetchImpl = globalThis.fetch } = {}) {
+  const url = `https://huggingface.co/api/models/${repo}/tree/${branch}?recursive=true`;
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(10000) });
+  if (!response.ok) throw new Error(`HuggingFace API error: HTTP ${response.status} for ${repo}`);
+  return await response.json();
+}
+
+/** Resolve a user-provided HF reference into a download plan. */
+export async function resolveHfDownload(input, { fetchImpl = globalThis.fetch } = {}) {
+  const { repo, filename } = parseHfRef(input);
+
+  if (filename && filename.endsWith(".gguf")) {
+    const file = await resolveGgufFile(`${repo}/${filename}`, { fetchImpl });
+    return {
+      id: repo.split("/").pop() ?? repo,
+      repo,
+      format: "gguf",
+      files: [file],
+      totalSizeBytes: file.sizeBytes,
+    };
+  }
+
+  const tree = await getHfTree(repo, { fetchImpl });
+  const ggufFiles = tree.filter((f) => f.type === "file" && f.path.endsWith(".gguf"));
+  if (ggufFiles.length > 0) {
+    const file = ggufFiles[0];
+    const resolved = await resolveGgufFile(`${repo}/${file.path}`, { fetchImpl });
+    return {
+      id: repo.split("/").pop() ?? repo,
+      repo,
+      format: "gguf",
+      files: [resolved],
+      totalSizeBytes: resolved.sizeBytes,
+    };
+  }
+
+  const files = await resolveMlxRepo(repo, { fetchImpl });
+  return {
+    id: repo.split("/").pop() ?? repo,
+    repo,
+    format: "mlx",
+    files,
+    totalSizeBytes: files.reduce((sum, f) => sum + f.sizeBytes, 0),
+  };
+}
+
+/**
+ * Download a resolved model into the HF hub cache.
+ * @param {object} model - from resolveHfDownload
+ * @param {object} options
+ * @param {function} options.onProgress - ({ downloadedBytes, totalBytes, percentage, file }) => void
+ * @returns {Promise<{ localDir: string, format: string }>}
+ */
+export async function downloadToHfCache(model, options = {}) {
+  await mkdir(HF_HUB_DIR, { recursive: true });
+
+  const script = HF_DOWNLOAD_SCRIPT;
+  const args = ["--repo", model.repo, "--cache-dir", HF_HUB_DIR];
+  if (model.format === "gguf") {
+    args.push("--file", model.files[0].filename);
+  }
+
+  const onProgress = options.onProgress ?? (() => {});
+
+  return new Promise((resolve, reject) => {
+    const child = execFile("python3", [script, ...args], { env: process.env });
+
+    let stdoutBuf = "";
+    let downloadedBytes = 0;
+    let currentFile = null;
+
+    // huggingface_hub streams NDJSON progress events to stdout, one per line.
+    // Buffer and split on complete newlines so an event split across chunk
+    // boundaries isn't silently dropped.
+    const handleLine = (line) => {
+      if (!line) return;
+      try {
+        const event = JSON.parse(line);
+        if (event.type === "progress") {
+          downloadedBytes = event.downloadedBytes ?? downloadedBytes;
+          currentFile = event.file ?? currentFile;
+          onProgress({
+            downloadedBytes,
+            totalBytes: model.totalSizeBytes,
+            percentage: Math.min(100, Math.round((downloadedBytes / model.totalSizeBytes) * 100)),
+            file: currentFile,
+          });
+        } else if (event.type === "complete") {
+          resolve({ localDir: event.localDir, format: model.format });
+        } else if (event.type === "error") {
+          reject(new Error(event.message));
+        }
+      } catch {
+        // Ignore non-JSON output (progress bars, etc.)
+      }
+    };
+
+    child.stdout?.on("data", (chunk) => {
+      stdoutBuf += String(chunk);
+      let nl;
+      while ((nl = stdoutBuf.indexOf("\n")) !== -1) {
+        handleLine(stdoutBuf.slice(0, nl));
+        stdoutBuf = stdoutBuf.slice(nl + 1);
+      }
+    });
+
+    child.stderr?.on("data", () => {
+      // huggingface_hub prints progress bars to stderr; ignore.
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      // Flush any final line that lacked a trailing newline.
+      if (stdoutBuf.trim()) handleLine(stdoutBuf.trim());
+      if (code !== 0) reject(new Error(`Download failed with exit code ${code}`));
+    });
+  });
+}

package/src/managed.mjs

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { BACKENDS } from "./backends.mjs";
 import { commandExists } from "./exec.mjs";
 
-export const MANAGED_BACKEND_IDS = ["ollama", "omlx"];
+export const MANAGED_BACKEND_IDS = ["omlx"];
 
 export async function scanManagedModels() {
   const results = [];
@@ -22,10 +22,6 @@ export function hasLmStudioInstalled() {
   return existsSync("/Applications/LM Studio.app");
 }
 
-export function hasOllamaInstalled() {
-  return commandExists("ollama");
-}
-
 export function hasOmlxInstalled() {
   return commandExists("omlx");
 }

package/src/mlx-discovery.mjs

@@ -0,0 +1,290 @@
+// MLX model discovery + metadata — scans configured model directories for MLX
+// model directories and parses their config.json.
+// Ported from deprecated-offgrid-desktop/src/main/model-discovery.ts +
+// mlx-metadata.ts (MLX subset only).
+//
+// This runs ALONGSIDE offgrid-ai's existing GGUF scan (scan.mjs scanGgufModels)
+// — it does not replace it. The picker (main.mjs) will merge GGUF + MLX lists.
+//
+// An MLX model directory is one containing config.json + one or more
+// *.safetensors files. HuggingFace Hub cache layout (models--org--name) is
+// detected and scanned specially.
+
+import { readdir, stat, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { getModelScanDirs } from "./config.mjs";
+import { inferSourceLabel, MIN_MODEL_SIZE_BYTES, EMBEDDING_MODEL_TYPES } from "./discovery-shared.mjs";
+
+// ── Folder → backend mapping ──────────────────────────────────────────────
+// The oMLX folder is oMLX-exclusive: models there are served by the oMLX
+// managed backend, NOT by mlx-vlm. Every OTHER scan dir is format-based
+// (GGUF → llama.cpp, MLX → mlx-vlm). So mlx-vlm scans all configured dirs
+// EXCEPT the oMLX folder.
+const OMLX_MODELS_DIR = join(homedir(), ".omlx", "models");
+function isOmlxFolder(p) {
+  return p === OMLX_MODELS_DIR || p.startsWith(OMLX_MODELS_DIR + "/");
+}
+
+// ── MLX directory detection ───────────────────────────────────────────────
+
+/** True if dir contains config.json + at least one .safetensors file. */
+async function isMlxModelDir(dir) {
+  if (!existsSync(join(dir, "config.json"))) return false;
+  try {
+    const entries = await readdir(dir);
+    return entries.some((f) => f.endsWith(".safetensors"));
+  } catch {
+    return false;
+  }
+}
+
+/** Sum the size of all .safetensors files in an MLX model dir (bytes). */
+async function getMlxDirSizeBytes(dir) {
+  try {
+    const entries = await readdir(dir);
+    const sizes = await Promise.all(
+      entries.filter((f) => f.endsWith(".safetensors")).map(async (f) => {
+        const s = await stat(join(dir, f));
+        return s.size;
+      }),
+    );
+    return sizes.reduce((a, b) => a + b, 0);
+  } catch {
+    return 0;
+  }
+}
+
+// ── Recursive MLX scanner ─────────────────────────────────────────────────
+
+/**
+ * Recursively scan a directory for MLX model directories.
+ * Searches up to maxDepth levels deep. Does NOT collect GGUF (that's scan.mjs).
+ */
+async function scanDirRecursiveForMlx(rootDir, sourceLabel, maxDepth = 3) {
+  if (!existsSync(rootDir)) return [];
+  const models = [];
+
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    // Is this directory itself an MLX model dir? (don't recurse into it)
+    if (depth > 0 && await isMlxModelDir(dir)) {
+      const sizeBytes = await getMlxDirSizeBytes(dir);
+      if (sizeBytes < MIN_MODEL_SIZE_BYTES) return;
+      if (await isEmbeddingMlxModel(join(dir, "config.json"))) return;
+      models.push(makeMlxModel(dir, basename(dir), sizeBytes, sourceLabel, rootDir));
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "README.md" || entry.name === ".gitattributes") continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (await isMlxModelDir(fullPath)) {
+          const sizeBytes = await getMlxDirSizeBytes(fullPath);
+          if (sizeBytes < MIN_MODEL_SIZE_BYTES) continue;
+          if (await isEmbeddingMlxModel(join(fullPath, "config.json"))) continue;
+          models.push(makeMlxModel(fullPath, entry.name, sizeBytes, sourceLabel, rootDir));
+        } else {
+          await walk(fullPath, depth + 1);
+        }
+      }
+    }
+  }
+
+  await walk(rootDir, 0);
+  return models;
+}
+
+// ── HuggingFace Hub layout ────────────────────────────────────────────────
+
+/** True if dir looks like an HF Hub cache (has models--* subdirs). */
+async function looksLikeHfHub(dir) {
+  if (!existsSync(dir)) return false;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.some((e) => e.isDirectory() && e.name.startsWith("models--"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Scan an HF Hub cache dir for MLX model dirs.
+ * HF layout: models--org--name/snapshots/hash/files
+ */
+async function scanHfHubForMlx(dir, sourceLabel) {
+  if (!existsSync(dir)) return [];
+  const models = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith("models--")) continue;
+      const parts = entry.name.slice("models--".length).split("--");
+      const label = parts.join("/");
+      const snapshotsDir = join(dir, entry.name, "snapshots");
+      if (!existsSync(snapshotsDir)) continue;
+      const snapshots = await readdir(snapshotsDir, { withFileTypes: true });
+      // Follow symlinks (HF hub uses them; test imports use them too). A model
+      // dir can have several snapshots — some incomplete/empty. Check EACH
+      // snapshot and use the first that is a valid MLX model dir, rather than
+      // giving up on the whole model if the first snapshot happens to be empty.
+      const candidates = snapshots.filter((s) => s.isDirectory() || s.isSymbolicLink());
+      let snapshotPath = null;
+      for (const snap of candidates) {
+        const sp = join(snapshotsDir, snap.name);
+        const st = await stat(sp).catch(() => null);
+        if (st?.isDirectory() && await isMlxModelDir(sp)) { snapshotPath = sp; break; }
+      }
+
+      if (!snapshotPath) continue;
+      const sizeBytes = await getMlxDirSizeBytes(snapshotPath);
+      if (sizeBytes < MIN_MODEL_SIZE_BYTES) continue;
+      if (await isEmbeddingMlxModel(join(snapshotPath, "config.json"))) continue;
+      models.push({
+        id: `${sourceLabel}:${entry.name}`,
+        label,
+        path: snapshotPath,
+        filePath: snapshotPath,
+        sizeBytes,
+        backend: "mlx-vlm",
+        format: "mlx",
+        source: sourceLabel,
+      });
+    }
+  } catch {
+    // Can't read — return what we have.
+  }
+  return models;
+}
+
+// ── Embedding model filtering for MLX ─────────────────────────────────────
+
+async function isEmbeddingMlxModel(configPath) {
+  if (!existsSync(configPath)) return false;
+  try {
+    const config = JSON.parse(await readFile(configPath, "utf-8"));
+    const textConfig = config.text_config ?? config;
+    const modelType = String(textConfig.model_type ?? "").toLowerCase();
+    if (EMBEDDING_MODEL_TYPES.has(modelType)) return true;
+    const arch = Array.isArray(config.architectures) ? config.architectures[0] : "";
+    const lowerArch = String(arch).toLowerCase();
+    return EMBEDDING_MODEL_TYPES.has(lowerArch) || lowerArch.includes("bert");
+  } catch {
+    return false;
+  }
+}
+
+// ── MLX model entry builder ───────────────────────────────────────────────
+
+function makeMlxModel(dir, label, sizeBytes, sourceLabel, rootDir) {
+  return {
+    id: `${sourceLabel}:${dir.replace(rootDir + "/", "")}`,
+    label,
+    path: dir,
+    filePath: dir,
+    sizeBytes,
+    backend: "mlx-vlm",
+    format: "mlx",
+    source: sourceLabel,
+  };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Discover all MLX models across the configured scan directories.
+ * Reads scan dirs from config.mjs getModelScanDirs() — same paths GGUF uses
+ * (LM Studio, HF hub, user-added). Returns a flat, deduplicated list.
+ */
+export async function scanMlxModels(dirs) {
+  // mlx-vlm scans every configured dir EXCEPT the oMLX folder (oMLX-exclusive).
+  const scanDirs = (dirs ?? await getModelScanDirs()).filter((d) => !isOmlxFolder(d));
+  const results = await Promise.all(
+    scanDirs.map(async (dir) => {
+      const label = inferSourceLabel(dir);
+      if (await looksLikeHfHub(dir)) return scanHfHubForMlx(dir, label);
+      return scanDirRecursiveForMlx(dir, label);
+    }),
+  );
+  const all = results.flat();
+  // Deduplicate by filePath (same model may appear in multiple paths).
+  const seen = new Set();
+  return all.filter((m) => {
+    if (seen.has(m.filePath)) return false;
+    seen.add(m.filePath);
+    return true;
+  });
+}
+
+// ── MLX capability detection ─────────────────────────────────────────────
+
+/**
+ * Detect MLX model capabilities from its config.json.
+ * Returns { architecture, thinking, vision, contextLength }.
+ */
+export async function detectMlxCapabilities(modelDir) {
+  const configPath = join(modelDir, "config.json");
+  if (!existsSync(configPath)) return { thinking: false, vision: false, contextLength: null, architecture: null };
+  try {
+    const config = JSON.parse(await readFile(configPath, "utf-8"));
+    return detectMlxCapabilitiesFromConfig(config, modelDir);
+  } catch {
+    return { thinking: false, vision: false, contextLength: null, architecture: null };
+  }
+}
+
+export function detectMlxCapabilitiesFromConfig(config, modelDir) {
+  const textConfig = config.text_config ?? config;
+  const rawName = config._name_or_path ?? basename(modelDir ?? "");
+  const name = String(rawName).toLowerCase();
+  const label = String(rawName);
+
+  const modelType = String(config.model_type ?? "").toLowerCase();
+  const textModelType = String(textConfig.model_type ?? "").toLowerCase();
+
+  const vision = Boolean(
+    config.vision_config ||
+    config.image_token_id != null ||
+    config.video_token_id != null ||
+    config.vision_start_token_id != null ||
+    modelType.includes("vl") ||
+    modelType.includes("vision") ||
+    textModelType.includes("vl") ||
+    textModelType.includes("vision")
+  );
+
+  const thinking = /qwen3|gemma-4|gemma4|deepseek-r[12]/i.test(name + " " + label);
+
+  const architectures = Array.isArray(config.architectures) ? config.architectures : [];
+  const architecture = architectures[0] ?? null;
+
+  const candidates = [
+    textConfig.max_position_embeddings,
+    textConfig.sliding_window,
+    config.max_position_embeddings,
+    config.sliding_window,
+  ].filter((v) => typeof v === "number" && v > 0);
+  const contextLength = candidates.length > 0 ? Math.max(...candidates) : null;
+
+  return { thinking, vision, contextLength, architecture };
+}
+
+/**
+ * Pick a sensible default context length for an MLX model, capping by RAM.
+ */
+export function defaultMlxContextLength(trainedCtx, ramGb) {
+  if (!trainedCtx || trainedCtx <= 0) return 8192;
+  if (ramGb < 12) return Math.min(trainedCtx, 4096);
+  if (ramGb < 16) return Math.min(trainedCtx, 8192);
+  if (ramGb < 32) return Math.min(trainedCtx, 16384);
+  return trainedCtx;
+}