mlx-bun 0.5.0 → 1.0.0

package/src/cli/memory.ts

@@ -0,0 +1,36 @@
+import { fileURLToPath } from "node:url";
+import { runModuleMemory, vaultRoot, memoryManifest, type MemoryDependencies, type MemoryCommandArgs as CommandArgs } from "../modules";
+import { verbHelp } from "@mlx-bun/app-services";
+import { executablePath } from "../jobs/executable";
+import { userHome } from "../storage/paths";
+import { createInProcessMemoryClient } from "./memory-engine";
+import { banner, boxLines, renderHelp, step, style, gradient } from "./terminal";
+import pkg from "../../package.json" with { type: "json" };
+export type { MemoryDependencies } from "../modules";
+
+/** The app's executable, terminal and task-model adapters; memory policy belongs to its module. */
+export function defaultMemoryDependencies(): MemoryDependencies {
+  const entry = fileURLToPath(new URL("./main.ts", import.meta.url));
+  return {
+    log: console.log, error: console.error, banner: () => banner(pkg.version),
+    box: lines => { for (const line of boxLines(lines)) console.log(line); }, step, style: { ...style, gradient },
+    help: () => renderHelp(verbHelp("mlx-bun", memoryManifest.verbs[0])), vault: vaultRoot(), home: userHome(),
+    program: entry.includes("$bunfs") ? [executablePath] : [executablePath, entry],
+    taskModel: () => createInProcessMemoryClient(),
+    async open(args) { return await Bun.spawn(["open", ...args], { stdout: "ignore", stderr: "ignore" }).exited; },
+    async ask(question, fallback) {
+      if (!process.stdin.isTTY) return fallback;
+      const { createInterface } = await import("node:readline/promises");
+      const reader = createInterface({ input: process.stdin, output: process.stdout });
+      try { return (await reader.question(question)).trim() || fallback; } finally { reader.close(); }
+    },
+  };
+}
+export async function runMemory(args: CommandArgs, supplied: Partial<MemoryDependencies> = {}): Promise<void> {
+  const defaults = defaultMemoryDependencies();
+  const deps = { ...defaults, ...supplied };
+  // Injected output callbacks also capture the existing boxed presentation in the CLI tests.
+  if (supplied.log && !supplied.box) deps.box = lines => { for (const line of boxLines(lines)) supplied.log!(line); };
+  const code = await runModuleMemory(args, deps);
+  if (code) process.exitCode = code;
+}

package/src/cli/mlx-lm-aliases.ts

