llm-tuner 0.1.0

package/src/core/gguf.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs/promises';
+
+// Minimal GGUF header reader: metadata key/values and tensor infos.
+// Spec: https://github.com/ggml-org/ggml/blob/master/docs/gguf.md
+
+const T = { UINT8: 0, INT8: 1, UINT16: 2, INT16: 3, UINT32: 4, INT32: 5, FLOAT32: 6, BOOL: 7, STRING: 8, ARRAY: 9, UINT64: 10, INT64: 11, FLOAT64: 12 };
+
+// ggml tensor types -> [block size (elements), bytes per block]
+const GGML_TYPE_SIZE = {
+  0: [1, 4], 1: [1, 2], 2: [32, 18], 3: [32, 20], 6: [32, 22], 7: [32, 24], 8: [32, 34], 9: [32, 36],
+  10: [256, 84], 11: [256, 110], 12: [256, 144], 13: [256, 176], 14: [256, 210], 15: [256, 292],
+  16: [256, 66], 17: [256, 74], 18: [256, 98], 19: [256, 50], 20: [32, 18], 21: [256, 110], 22: [256, 82],
+  23: [256, 136], 24: [1, 1], 25: [1, 2], 26: [1, 4], 27: [1, 8], 28: [1, 8], 29: [256, 56], 30: [1, 2],
+  34: [256, 54], 35: [256, 66], 39: [32, 17],
+};
+
+class Reader {
+  constructor(fh) { this.fh = fh; this.buf = Buffer.alloc(0); this.bufStart = 0; this.pos = 0; }
+  async ensure(n) {
+    const end = this.pos + n;
+    if (this.pos >= this.bufStart && end <= this.bufStart + this.buf.length) return;
+    const size = Math.max(n, 4 * 1024 * 1024);
+    const buf = Buffer.alloc(size);
+    const { bytesRead } = await this.fh.read(buf, 0, size, this.pos);
+    if (bytesRead < n) throw new Error('GGUF: unexpected end of file');
+    this.buf = buf.subarray(0, bytesRead);
+    this.bufStart = this.pos;
+  }
+  async take(n) { await this.ensure(n); const o = this.pos - this.bufStart; this.pos += n; return this.buf.subarray(o, o + n); }
+  async u32() { return (await this.take(4)).readUInt32LE(0); }
+  async u64() { return Number((await this.take(8)).readBigUInt64LE(0)); }
+  async str() { const n = await this.u64(); return (await this.take(n)).toString('utf8'); }
+  async value(type, keepArrays) {
+    switch (type) {
+      case T.UINT8: return (await this.take(1)).readUInt8(0);
+      case T.INT8: return (await this.take(1)).readInt8(0);
+      case T.UINT16: return (await this.take(2)).readUInt16LE(0);
+      case T.INT16: return (await this.take(2)).readInt16LE(0);
+      case T.UINT32: return (await this.take(4)).readUInt32LE(0);
+      case T.INT32: return (await this.take(4)).readInt32LE(0);
+      case T.FLOAT32: return (await this.take(4)).readFloatLE(0);
+      case T.BOOL: return (await this.take(1)).readUInt8(0) !== 0;
+      case T.STRING: return this.str();
+      case T.UINT64: return Number((await this.take(8)).readBigUInt64LE(0));
+      case T.INT64: return Number((await this.take(8)).readBigInt64LE(0));
+      case T.FLOAT64: return (await this.take(8)).readDoubleLE(0);
+      case T.ARRAY: {
+        const itemType = await this.u32();
+        const n = await this.u64();
+        // Large arrays (tokenizer vocab) are skipped; we only keep their length.
+        if (!keepArrays || n > 4096) {
+          for (let i = 0; i < n; i++) await this.value(itemType, false);
+          return { length: n };
+        }
+        const out = [];
+        for (let i = 0; i < n; i++) out.push(await this.value(itemType, false));
+        return out;
+      }
+      default: throw new Error(`GGUF: unknown value type ${type}`);
+    }
+  }
+}
+
+export async function readGguf(file) {
+  const fh = await fs.open(file, 'r');
+  try {
+    const stat = await fh.stat();
+    const r = new Reader(fh);
+    const magic = (await r.take(4)).toString('ascii');
+    if (magic !== 'GGUF') throw new Error(`${file} is not a GGUF file`);
+    const version = await r.u32();
+    const nTensors = await r.u64();
+    const nKv = await r.u64();
+    const kv = {};
+    for (let i = 0; i < nKv; i++) {
+      const key = await r.str();
+      const type = await r.u32();
+      kv[key] = await r.value(type, true);
+    }
+    const tensors = [];
+    for (let i = 0; i < nTensors; i++) {
+      const name = await r.str();
+      const nDims = await r.u32();
+      const dims = [];
+      for (let d = 0; d < nDims; d++) dims.push(await r.u64());
+      const type = await r.u32();
+      await r.u64(); // offset
+      const elems = dims.reduce((a, b) => a * b, 1);
+      const [bs, bb] = GGML_TYPE_SIZE[type] ?? [1, 2];
+      tensors.push({ name, dims, type, bytes: Math.ceil(elems / bs) * bb });
+    }
+    return { version, kv, tensors, fileBytes: stat.size };
+  } finally {
+    await fh.close();
+  }
+}
+
+const first = (v) => (Array.isArray(v) ? Math.max(...v) : v);
+
+/**
+ * Turn raw GGUF data into the numbers the estimator needs: per-layer weight
+ * bytes, which layers have attention (KV cache), KV head dims, experts, vocab.
+ */
+export function summarizeGguf({ kv, tensors, fileBytes }) {
+  const arch = kv['general.architecture'];
+  const g = (k) => kv[`${arch}.${k}`];
+  const nLayers = g('block_count');
+  const nEmbd = g('embedding_length');
+  const nHead = first(g('attention.head_count'));
+  const headCountKv = g('attention.head_count_kv');
+  const nHeadKv = first(headCountKv ?? nHead);
+  const keyLen = g('attention.key_length') ?? (nEmbd && nHead ? nEmbd / nHead : 128);
+  const valLen = g('attention.value_length') ?? keyLen;
+  const vocab = kv['tokenizer.ggml.tokens']?.length ?? g('vocab_size') ?? 32000;
+
+  const layerBytes = new Array(nLayers).fill(0);
+  const layerExpertBytes = new Array(nLayers).fill(0);
+  const attnLayers = new Set();
+  let outputBytes = 0, embdBytes = 0;
+  for (const t of tensors) {
+    const m = /^blk\.(\d+)\.(.+)$/.exec(t.name);
+    if (m) {
+      const i = Number(m[1]);
+      if (i >= nLayers) continue; // e.g. MTP / nextn layers not used for inference
+      layerBytes[i] += t.bytes;
+      if (/_exps\./.test(m[2])) layerExpertBytes[i] += t.bytes;
+      if (/^attn_(k|q|qkv|kv_a_mqa|k_b)\b/.test(m[2])) attnLayers.add(i);
+    } else if (/^token_embd/.test(t.name)) embdBytes += t.bytes;
+    else outputBytes += t.bytes; // output.weight, output_norm, rope freqs...
+  }
+  // Tied embeddings: output shares token_embd, llama.cpp still puts a copy on GPU.
+  if (!tensors.some((t) => t.name === 'output.weight')) outputBytes += embdBytes;
+
+  // Per-layer KV heads can be an array (0 for non-attention layers).
+  const kvHeadsPerLayer = Array.from({ length: nLayers }, (_, i) =>
+    Array.isArray(headCountKv) ? headCountKv[i] : (attnLayers.has(i) || attnLayers.size === 0 ? nHeadKv : 0));
+
+  const slidingWindow = g('attention.sliding_window') || null;
+  // Some SWA models declare which layers use it; fall back to "every layer but each Nth".
+  let swaLayers = [];
+  const pattern = g('attention.sliding_window_pattern');
+  if (slidingWindow) {
+    if (Array.isArray(pattern)) swaLayers = pattern.map((v, i) => (v ? i : -1)).filter((i) => i >= 0);
+    else if (typeof pattern === 'number' && pattern > 1) swaLayers = [...Array(nLayers).keys()].filter((i) => (i + 1) % pattern !== 0);
+  }
+
+  const nExperts = g('expert_count') || 0;
+  const nExpertsUsed = g('expert_used_count') || 0;
+
+  let totalBytes = 0, totalElements = 0;
+  for (const t of tensors) {
+    totalBytes += t.bytes;
+    let elements = 1;
+    for (const d of t.dims) elements *= d;
+    totalElements += elements;
+  }
+  const bitsPerWeight = totalElements === 0 ? null : +(totalBytes * 8 / totalElements).toFixed(2);
+
+  return {
+    arch,
+    name: kv['general.name'] || null,
+    nLayers,
+    nEmbd,
+    nHead,
+    nHeadKv,
+    keyLen,
+    valLen,
+    vocab,
+    trainContext: g('context_length') || null,
+    fileBytes,
+    bitsPerWeight,
+    layerBytes,
+    layerExpertBytes,
+    outputBytes,
+    embdBytes,
+    kvHeadsPerLayer,
+    slidingWindow,
+    swaLayers,
+    nExperts,
+    nExpertsUsed,
+    isMoE: nExperts > 1,
+  };
+}
+
+export async function modelMetaFromFile(file) {
+  return summarizeGguf(await readGguf(file));
+}