@@ -0,0 +1,309 @@
+// `mlx-bun.<cmd>`: mlx-lm's console commands (mlx_lm.<cmd>) under mlx-bun's own
+// names. Each alias runs the matching mlx-bun verb with mlx_lm's argument
+// spellings translated; the verb's own options stay accepted, so an alias is a
+// superset of the mlx_lm command. Defaults, output locations (~/.mlx-bun) and
+// behavior are the verb's; an explicit path behaves exactly as in mlx-lm.
+// Flags mlx-bun cannot honor exit with an error naming the mlx_lm flag.
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { checkPositionals, commandOptions, help, isCommand, type CommandArgs } from "./args";
+
+type Value = string | boolean;
+export type AliasValues = Record<string, Value | undefined>;
+
+interface MlxLmFlag {
+  kind: "string" | "boolean" | "list";
+  /** Single-dash spelling, without the dash (`p` for -p, `qa` for -qa). */
+  short?: string;
+  /** The verb's option that receives the value (default: the same name). */
+  to?: string;
+  /** Accepted with no effect; the reason is shown in help. */
+  ignored?: string;
+  /** Not supported; the reason follows the error. */
+  unsupported?: string;
+  /** Custom translation of the parsed value into the verb's values. */
+  set?(value: Value | string[], values: AliasValues): void;
+}
+interface Alias {
+  verb: string;
+  /** mlx_lm's flags that need translation, refusal, or acceptance; every other mlx_lm flag is the verb's own option. */
+  flags: Record<string, MlxLmFlag>;
+  /** Final adjustments once every flag (and the config file) is applied. */
+  finish?(values: AliasValues, given: ReadonlySet<string>): void;
+}
+
+const no = (kind: MlxLmFlag["kind"], unsupported: string, extra: Partial<MlxLmFlag> = {}): MlxLmFlag => ({ kind, unsupported, ...extra });
+const trustRemoteCode: MlxLmFlag = { kind: "boolean", ignored: "mlx-bun never executes code from a model repository" };
+
+const ONE_SHOT = "mlx-bun's one-shot generate has no such option";
+const GENERATE: Alias = {
+  verb: "generate",
+  flags: {
+    model: { kind: "string", to: "query" },
+    "trust-remote-code": trustRemoteCode,
+    prompt: { kind: "string", short: "p", set: (value, values) => {
+      // mlx_lm.generate reads the escapes \n and \t as characters; `-` (stdin) passes through.
+      values.prompt = String(value).replaceAll("\\n", "\n").replaceAll("\\t", "\t");
+    } },
+    "max-tokens": { kind: "string", short: "m" },
+    "ignore-chat-template": { kind: "boolean", to: "raw" },
+    verbose: { kind: "string", ignored: "mlx-bun prints only the generated text" },
+    "kv-bits": { kind: "string", set: (value, values) => {
+      if (value !== "4" && value !== "8") throw new Error(`--kv-bits ${value}: mlx-bun's affine KV cache supports 4 or 8 bits`);
+      values["kv-quant"] = value;
+      // mlx_lm starts quantizing at token 5000 unless told otherwise; mlx-bun's own --kv-quant starts at 0.
+      values["quantized-kv-start"] ??= "5000";
+    } },
+    "kv-group-size": { kind: "string", set: value => {
+      if (value !== "64") throw new Error(`--kv-group-size ${value}: mlx-bun's affine KV cache uses group size 64`);
+    } },
+    "extra-eos-token": no("list", "the model's own end-of-sequence tokens stop generation"),
+    "prefill-response": no("string", ONE_SHOT),
+    "use-default-chat-template": no("boolean", "the model's own chat template is always used"),
+    "chat-template-config": no("string", "chat template arguments are not configurable here"),
+    "max-kv-size": no("string", "mlx-bun has no rotating KV size cap flag"),
+    "prompt-cache-file": no("string", "saved prompt caches are not supported; `serve` caches prompts itself"),
+    "quantize-activations": no("boolean", "activation quantization is not supported", { short: "qa" }),
+    "draft-model": no("string", "speculative decoding runs in `serve` (--draft-model)"),
+    "num-draft-tokens": no("string", "speculative decoding runs in `serve` (--num-draft-tokens)"),
+  },
+};
+
+const SERVE: Alias = {
+  verb: "serve",
+  flags: {
+    "trust-remote-code": trustRemoteCode,
+    "allowed-origins": no("string", "CORS origins are not configurable"),
+    "log-level": no("string", "the server has no log-level switch"),
+    "chat-template": no("string", "the model's own chat template is always used"),
+    "use-default-chat-template": no("boolean", "the model's own chat template is always used"),
+    "chat-template-args": no("string", "send chat_template_kwargs with the request instead"),
+    "min-p": no("string", "send min_p with the request instead"),
+    "prompt-concurrency": no("string", "the scheduler decides how prompts join; --batch sets the capacity"),
+    "prefill-step-size": no("string", "prefill chunking is not configurable"),
+    "prompt-cache-size": no("string", "use --prompt-cache (GiB)"),
+    "prompt-cache-bytes": no("string", "use --prompt-cache (GiB)"),
+    pipeline: no("boolean", "distributed pipelining is not supported"),
+  },
+  // mlx_lm.server is headless; the web app is mlx-bun's addition, opened only on request.
+  finish: (values, given) => { if (!given.has("no-open")) values["no-open"] = true; },
+};
+
+const CONVERT: Alias = { verb: "convert", flags: { "trust-remote-code": trustRemoteCode } };
+const FUSE: Alias = { verb: "fuse", flags: {} };
+const UPLOAD: Alias = { verb: "upload", flags: {} };
+
+const LORA_UNSUPPORTED = (what: string) => `${what} is not supported by mlx-bun's LoRA trainer`;
+const LORA: Alias = {
+  verb: "train",
+  flags: {
+    model: { kind: "string", to: "query" },
+    train: { kind: "boolean" },
+    test: no("boolean", "test-set evaluation is not supported"),
+    "test-batches": no("string", "test-set evaluation is not supported"),
+    "fine-tune-type": { kind: "string", set: value => {
+      if (value === "dora" || value === "full") throw new Error(`--fine-tune-type ${value}: ${LORA_UNSUPPORTED(value)}; only lora`);
+      if (value !== "lora") throw new Error(`--fine-tune-type: invalid choice: '${value}' (choose from lora, dora, full)`);
+    } },
+    optimizer: { kind: "string", set: (value, values) => {
+      // mlx.optimizers.Adam has no weight decay; AdamW (mlx-bun's optimizer) defaults to 0.01.
+      if (value === "adam") values["optimizer-adam"] = true;
+      else if (value !== "adamw") throw new Error(`--optimizer ${value}: only adam and adamw are supported`);
+    } },
+    "mask-prompt": { kind: "boolean", ignored: "mlx-bun's SFT always masks the prompt (loss on the response only)" },
+    "batch-size": { kind: "string", to: "batch" },
+    "val-batches": { kind: "string", set: (value, values) => { values["val-batches"] = String(value); } },
+    "learning-rate": { kind: "string", to: "lr" },
+    "grad-accumulation-steps": { kind: "string", to: "grad-accum" },
+    "resume-adapter-file": { kind: "string", set: (value, values) => {
+      // mlx-bun resumes from an adapter directory; mlx-lm names the weights file in it.
+      const path = String(value);
+      values.resume = path.endsWith(".safetensors") ? dirname(path) : path;
+    } },
+    "adapter-path": { kind: "string", to: "adapter" },
+    "max-seq-length": { kind: "string", to: "seq" },
+    config: { kind: "string", short: "c", set: (value, values) => { values["config-file"] = String(value); } },
+    "clear-cache-threshold": no("string", "the allocator cache policy is not configurable"),
+    "report-to": no("string", "experiment reporting is not supported"),
+    "project-name": no("string", "experiment reporting is not supported"),
+  },
+  finish: (values, given) => {
+    if (values.method === undefined) values.method = "sft"; // mlx_lm.lora is supervised fine-tuning
+    if (values["optimizer-adam"] && !given.has("weight-decay")) values["weight-decay"] = "0";
+    delete values["optimizer-adam"];
+    const batches = values["val-batches"];
+    if (typeof batches === "string") {
+      // mlx-lm counts validation batches; mlx-bun caps validation examples.
+      const n = Number(batches), size = Number(values.batch ?? 1);
+      values["val-size"] = String(n < 0 ? Number.MAX_SAFE_INTEGER : n * size);
+      delete values["val-batches"];
+    }
+    if (values.train !== true) throw new Error("Must provide --train (mlx-bun's LoRA trainer has no --test-only mode)");
+    delete values.train;
+  },
+};
+
+/** mlx_lm.lora's YAML config keys that are not plain flag spellings. */
+const LORA_CONFIG_UNSUPPORTED = ["lr_schedule"];
+
+export const ALIASES: Record<string, Alias> = { server: SERVE, generate: GENERATE, convert: CONVERT, fuse: FUSE, lora: LORA, upload: UPLOAD };
+
+/** mlx-lm's other console scripts (0.31.3): no mlx-bun counterpart, so no alias. */
+export const ALIAS_GAPS: Record<string, string> = {
+  chat: "no interactive terminal chat; use the web app (`mlx-bun`) or `mlx-bun.server`",
+  benchmark: "no benchmark verb; the repository's scripts/bench-serve.ts measures a running server",
+  cache_prompt: "no saved prompt-cache files; `serve` keeps its own prompt cache",
+  evaluate: "no lm-evaluation-harness runner; the repository's scripts/eval-serve.ts scores a running server",
+  perplexity: "use `mlx-bun perplexity <model> --data-path <local file>` (main's verb, mlx_lm.perplexity's method over a local file)",
+  manage: "no cache-management verb with mlx_lm.manage's semantics; see `mlx-bun ls` and `mlx-bun gc`",
+  share: "no distributed file sharing",
+  awq: "no AWQ quantization; `mlx-bun convert --target-bpw` is the mixed-precision path",
+  dwq: "no DWQ quantization; `mlx-bun convert --target-bpw` is the mixed-precision path",
+  dynamic_quant: "no dynamic quantization; `mlx-bun convert --target-bpw` is the mixed-precision path",
+  gptq: "no GPTQ quantization; `mlx-bun convert --target-bpw` is the mixed-precision path",
+};
+
+const PREFIX = "mlx-bun.";
+
+/** The alias an invocation asked for, from the name the command was started as:
+ * the executable's own name in the standalone binary, the launcher file's name
+ * (bin/mlx-bun.<cmd>.mjs) when run from source. Null for plain `mlx-bun`. */
+export function invokedAlias(input: { argv0?: string; argv1?: string; main?: string } = {}): string | null {
+  const main = input.main ?? Bun.main;
+  const name = basename(main.startsWith("/$bunfs/") ? input.argv0 ?? process.argv0 : input.argv1 ?? process.argv[1] ?? "").replace(/\.mjs$/, "");
+  return name.startsWith(PREFIX) ? name.slice(PREFIX.length) : null;
+}
+
+const NEGATIVE_NUMBER = /^-(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+const looksLikeFlag = (token: string) => token.startsWith("-") && token !== "-" && !NEGATIVE_NUMBER.test(token);
+
+export type AliasResult = { help: string } | { command: string; parsed: CommandArgs };
+
+function requireAlias(name: string): Alias {
+  const alias = Object.hasOwn(ALIASES, name) ? ALIASES[name] : undefined;
+  if (alias) return alias;
+  const gap = Object.hasOwn(ALIAS_GAPS, name) ? ALIAS_GAPS[name] : undefined;
+  throw new Error(gap ? `${PREFIX}${name}: mlx_lm.${name} has no mlx-bun counterpart (${gap})`
+    : `${PREFIX}${name}: unknown mlx-lm alias; available: ${Object.keys(ALIASES).map(key => PREFIX + key).join(", ")}`);
+}
+
+/** Translate `mlx-bun.<name> <argv>`: mlx_lm's spellings first, then the verb's own options. */
+export function translateAlias(name: string, argv: string[], readConfig: (path: string) => unknown = readYaml): AliasResult {
+  const alias = requireAlias(name), tag = `${PREFIX}${name}`;
+  if (argv.includes("--help") || argv.includes("-h")) return { help: aliasHelp(name) };
+  const own = commandOptions(alias.verb);
+  const lookup = (token: string): { key: string; flag: MlxLmFlag } | undefined => {
+    const long = token.startsWith("--");
+    const bare = token.slice(long ? 2 : 1);
+    if (long) {
+      const mapped = alias.flags[bare];
+      if (mapped) return { key: bare, flag: mapped };
+      const option = own[bare];
+      return option ? { key: bare, flag: { kind: option.type } } : undefined;
+    }
+    for (const [key, flag] of Object.entries(alias.flags)) if (flag.short === bare) return { key, flag };
+    for (const [key, option] of Object.entries(own)) if (option.short === bare) return { key, flag: { kind: option.type } };
+    return undefined;
+  };
+
+  const values: AliasValues = {}, given = new Set<string>(), positionals: string[] = [];
+  /** A translation's own refusal reads as the alias's. */
+  const tagged = <T>(work: () => T): T => {
+    try { return work(); }
+    catch (error) { throw new Error(error instanceof Error && !error.message.startsWith(tag) ? `${tag}: ${error.message}` : String(error)); }
+  };
+  const apply = (key: string, flag: MlxLmFlag, value: Value | string[]) => {
+    if (flag.unsupported) throw new Error(`${tag}: --${key} is an mlx_lm.${name} option mlx-bun does not support: ${flag.unsupported}`);
+    given.add(flag.to ?? key);
+    if (flag.ignored) return;
+    if (flag.set) return tagged(() => flag.set!(value, values));
+    values[flag.to ?? key] = Array.isArray(value) ? value.join(" ") : value;
+  };
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index]!;
+    if (token === "--") { positionals.push(...argv.slice(index + 1)); break; }
+    if (!looksLikeFlag(token)) { positionals.push(token); continue; }
+    const equals = token.startsWith("--") ? token.indexOf("=") : -1;
+    const spelled = equals === -1 ? token : token.slice(0, equals);
+    const found = lookup(spelled);
+    if (!found) throw new Error(`${tag}: unrecognized argument: ${spelled}`);
+    const { key, flag } = found;
+    if (flag.kind === "boolean") {
+      if (equals !== -1) throw new Error(`${tag}: argument ${spelled}: ignored explicit argument '${token.slice(equals + 1)}'`);
+      apply(key, flag, true);
+    } else if (flag.kind === "list") {
+      const items: string[] = equals === -1 ? [] : [token.slice(equals + 1)];
+      while (equals === -1 && index + 1 < argv.length && !looksLikeFlag(argv[index + 1]!)) items.push(argv[++index]!);
+      if (!items.length) throw new Error(`${tag}: argument ${spelled}: expected at least one argument`);
+      apply(key, flag, items);
+    } else {
+      const next = equals === -1 ? argv[index + 1] : token.slice(equals + 1);
+      if (next === undefined || (equals === -1 && looksLikeFlag(next))) throw new Error(`${tag}: argument ${spelled}: expected one argument`);
+      if (equals === -1) index++;
+      apply(key, flag, next);
+    }
+  }
+  if (name === "lora" && values["config-file"] !== undefined) applyLoraConfig(values, given, String(values["config-file"]), readConfig, tag, lookup, apply);
+  delete values["config-file"];
+  tagged(() => alias.finish?.(values, given));
+  // Positionals belong to the verb (`generate [query] [prompt]`); mlx_lm's commands take none.
+  const parsed: CommandArgs = { values, positionals };
+  // A module's verb checks its own positionals against its manifest when the host runs it.
+  if (isCommand(alias.verb)) checkPositionals(alias.verb, parsed);
+  return { command: alias.verb, parsed };
+}
+
+function readYaml(path: string): unknown { return Bun.YAML.parse(readFileSync(path, "utf8")); }
+
+/** mlx_lm.lora's `-c/--config`: the file's keys are the flags' names with underscores; a flag on the command line wins. */
+function applyLoraConfig(values: AliasValues, given: Set<string>, path: string, read: (path: string) => unknown, tag: string,
+  lookup: (token: string) => { key: string; flag: MlxLmFlag } | undefined, apply: (key: string, flag: MlxLmFlag, value: Value | string[]) => void): void {
+  let config: unknown;
+  try { config = read(path); }
+  catch (error) { throw new Error(`${tag}: cannot read config ${path}: ${error instanceof Error ? error.message : String(error)}`); }
+  if (config === null || typeof config !== "object" || Array.isArray(config)) throw new Error(`${tag}: config ${path} must be a YAML mapping`);
+  const entries = config as Record<string, unknown>;
+  const set = (name: string, value: unknown) => {
+    if (value === null || value === undefined) return;
+    const found = lookup(`--${name}`);
+    if (!found) throw new Error(`${tag}: config ${path}: unrecognized key ${name.replaceAll("-", "_")}`);
+    if (given.has(found.flag.to ?? found.key)) return; // the command line wins
+    if (found.flag.kind === "boolean") { if (value === true) apply(found.key, found.flag, true); return; }
+    apply(found.key, found.flag, String(value));
+  };
+  for (const [rawKey, value] of Object.entries(entries)) {
+    const key = rawKey.replaceAll("_", "-");
+    if (LORA_CONFIG_UNSUPPORTED.includes(rawKey) && value !== null) throw new Error(`${tag}: config ${path}: ${rawKey} is not supported`);
+    if (rawKey === "lora_parameters") {
+      const parameters = value as Record<string, unknown> | null;
+      for (const [parameter, parameterValue] of Object.entries(parameters ?? {})) {
+        if (parameterValue === null) continue;
+        if (!["rank", "scale", "dropout"].includes(parameter)) throw new Error(`${tag}: config ${path}: lora_parameters.${parameter} is not supported`);
+        set(parameter, parameterValue);
+      }
+    } else if (rawKey === "optimizer_config") {
+      const chosen = (value as Record<string, Record<string, unknown> | null> | null)?.[String(entries.optimizer ?? "adam")];
+      for (const [option, optionValue] of Object.entries(chosen ?? {})) {
+        if (optionValue === null) continue;
+        if (option !== "weight_decay") throw new Error(`${tag}: config ${path}: optimizer_config.${option} is not supported`);
+        set("weight-decay", optionValue);
+      }
+    } else set(key, value);
+  }
+}
+
+/** `mlx-bun.<cmd> --help`: what the alias translates, then the verb's own help. */
+export function aliasHelp(name: string): string {
+  const alias = requireAlias(name), verb = alias.verb;
+  const group = (pick: (flag: MlxLmFlag) => string | undefined) => Object.entries(alias.flags)
+    .flatMap(([key, flag]) => { const detail = pick(flag); return detail === undefined ? [] : [`  ${flag.short ? `-${flag.short}, ` : ""}--${key}${detail ? `  ${detail}` : ""}`]; });
+  const mapped = group(flag => flag.to ? `→ --${flag.to}` : flag.set && !flag.ignored && !flag.unsupported ? "(translated)" : undefined);
+  const ignored = group(flag => flag.ignored);
+  const unsupported = group(flag => flag.unsupported);
+  const section = (title: string, rows: string[]) => rows.length ? `\n${title}:\n${rows.join("\n")}\n` : "";
+  return `${PREFIX}${name} — mlx_lm.${name}-compatible alias of \`mlx-bun ${verb}\`\n\nUsage: ${PREFIX}${name} [options]\n\n` +
+    `Accepts mlx_lm.${name}'s arguments and every \`mlx-bun ${verb}\` option. Defaults and output locations (~/.mlx-bun) are\n` +
+    `mlx-bun's; an explicit path behaves as in mlx-lm.\n` +
+    section("mlx_lm spellings mapped", mapped) + section("Accepted, no effect", ignored) + section("mlx_lm options not supported", unsupported) +
+    `\nOptions of \`mlx-bun ${verb}\`:\n${help(verb).split("\nOptions:\n")[1]}`;
+}

package/src/cli/model-choice.ts

@@ -0,0 +1,33 @@
+// The public `mlx-bun/selection` entry: main's pure model-selection helpers
+// (src/fit.ts). A leaf module with no imports, so it loads without native MLX;
+// model-selection.ts applies these choices to the registry and fit.
+// Application choices, not hub policy: discovery and fit remain reusable libraries.
+
+/** The model automatic selection prefers (e4b). */
+export const DEFAULT_REPO_ID = "mlx-community/gemma-4-e4b-it-OptiQ-4bit";
+/** Downloaded first when no supported model is cached. */
+export const STARTER_REPO_ID = "mlx-community/MiniCPM5-1B-OptiQ-4bit";
+/** Fraction of RAM an automatically selected model may use while leaving room for other apps. */
+export const COEXIST_FRACTION = 0.6;
+
+/** Prefer e4b when it fits; otherwise retain room for other apps where possible.
+ * Explicit model selection does not use these advisory fit predicates. */
+export function chooseAutoModel<T extends { repoId: string; sizeBytes: number }>(
+  candidates: readonly T[], preferredRepo: string,
+  fitsFull: (candidate: T) => boolean, fitsCoexist: (candidate: T) => boolean,
+): T | undefined {
+  const preferred = candidates.find(candidate => candidate.repoId === preferredRepo);
+  if (preferred && fitsFull(preferred)) return preferred;
+  const largest = [...candidates].sort((a, b) => b.sizeBytes - a.sizeBytes);
+  return largest.find(fitsCoexist) ?? largest.find(fitsFull);
+}
+
+/** Largest Gemma a RAM tier can comfortably hold: the 26B at 48 GiB or more,
+ * the 12B at 24 GiB or more, otherwise DEFAULT_REPO_ID. An explicit opt-in:
+ * automatic selection never calls it. Pass the RAM, e.g. `os.totalmem()`. */
+export function largestRecommendedRepoId(ramBytes: number): string {
+  const gb = ramBytes / 2 ** 30;
+  if (gb >= 48) return "mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit";
+  if (gb >= 24) return "mlx-community/gemma-4-12B-it-OptiQ-4bit";
+  return DEFAULT_REPO_ID;
+}