package/src/core/hardware.js

@@ -0,0 +1,162 @@
+import os from 'node:os';
+import si from 'systeminformation';
+import { run, which, PLATFORM, MiB, GiB } from './util.js';
+
+// Approximate memory bandwidth (GB/s) for common GPUs. Used only to rank
+// candidates before benchmarking, so rough numbers are fine.
+const GPU_BANDWIDTH = [
+  [/RTX 5090/i, 1792], [/RTX 5080/i, 960], [/RTX 5070 Ti/i, 896], [/RTX 5070/i, 672], [/RTX 5060 Ti/i, 448], [/RTX 5060/i, 448],
+  [/RTX 4090/i, 1008], [/RTX 4080/i, 717], [/RTX 4070 Ti/i, 504], [/RTX 4070/i, 504], [/RTX 4060 Ti/i, 288], [/RTX 4060/i, 272],
+  [/RTX 3090/i, 936], [/RTX 3080/i, 760], [/RTX 3070/i, 448], [/RTX 3060 Ti/i, 448], [/RTX 3060/i, 360],
+  [/RTX 20[0-9]0/i, 448], [/GTX 16[0-9]0/i, 192], [/GTX 10[0-9]0/i, 256],
+  [/A100/i, 1935], [/H100/i, 3350], [/L40/i, 864], [/A6000/i, 768], [/A4000/i, 448],
+  [/RX 9070 XT/i, 640], [/RX 9070/i, 640], [/RX 7900 XTX/i, 960], [/RX 7900/i, 800], [/RX 7800/i, 624], [/RX 7700/i, 432], [/RX 7600/i, 288],
+  [/RX 6900|RX 6800/i, 512], [/RX 6700/i, 384],
+  [/Arc A770/i, 560], [/Arc B580/i, 456],
+];
+
+// Apple Silicon unified memory bandwidth (GB/s).
+const APPLE_BANDWIDTH = [
+  [/M[1-5] Ultra/i, 800], [/M4 Max/i, 546], [/M[1-3] Max/i, 400], [/M4 Pro/i, 273], [/M[1-3] Pro/i, 200], [/M4/i, 120], [/M[1-3]/i, 100],
+];
+
+// PCIe per-lane throughput in GB/s by generation.
+const PCIE_LANE_GBPS = { 1: 0.25, 2: 0.5, 3: 0.985, 4: 1.97, 5: 3.94, 6: 7.56 };
+
+const lookup = (table, name, dflt) => (table.find(([re]) => re.test(name))?.[1] ?? dflt);
+
+async function nvidiaGpus() {
+  const smi = await which('nvidia-smi', PLATFORM === 'win32' ? ['C:\\Windows\\System32\\nvidia-smi.exe'] : []);
+  if (!smi) return [];
+  const fields = 'index,name,uuid,pci.bus_id,memory.total,memory.used,memory.free,pcie.link.gen.max,pcie.link.width.current,pcie.link.width.max,display_active';
+  const r = await run(smi, [`--query-gpu=${fields}`, '--format=csv,noheader,nounits']);
+  if (r.code !== 0) return [];
+  return r.stdout.trim().split('\n').filter(Boolean).map((line) => {
+    const [index, name, uuid, busId, total, used, free, gen, widthCur, widthMax, display] = line.split(',').map((s) => s.trim());
+    const pcieGen = Number(gen) || null;
+    // width.max reports the GPU's capability; width.current reflects the real slot.
+    const pcieWidth = Number(widthCur) || Number(widthMax) || null;
+    return {
+      vendor: 'nvidia',
+      backend: 'cuda',
+      index: Number(index),
+      name,
+      uuid,
+      busId,
+      totalBytes: Number(total) * MiB,
+      usedBytes: Number(used) * MiB,
+      freeBytes: Number(free) * MiB,
+      pcieGen,
+      pcieWidth,
+      pcieGBps: pcieGen && pcieWidth ? +(PCIE_LANE_GBPS[pcieGen] * pcieWidth).toFixed(1) : null,
+      displayAttached: /enabled/i.test(display || ''),
+      bandwidthGBps: lookup(GPU_BANDWIDTH, name, 400),
+    };
+  });
+}
+
+async function amdGpus() {
+  const smi = await which('rocm-smi');
+  if (!smi) return [];
+  const r = await run(smi, ['--showmeminfo', 'vram', '--showproductname', '--json']);
+  if (r.code !== 0) return [];
+  let data;
+  try { data = JSON.parse(r.stdout); } catch { return []; }
+  return Object.entries(data)
+    .filter(([k]) => /^card\d+/.test(k))
+    .map(([k, v], i) => {
+      const total = Number(v['VRAM Total Memory (B)'] || 0);
+      const used = Number(v['VRAM Total Used Memory (B)'] || 0);
+      const name = v['Card Series'] || v['Card series'] || v['Card model'] || k;
+      return {
+        vendor: 'amd', backend: 'rocm', index: i, name, uuid: k, busId: null,
+        totalBytes: total, usedBytes: used, freeBytes: total - used,
+        pcieGen: null, pcieWidth: null, pcieGBps: null, displayAttached: false,
+        bandwidthGBps: lookup(GPU_BANDWIDTH, name, 400),
+      };
+    });
+}
+
+async function appleGpu(cpuBrand, totalMem) {
+  if (PLATFORM !== 'darwin' || os.arch() !== 'arm64') return [];
+  // macOS lets Metal wire roughly 2/3 of RAM on small machines, ~3/4 on larger ones.
+  const usable = totalMem <= 36 * GiB ? totalMem * 0.67 : totalMem * 0.75;
+  return [{
+    vendor: 'apple', backend: 'metal', index: 0, name: `${cpuBrand} GPU`, uuid: 'apple-gpu', busId: null,
+    totalBytes: usable, usedBytes: 0, freeBytes: usable, unifiedMemory: true,
+    pcieGen: null, pcieWidth: null, pcieGBps: null, displayAttached: true,
+    bandwidthGBps: lookup(APPLE_BANDWIDTH, cpuBrand, 100),
+  }];
+}
+
+/** Fallback for GPUs without a vendor tool (Intel, AMD on Windows, ...). */
+function genericGpus(controllers) {
+  return controllers
+    .filter((c) => c.vram && c.vram > 512 && !/microsoft basic|llvmpipe|virtual/i.test(c.model || ''))
+    .map((c, i) => ({
+      vendor: /nvidia/i.test(c.vendor) ? 'nvidia' : /amd|ati|advanced micro/i.test(c.vendor) ? 'amd' : /intel/i.test(c.vendor) ? 'intel' : 'other',
+      backend: 'vulkan', index: i, name: c.model, uuid: c.busAddress || `gpu${i}`, busId: c.busAddress || null,
+      totalBytes: c.vram * MiB, usedBytes: (c.memoryUsed ?? 0) * MiB, freeBytes: (c.memoryFree ?? c.vram) * MiB,
+      pcieGen: null, pcieWidth: null, pcieGBps: null, displayAttached: false,
+      bandwidthGBps: lookup(GPU_BANDWIDTH, c.model || '', 300),
+      vramApproximate: true,
+    }));
+}
+
+/**
+ * Snapshot of the machine: CPU, RAM and GPUs (with free VRAM and PCIe link).
+ * GPUs are sorted by suggested priority: fastest link / no display first.
+ */
+export async function detectHardware() {
+  const [cpu, mem, osInfo, graphics] = await Promise.all([si.cpu(), si.mem(), si.osInfo(), si.graphics().catch(() => ({ controllers: [] }))]);
+  const cpuBrand = `${cpu.manufacturer} ${cpu.brand}`.trim();
+
+  let gpus = await nvidiaGpus();
+  if (!gpus.length) gpus = await amdGpus();
+  if (!gpus.length) gpus = await appleGpu(cpuBrand, mem.total);
+  if (!gpus.length) gpus = genericGpus(graphics.controllers || []);
+
+  return {
+    os: { platform: PLATFORM, distro: osInfo.distro, release: osInfo.release, arch: os.arch() },
+    cpu: {
+      brand: cpuBrand,
+      physicalCores: cpu.physicalCores || Math.max(1, Math.floor(os.cpus().length / 2)),
+      threads: cpu.cores || os.cpus().length,
+      avx2: /avx2/i.test(cpu.flags || ''),
+    },
+    ram: { totalBytes: mem.total, availableBytes: mem.available },
+    // Dual-channel DDR4 ~40 GB/s, DDR5 ~70 GB/s; Apple uses unified memory.
+    ramBandwidthGBps: gpus[0]?.unifiedMemory ? gpus[0].bandwidthGBps : 45,
+    gpus: rankGpus(gpus),
+  };
+}
+
+/**
+ * Priority order for placing model layers: prefer the GPU with the widest
+ * PCIe link, then the one not driving a display, then the most free VRAM.
+ */
+export function rankGpus(gpus) {
+  return [...gpus].sort((a, b) =>
+    (b.pcieGBps ?? 0) - (a.pcieGBps ?? 0) ||
+    Number(a.displayAttached) - Number(b.displayAttached) ||
+    b.freeBytes - a.freeBytes ||
+    a.index - b.index);
+}
+
+/** Poll per-GPU VRAM usage (NVIDIA only) until stop() is called. */
+export function startVramSampler(intervalMs = 500) {
+  const peaks = new Map();
+  let timer = null;
+  let stopped = false;
+  const tick = async () => {
+    const gpus = await nvidiaGpus();
+    for (const g of gpus) peaks.set(g.index, Math.max(peaks.get(g.index) ?? 0, g.usedBytes));
+    if (!stopped) timer = setTimeout(tick, intervalMs);
+  };
+  tick();
+  return {
+    stop() { stopped = true; clearTimeout(timer); return Object.fromEntries(peaks); },
+  };
+}
+
+export { nvidiaGpus };