package/src/cli/model-selection.ts

@@ -0,0 +1,84 @@
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { scanSnapshot, type ModelRecord, type Registry } from "@mlx-bun/hub/registry";
+import { downloadModel } from "@mlx-bun/hub/download";
+import { fit, thisMachine, type MachineSpec } from "@mlx-bun/inference/execution/fit";
+import { loadModelConfig } from "@mlx-bun/inference/artifacts/config";
+import { isSupportedModelRecord } from "@mlx-bun/inference/models/support";
+import { chooseAutoModel, COEXIST_FRACTION, DEFAULT_REPO_ID, STARTER_REPO_ID } from "./model-choice";
+import { openRegistry } from "../storage/paths";
+
+type ModelRegistry = Pick<Registry, "list" | "resolve" | "scan" | "close">;
+export interface ModelSelectionDependencies {
+  registry(): ModelRegistry;
+  scanSnapshot: typeof scanSnapshot;
+  download: typeof downloadModel;
+  machine(): MachineSpec;
+  assess(model: ModelRecord, machine: MachineSpec): Promise<{ full: boolean; coexist: boolean }>;
+  log(message: string): void;
+}
+const defaults: ModelSelectionDependencies = {
+  registry: () => openRegistry(), scanSnapshot, download: downloadModel, machine: thisMachine,
+  async assess(model, machine) {
+    const config = await loadModelConfig(model.path);
+    return {
+      full: fit(config, model.sizeBytes, 8192, machine, undefined, model.expertsBytes).fits,
+      coexist: fit(config, model.sizeBytes, 8192, machine, undefined, model.expertsBytes, machine.ramBytes * COEXIST_FRACTION).fits,
+    };
+  },
+  log: message => console.log(message),
+};
+
+/** Resolve a path/query, or select a cached supported model. An empty supported
+ * cache gets the starter first, as in main; the larger recommended model is
+ * returned for the caller to fetch in the background under its own owner.
+ * `signal` cancels the starter download (its partial stays resumable). */
+export async function resolveModelAuto(query: string | null, supplied: Partial<ModelSelectionDependencies> = {},
+  signal?: AbortSignal): Promise<{ m: ModelRecord; picked: boolean; recommended?: string }> {
+  const deps = { ...defaults, ...supplied };
+  if (query && existsSync(join(query, "config.json"))) {
+    const directory = resolve(query);
+    const hf = /models--([^/]+)--([^/]+)\/snapshots\//.exec(directory);
+    const repoId = hf ? `${hf[1]}/${hf[2]}` : basename(directory);
+    const model = await deps.scanSnapshot(directory, repoId);
+    if (!model) throw new Error(`${directory} has config.json but no weights (*.safetensors)`);
+    return { m: model, picked: false };
+  }
+  const registry = deps.registry();
+  try {
+    if (registry.list().length === 0) await registry.scan();
+    if (query) return { m: registry.resolve(query), picked: false };
+    const supported = () => registry.list().filter(model => isSupportedModelRecord(model.modelType));
+    let candidates = supported();
+    let recommended: string | undefined;
+    if (candidates.length === 0) {
+      signal?.throwIfAborted();
+      deps.log(`Downloading starter model ${STARTER_REPO_ID}`);
+      const reported = new Map<string, number>();
+      await deps.download(STARTER_REPO_ID, {
+        signal,
+        onProgress(file, received, total) {
+          // Keep redirected startup logs bounded while still showing large transfers.
+          const bucket = total ? Math.floor(received / total * 10) : Math.floor(received / 100_000_000);
+          if (reported.get(file) === bucket) return;
+          reported.set(file, bucket);
+          const progress = total ? `${Math.floor(received / total * 100)}%` : `${received} bytes`;
+          deps.log(`Starter model: ${file} (${progress})`);
+        },
+      });
+      await registry.scan();
+      deps.log(`Starter ready; downloading ${DEFAULT_REPO_ID} in the background for the next start.`);
+      recommended = DEFAULT_REPO_ID;
+      candidates = supported();
+    }
+    signal?.throwIfAborted();
+    const machine = deps.machine();
+    const assessments = new Map<string, { full: boolean; coexist: boolean }>();
+    for (const model of candidates) assessments.set(model.repoId, await deps.assess(model, machine));
+    const chosen = chooseAutoModel(candidates, DEFAULT_REPO_ID,
+      model => assessments.get(model.repoId)?.full ?? false,
+      model => assessments.get(model.repoId)?.coexist ?? false);
+    if (!chosen) throw new Error("No downloaded supported model fits this machine — pick one explicitly (mlx-bun ls).");
+    return { m: chosen, picked: true, ...(recommended ? { recommended } : {}) };
+  } finally { registry.close(); }
+}

package/src/cli/module-host.ts

@@ -0,0 +1,11 @@
+// Loading the installed modules (`src/modules.ts`) over a host's core services
+// (`@mlx-bun/app-services`); the serve composition supplies the generation
+// gateway's execution lock so decoding never overlaps chat.
+import type { LoadedModules } from "@mlx-bun/app-host";
+import { activateModules, type HostServices } from "@mlx-bun/app-services";
+import { installedModules, type ModuleScope } from "../modules";
+
+/** Activate the installed modules of a scope (see `ModuleScope`) over the host's core services. */
+export async function loadInstalledModules(host: Pick<HostServices, "bindings">, scope: ModuleScope = "model"): Promise<LoadedModules> {
+  return activateModules(await installedModules(scope), host);
+}

package/src/cli/module-verbs.ts

@@ -0,0 +1,50 @@
+// The CLI verbs the installed modules declare (`src/modules.ts`): their
+// manifests are plain data, so the command list, `--help` and argument parsing
+// read them without activating anything. Running one activates the verb's
+// module over this app's core services and hands the verb what the host parsed.
+import type { CliVerbSpec } from "@mlx-bun/app-core";
+import { manifests } from "../modules";
+
+export const PROGRAM = "mlx-bun";
+
+/** Verb name to its declared spec, in installation order. */
+export function installedVerbs(): ReadonlyMap<string, CliVerbSpec> {
+  return new Map(manifests.flatMap(manifest => (manifest.verbs ?? []).map(spec => [spec.name, spec] as const)));
+}
+
+/** Run an installed module's verb, from its argv or from the values another spelling of the verb (`mlx-bun.convert`) already parsed; resolves to the exit code. */
+export async function runInstalledVerb(name: string, input: string[] | { values: Readonly<Record<string, unknown>>; positionals: readonly string[] }): Promise<number> {
+  const spec = installedVerbs().get(name);
+  if (!spec) throw new Error(`Unknown command: ${name}`);
+  // The module code and its services load only now, so the command list and help stay light.
+  const [{ createHostServices, runVerb }, { installedModules }, { createCatalogHub }, terminal, { createJobHost }, { createJobService }, { JobStore }, { fileURLToPath }, fs, os, path] = await Promise.all([
+    import("@mlx-bun/app-services"), import("../modules"), import("../publishing/catalog-hub"), import("./terminal"), import("../jobs/host"), import("../jobs/service"), import("../jobs/db"),
+    import("node:url"), import("node:fs"), import("node:os"), import("node:path") ]);
+  // A one-shot verb records the jobs it starts in a store of its own, created on first use and removed when it ends:
+  // nothing of it is left in the app's job history. Its children hold no lease: no model is loaded beside them.
+  const scratch = path.join(os.tmpdir(), `mlx-bun-verb-${crypto.randomUUID()}`);
+  const jobs = createJobHost({ entry: fileURLToPath(new URL("./job-entry.ts", import.meta.url)), acquire: async () => ({ dispose() {} }),
+    createStore: () => new JobStore(path.join(scratch, "jobs.db"), path.join(scratch, "logs")) });
+  const jobService = createJobService(jobs);
+  // A verb that names no model runs on the app's automatic choice (`cli/model-selection.ts`), the same one `serve` makes.
+  const host = createHostServices({ log() {}, hub: { ...createCatalogHub(), async pickDefault(signal) {
+    const { m } = await (await import("./model-selection")).resolveModelAuto(null, {}, signal);
+    return { id: m.repoId, directory: m.path };
+  } } });
+  const memoryDependencies = name === "memory" || name === "setup" ? (await import("./memory")).defaultMemoryDependencies() : undefined;
+  try {
+    return await runVerb({ program: PROGRAM, spec, ...(Array.isArray(input) ? { argv: input } : input), services: { ...host, bindings: { ...host.bindings, jobs: () => jobService, ...(memoryDependencies ? { storage: (scope) => {
+        const storage = host.bindings.storage!(scope);
+        return { path: (key, options) => key === "vault" ? memoryDependencies.vault : storage.path(key, options) };
+      } } : {}) } },
+      // Only the verb's own module activates (a verb of one module never starts another's runners).
+      modules: async () => installedModules(manifest => manifest.verbs?.some(verb => verb.name === name) ?? false,
+        name === "memory" || name === "setup" ? { memory: { cli: () => (memoryDependencies!) } } : {}),
+      activated: loaded => jobService.serve(loaded.jobs),
+      terminal: { step: terminal.step, box: lines => terminal.box([...lines]), heading: terminal.h1,
+        table: (columns, rows) => terminal.table(columns.map(column => ({ ...column })), rows.map(row => [...row])),
+        style: { ...terminal.style, gradient: terminal.gradient } } });
+  } finally {
+    try { await jobs.close(); } finally { fs.rmSync(scratch, { recursive: true, force: true }); }
+  }
+}