package/src/core/index.js

@@ -0,0 +1,10 @@
+export { detectHardware, rankGpus } from './hardware.js';
+export { readGguf, summarizeGguf, modelMetaFromFile } from './gguf.js';
+export { planCandidates, placeLayers, maxFullOffloadContext, kvTotalBytes, KV_TYPES } from './estimator.js';
+export { Tuner, ENGINES, detectEngines, pickBest, slim } from './tuner.js';
+export { PROFILES, DEFAULT_PROFILE, normalizeProfile, QUALITY_KV_TYPES, kvTypesFor, meetsQuality, fitsFullyOnGpu, pickVariant, recommendProfile, HINT_TARGETS, variantHints, VRAM_BUSY_FRACTION, vramInUse } from './profiles.js';
+export { installPlans, runInstall, openUrl } from './installer.js';
+export { fmtBytes, configDir } from './util.js';
+export { findPreset, savePreset, listPresets, presetsDir, presetPath, variantsSignature, hardwareFingerprint } from './presets.js';
+export { readSettings, writeSettings, settingsPath, THEMES, DEFAULT_THEME, normalizeTheme } from './settings.js';
+export { TunerError, benchError } from './errors.js';

package/src/core/installer.js

@@ -0,0 +1,59 @@
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { which, PLATFORM } from './util.js';
+
+/**
+ * Official install routes per engine and OS. Every plan is shown to the user
+ * before running; nothing is installed silently.
+ */
+export async function installPlans(engineId) {
+  const brew = PLATFORM === 'darwin' ? await which('brew') : null;
+  const winget = PLATFORM === 'win32' ? await which('winget') : null;
+  const arch = os.arch() === 'arm64' ? 'arm64' : 'x64';
+  const plans = [];
+
+  if (engineId === 'ollama') {
+    if (PLATFORM === 'linux') plans.push({ id: 'script', labelCode: 'install.ollamaScript', shell: 'curl -fsSL https://ollama.com/install.sh | sh', needsSudo: true });
+    if (PLATFORM === 'darwin') {
+      if (brew) plans.push({ id: 'brew', labelCode: 'install.ollamaBrew', cmd: 'brew', args: ['install', '--cask', 'ollama'] });
+      plans.push({ id: 'dmg', labelCode: 'install.ollamaDmg', url: 'https://ollama.com/download/Ollama.dmg', manual: true });
+    }
+    if (PLATFORM === 'win32') {
+      if (winget) plans.push({ id: 'winget', labelCode: 'install.ollamaWinget', cmd: 'winget', args: ['install', '-e', '--id', 'Ollama.Ollama', '--accept-source-agreements', '--accept-package-agreements'] });
+      plans.push({ id: 'ps1', labelCode: 'install.ollamaPs1', cmd: 'powershell', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', 'irm https://ollama.com/install.ps1 | iex'] });
+    }
+  }
+
+  if (engineId === 'lmstudio') {
+    if (PLATFORM === 'linux' || PLATFORM === 'darwin') {
+      plans.push({ id: 'llmster', labelCode: 'install.lmsHeadless', shell: 'curl -fsSL https://lmstudio.ai/install.sh | bash' });
+    }
+    if (PLATFORM === 'darwin' && brew) plans.push({ id: 'brew', labelCode: 'install.lmsBrew', cmd: 'brew', args: ['install', '--cask', 'lm-studio'] });
+    if (PLATFORM === 'win32') {
+      if (winget) plans.push({ id: 'winget', labelCode: 'install.lmsWinget', cmd: 'winget', args: ['install', '-e', '--id', 'ElementLabs.LMStudio', '--accept-source-agreements', '--accept-package-agreements'] });
+      plans.push({ id: 'ps1', labelCode: 'install.lmsHeadlessPs1', cmd: 'powershell', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', 'irm https://lmstudio.ai/install.ps1 | iex'] });
+    }
+    const plat = { linux: 'linux', darwin: 'darwin', win32: 'win32' }[PLATFORM];
+    plans.push({ id: 'download', labelCode: 'install.lmsDownload', url: `https://lmstudio.ai/download/latest/${plat}/${arch}`, manual: true });
+  }
+  return plans;
+}
+
+/** Run an install plan, streaming output lines to `onLine`. Resolves exit code. */
+export function runInstall(plan, onLine = () => {}) {
+  if (plan.manual) {
+    openUrl(plan.url);
+    return Promise.resolve({ code: 0, manual: true });
+  }
+  const child = plan.shell
+    ? spawn(PLATFORM === 'win32' ? 'cmd' : 'sh', PLATFORM === 'win32' ? ['/c', plan.shell] : ['-c', plan.shell], { stdio: ['inherit', 'pipe', 'pipe'] })
+    : spawn(plan.cmd, plan.args, { stdio: ['inherit', 'pipe', 'pipe'], windowsHide: true });
+  child.stdout.on('data', (d) => String(d).split(/\r?\n/).filter(Boolean).forEach(onLine));
+  child.stderr.on('data', (d) => String(d).split(/\r?\n/).filter(Boolean).forEach(onLine));
+  return new Promise((resolve) => child.on('exit', (code) => resolve({ code })));
+}
+
+export function openUrl(url) {
+  const [cmd, args] = PLATFORM === 'win32' ? ['cmd', ['/c', 'start', '', url]] : PLATFORM === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}

package/src/core/llama-server.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import { spawnLogged, killProcess, freePort, fetchJson, sleep, PLATFORM } from './util.js';
+import { makeCodePrompt, withSampling } from './benchmark.js';
+import { benchError } from './errors.js';
+
+const LIB_ENV = { linux: 'LD_LIBRARY_PATH', darwin: 'DYLD_LIBRARY_PATH', win32: 'PATH' };
+
+/** Translate an engine-agnostic candidate into llama-server flags. */
+export function llamaServerArgs(modelFile, c, port) {
+  // llama.cpp gives the *last* layers (and the output layer) to the last device,
+  // so devices are listed in reverse priority: the preferred GPU ends up last.
+  const split = [...c.tensorSplit].reverse();
+  const args = [
+    '--model', modelFile,
+    '--host', '127.0.0.1', '--port', String(port),
+    '--ctx-size', String(c.ctx),
+    '--n-gpu-layers', String(c.fullOffload ? 999 : c.gpuLayers),
+    '--split-mode', 'layer',
+    '--batch-size', String(c.batch), '--ubatch-size', String(c.ubatch),
+    '--threads', String(c.threads),
+    '--parallel', String(c.parallel),
+    '--cache-type-k', c.kvType, '--cache-type-v', c.kvType,
+    '--flash-attn', c.flashAttention ? 'on' : 'off',
+    '--kv-offload', '--no-kv-unified',
+    '--no-webui',
+  ];
+  if (split.length > 1) args.push('--tensor-split', split.join(','), '--main-gpu', String(split.length - 1));
+  if (c.cpuMoeLayers) args.push('--n-cpu-moe', String(c.cpuMoeLayers));
+  return args;
+}
+
+export function llamaServerEnv(libDirs, c) {
+  const key = LIB_ENV[PLATFORM] || 'LD_LIBRARY_PATH';
+  const env = { ...process.env, [key]: [...libDirs, process.env[key]].filter(Boolean).join(path.delimiter) };
+  if (c.gpuOrder?.length) {
+    // Match nvidia-smi numbering, then enumerate in reverse priority (see above).
+    env.CUDA_DEVICE_ORDER = 'PCI_BUS_ID';
+    env.CUDA_VISIBLE_DEVICES = [...c.gpuOrder].reverse().join(',');
+  }
+  return env;
+}
+
+/**
+ * Start the engine's own llama-server with exactly the candidate settings,
+ * measure a short and a deep prompt, then stop it. Same binary LM Studio uses,
+ * so results transfer 1:1 to the app.
+ */
+export async function runLlamaServerBenchmark({ server, libDirs, cwd, modelFile, candidate, depthTokens = 4000, genTokens = 200, onProgress = () => {} }) {
+  const port = await freePort();
+  const args = llamaServerArgs(modelFile, candidate, port);
+  const t0 = Date.now();
+  onProgress({ phase: 'load' });
+  const proc = spawnLogged(server, args, { cwd, env: llamaServerEnv(libDirs, candidate) });
+  const base = `http://127.0.0.1:${port}`;
+  try {
+    let healthy = false;
+    let exited = null;
+    proc.exited.then((e) => { exited = e; });
+    for (let i = 0; i < 1200 && !exited; i++) {
+      const h = await fetchJson(`${base}/health`, { timeout: 1000 });
+      if (h?.ok) { healthy = true; break; }
+      await sleep(500);
+    }
+    if (!healthy) {
+      const log = proc.lines.join('\n');
+      const oom = /out of memory|cudaMalloc failed|failed to allocate|ErrorOutOfDeviceMemory/i.test(log);
+      return oom
+        ? { ...benchError('bench.oomOnLoad'), oom, args, logTail: proc.lines.slice(-15) }
+        : { ok: false, oom, error: lastError(proc.lines), args, logTail: proc.lines.slice(-15) };
+    }
+    const loadSeconds = +((Date.now() - t0) / 1000).toFixed(1);
+
+    // Calibrate chars/token with the model's own tokenizer.
+    let cpt = 3.3;
+    const sample = makeCodePrompt(500);
+    const tok = await fetchJson(`${base}/tokenize`, { method: 'POST', body: { content: sample }, timeout: 10000 });
+    if (tok?.json?.tokens?.length) cpt = sample.length / tok.json.tokens.length;
+
+    const one = async (label, tokens) => {
+      onProgress({ phase: label, promptTokens: tokens });
+      const res = await fetchJson(`${base}/completion`, {
+        method: 'POST', timeout: 1_800_000,
+        body: { prompt: makeCodePrompt(tokens, cpt), n_predict: genTokens, ignore_eos: true, cache_prompt: false, temperature: 0.2 },
+      });
+      const t = res?.json?.timings;
+      if (!t) return { ok: false, error: res?.json?.error?.message || lastError(proc.lines) };
+      return { ok: true, promptTokens: t.prompt_n, genTokens: t.predicted_n, genTps: +t.predicted_per_second.toFixed(1), ppTps: Math.round(t.prompt_per_second) };
+    };
+
+    const maxDepth = Math.max(0, candidate.ctx - genTokens - 256);
+    const { result, cpu, vramPeakBytes } = await withSampling(async () => {
+      const short = await one('short', 200);
+      const deep = short.ok && depthTokens > 400 ? await one('deep', Math.min(depthTokens, maxDepth)) : null;
+      return { short, deep };
+    });
+    const ok = result.short.ok && (!result.deep || result.deep.ok);
+    return { ok, error: ok ? null : (result.deep?.error || result.short.error), loadSeconds, short: result.short, deep: result.deep, cpu, vramPeakBytes, args };
+  } finally {
+    await killProcess(proc.child);
+    await sleep(1000); // let the driver release VRAM before the next candidate
+  }
+}
+
+function lastError(lines) {
+  const errs = lines.filter((l) => /\b(E|error|failed)\b/i.test(l));
+  return (errs.slice(-2).join(' | ') || lines.slice(-2).join(' | ') || 'llama-server exited without responding').slice(0, 400);
+}

package/src/core/presets.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { configDir, readJson, GiB } from './util.js';
+import { DEFAULT_PROFILE, normalizeProfile } from './profiles.js';
+
+// A preset stores the benchmark winner for (engine, model, context, hardware),
+// so the tuning scripts only run again when one of those changes.
+
+export function presetsDir() {
+  return path.join(configDir(), 'presets');
+}
+
+/** Identifies the hardware a preset was measured on (GPU models + VRAM + CPU). */
+export function hardwareFingerprint(hw) {
+  const parts = [
+    hw.cpu.brand,
+    ...hw.gpus.map((g) => `${g.name}|${Math.round(g.totalBytes / GiB)}G|pcie${g.pcieGen ?? '?'}x${g.pcieWidth ?? '?'}`).sort(),
+  ];
+  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 16);
+}
+
+const slug = (s) => s.replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 120);
+
+/** Returns the path to the preset file. */
+export function presetPath(engine, modelKey, ctx, profile = DEFAULT_PROFILE) {
+  // The profile is part of the file name: anything that is not a known profile is balanced.
+  const safe = normalizeProfile(profile);
+  const suffix = safe === DEFAULT_PROFILE ? '' : `__${safe}`;
+  return path.join(presetsDir(), `${engine}__${slug(modelKey)}__${ctx}${suffix}.json`);
+}
+
+/** Identifies the downloaded variants of a model (keys + file sizes + which one is selected), order independent. */
+export function variantsSignature(variants) {
+  if (!Array.isArray(variants) || !variants.length) return '';
+  return variants.map((v) => v.selected ? `${v.key}:${v.sizeBytes}:selected` : `${v.key}:${v.sizeBytes}`).sort().join('|');
+}
+
+/** The variant list a profile preset stores: key and file size, sorted by key, with the selected one flagged. */
+function storedVariants(variants) {
+  if (!Array.isArray(variants)) return null;
+  return variants.map((v) => {
+    const obj = { key: v.key, sizeBytes: v.sizeBytes };
+    if (v.selected) obj.selected = true;
+    return obj;
+  }).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+}
+
+/** Return the preset if it exists and was measured on this hardware/model/variants file. */
+export async function findPreset({ engine, modelKey, ctx, hw, modelBytes, profile: rawProfile = DEFAULT_PROFILE, variants }) {
+  const profile = normalizeProfile(rawProfile);
+  // A preset without a profile field is a balanced preset.
+  const p = await readJson(presetPath(engine, modelKey, ctx, profile));
+  if (!p) return { preset: null, reason: 'none' };
+  if (p.fingerprint !== hardwareFingerprint(hw)) return { preset: null, stale: p, reason: 'hardware' };
+  if (profile !== DEFAULT_PROFILE && Array.isArray(variants)) {
+    const signature = variantsSignature(variants);
+    if (signature !== variantsSignature(p.variants)) {
+      return { preset: null, stale: p, reason: 'variants' };
+    }
+    // Engines report [] when listing fails: an empty signature proves nothing, so the model file size decides.
+    if (signature) return { preset: p, reason: 'hit' };
+  }
+  if (modelBytes && p.modelBytes && p.modelBytes !== modelBytes) {
+    return { preset: null, stale: p, reason: 'model' };
+  }
+  return { preset: p, reason: 'hit' };
+}
+
+/** Save the winner of a measurement as the preset of its profile. */
+export async function savePreset({ engine, modelKey, ctx, hw, modelBytes, best, results, profile: rawProfile = DEFAULT_PROFILE, variant = null, variants = null }) {
+  // An unknown profile is stored as balanced, never as part of a file name.
+  const profile = normalizeProfile(rawProfile);
+  const { placement, score, ...candidate } = best.candidate;
+  const preset = {
+    version: 1,
+    engine,
+    model: modelKey,
+    ctx,
+    profile,
+    modelBytes: modelBytes || null,
+    fingerprint: hardwareFingerprint(hw),
+    hardware: { cpu: hw.cpu.brand, gpus: hw.gpus.map((g) => ({ index: g.index, name: g.name, totalBytes: g.totalBytes, pcieGen: g.pcieGen, pcieWidth: g.pcieWidth })) },
+    createdAt: new Date().toISOString(),
+    candidate,
+    bench: best.bench,
+    tried: (results || []).map((r) => ({ id: r.candidate.id, ok: r.bench.ok, error: r.bench.error || null, shortTps: r.bench.short?.genTps ?? null, deepTps: r.bench.deep?.genTps ?? null })),
+  };
+  if (profile !== DEFAULT_PROFILE) {
+    Object.assign(preset, { variant, variants: storedVariants(variants) });
+  }
+  const file = presetPath(engine, modelKey, ctx, profile);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(preset, null, 2));
+  return { file, preset };
+}
+
+/** All presets for a model (to show which contexts and profiles are already tuned). */
+export async function listPresets({ engine, modelKey } = {}) {
+  const dir = presetsDir();
+  const files = await fs.readdir(dir).catch(() => []);
+  const out = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const p = await readJson(path.join(dir, f));
+    if (!p) continue;
+    if (engine && p.engine !== engine) continue;
+    if (modelKey && p.model !== modelKey) continue;
+    out.push({ file: path.join(dir, f), engine: p.engine, model: p.model, ctx: p.ctx, profile: p.profile || 'balanced', variant: p.variant?.key || null, createdAt: p.createdAt, fingerprint: p.fingerprint, kvType: p.candidate.kvType, fullOffload: p.candidate.fullOffload, shortTps: p.bench?.short?.genTps, deepTps: p.bench?.deep?.genTps });
+  }
+  return out.sort((a, b) => a.ctx - b.ctx || a.profile.localeCompare(b.profile));
+}