package/src/cli/numerical-policy.ts

@@ -0,0 +1,12 @@
+import type { CommandArgs } from "./args";
+
+/** Resolve main's numerical aliases once, before model loading. An explicit
+ * KV choice overrides the preset; the explicit kernel choice overrides both. */
+export function numericalPolicy(args: CommandArgs): { kv: string | undefined; fusedSdpa: boolean } {
+  const value = (name: string) => typeof args.values[name] === "string" ? args.values[name] as string : undefined;
+  const kv = value("kv-quant") ?? (args.values.l2 === true ? "config" : args.values.l1 === true ? "off" : undefined);
+  const fused = value("fused-sdpa");
+  if (fused !== undefined && !["on", "off", "1", "0", "true", "false"].includes(fused))
+    throw new Error("--fused-sdpa expects on|off");
+  return { kv, fusedSdpa: fused === undefined ? kv === "config" : ["on", "1", "true"].includes(fused) };
+}

package/src/cli/perplexity.ts

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { CommandArgs } from "./args";
+import { openRegistry } from "../storage/paths";
+import pkg from "../../package.json" with { type: "json" };
+
+// Main's `mlx-bun perplexity` (02d723a:src/cli.ts): mlx_lm.perplexity's method over
+// a LOCAL dataset file (never a Hugging Face download), scored in process.
+
+export const PERPLEXITY_USAGE = "usage: mlx-bun perplexity <model-query-or-path> --data-path <file.txt|file.jsonl> [--sequence-length 512] [--num-samples 256] [--batch-size 8] [--seed 123]";
+
+export interface PerplexityOptions { model: string; dataPath: string; sequenceLength: number; numSamples: number; batchSize: number; seed: number; }
+
+/** Main's flags, defaults and validation; -1 (all rows) is accepted for --num-samples only. */
+export function perplexityOptions(parsed: CommandArgs): PerplexityOptions {
+  const { values, positionals } = parsed;
+  const model = positionals[0] ?? values.model ?? values.query, dataPath = values["data-path"];
+  if (typeof model !== "string" || typeof dataPath !== "string") throw new Error(PERPLEXITY_USAGE);
+  const int = (name: string, fallback: number, lo: number) => {
+    const raw = values[name] === undefined ? String(fallback) : String(values[name]), v = Number(raw);
+    if (!Number.isInteger(v) || (v < lo && !(name === "num-samples" && v === -1)))
+      throw new Error(`--${name} expects an integer >= ${lo} (got "${raw}")`);
+    return v;
+  };
+  return { model, dataPath, sequenceLength: int("sequence-length", 512, 2), numSamples: int("num-samples", 256, 1),
+    batchSize: int("batch-size", 8, 1), seed: int("seed", 123, 0) };
+}
+
+const gb = (bytes: number) => `${(bytes / 2 ** 30).toFixed(2)} GB`;
+
+export async function runPerplexity(parsed: CommandArgs): Promise<void> {
+  const o = perplexityOptions(parsed);
+  if (!existsSync(o.dataPath)) throw new Error(`data file not found: ${o.dataPath} (a local .txt or .jsonl — HF datasets are not downloaded)`);
+  let modelDir = o.model;
+  if (!existsSync(join(o.model, "config.json"))) {
+    const reg = openRegistry();
+    try {
+      if (reg.list().length === 0) await reg.scan();
+      modelDir = reg.resolve(o.model).path;
+    } finally { reg.close(); }
+  }
+  modelDir = resolve(modelDir);
+
+  // The startup step: compile any Neural Engine program the system cache lacks before the model loads.
+  await (await import("./ane-install")).ensureAneInstall();
+  const { banner, step, box, style } = await import("./terminal");
+  banner(pkg.version);
+  const sLoad = step(`loading ${modelDir}`);
+  // The library dlopens MLX on import: load it only once the inputs are known good.
+  const { loadModelConfig, Weights, createModel, loadTokenizer } = await import("@mlx-bun/inference");
+  const { parseSamples, packRows, evalPpl } = await import("@mlx-bun/inference/scoring");
+  const { resolveModelProfile } = await import("@mlx-bun/inference/models/profile");
+  const { peakMemory, resetPeakMemory } = await import("@mlx-bun/mlx/ffi");
+  const config = await loadModelConfig(modelDir);
+  // Colibri-container checkpoints (GLM-5.2) need the streamed runtime; scoring runs the
+  // synchronous forward over createModel, as main's verb did, so refuse them before loading.
+  if (resolveModelProfile(config).profile.execution.loader === "colibri") {
+    sLoad.fail("Colibri-container checkpoint");
+    throw new Error(`${modelDir} is a Colibri-container checkpoint (GLM-5.2); perplexity scores createModel graphs only`);
+  }
+  const model = createModel(await Weights.open(modelDir), config);
+  const tok = await loadTokenizer(modelDir);
+  sLoad.done(`model loaded ${style.dim(`· ${modelDir}`)}`);
+
+  const sData = step(`tokenizing ${o.dataPath}`);
+  const samples = parseSamples(await Bun.file(o.dataPath).text(), o.dataPath);
+  const rows = packRows(samples.map(t => tok.encode(t)), { sequenceLength: o.sequenceLength, numSamples: o.numSamples, seed: o.seed });
+  if (rows.length === 0) {
+    sData.fail(`dataset too small: fewer than ${o.sequenceLength} tokens (need at least one full row)`);
+    throw new Error(`dataset too small: fewer than ${o.sequenceLength} tokens (need at least one full row)`);
+  }
+  sData.done(`${rows.length} row(s) × ${o.sequenceLength} tokens ${style.dim(`· ${samples.length} sample(s), seed ${o.seed}`)}`);
+
+  const sEval = step(`evaluating (batch ${o.batchSize})`);
+  resetPeakMemory();
+  const t0 = performance.now();
+  const r = evalPpl(model, rows, o.batchSize, (done, total) => sEval.update(`batch ${done}/${total}`));
+  const seconds = (performance.now() - t0) / 1000;
+  sEval.done(`evaluated ${r.tokens.toLocaleString()} tokens ${style.dim(`in ${seconds.toFixed(1)} s`)}`);
+  console.log();
+  box([
+    `${style.green("●")} ${style.bold("perplexity")} ${style.dim(`· ${modelDir.split("/snapshots/")[0]?.split("/").at(-1) ?? modelDir}`)}`,
+    "",
+    `ppl        ${style.green(style.bold(r.ppl.toFixed(3)))} ${style.dim(`± ${r.standardError.toFixed(3)}`)}`,
+    `mean CE    ${style.bold(r.meanLoss.toFixed(4))} ${style.dim("nats/token")}`,
+    `tokens     ${style.bold(r.tokens.toLocaleString())} ${style.dim(`· ${r.rows} row(s) × ${o.sequenceLength}`)}`,
+    `speed      ${style.dim(`${(r.tokens / seconds).toFixed(0)} tok/s · peak ${gb(peakMemory())}`)}`,
+  ]);
+}