llm-tuner 0.1.0

package/src/core/profiles.js

@@ -0,0 +1,137 @@
+import { KV_TYPES, placeLayers } from './estimator.js';
+
+// Load profiles: what the tuner optimizes for. Lossless choices (layer placement, GPU order,
+// threads) apply to every profile; a profile only governs the lossy ones (weight quantization
+// and KV cache type).
+export const PROFILES = Object.freeze(['speed', 'balanced', 'quality']);
+export const DEFAULT_PROFILE = 'balanced';
+
+/** Returns the profile or the default if invalid. */
+export function normalizeProfile(p) {
+  return PROFILES.includes(p) ? p : DEFAULT_PROFILE;
+}
+
+// KV cache types precise enough for the quality profile.
+export const QUALITY_KV_TYPES = Object.freeze(['f16', 'q8_0']);
+
+/** Returns allowed KV types for a profile. */
+export function kvTypesFor(profile, engineKvTypes) {
+  if (profile === 'quality') {
+    const allowed = engineKvTypes.filter((k) => QUALITY_KV_TYPES.includes(k));
+    if (allowed.length > 0) return allowed;
+  }
+  return engineKvTypes;
+}
+
+/** Checks if a candidate meets the quality profile criteria. */
+export function meetsQuality(candidate) {
+  return candidate.fullOffload === true && !candidate.cpuMoeLayers && QUALITY_KV_TYPES.includes(candidate.kvType);
+}
+
+const tps = (r) => r.bench.deep?.genTps ?? r.bench.short.genTps;
+const kvQuality = (r) => KV_TYPES[r.candidate.kvType].quality;
+// Best element by a comparator, without touching the input (ties keep input order).
+const top = (list, compare) => [...list].sort(compare)[0] || null;
+
+/** Pick the winner of a measurement with the rule of the profile. */
+export function pickBest(results, profile = DEFAULT_PROFILE) {
+  const ok = results.filter((r) => r.bench?.ok);
+  const balanced = (a, b) => tps(b) * kvQuality(b) - tps(a) * kvQuality(a);
+  if (profile === 'speed') return top(ok, (a, b) => tps(b) - tps(a));
+  if (profile === 'quality') {
+    const precise = ok.filter((r) => meetsQuality(r.candidate));
+    if (precise.length > 0) return top(precise, (a, b) => kvQuality(b) - kvQuality(a) || tps(b) - tps(a));
+  }
+  return top(ok, balanced);
+}
+
+/** True when the model fits fully on GPU with at least one of the KV types. */
+export function fitsFullyOnGpu(meta, hw, { ctx, kvTypes }) {
+  return kvTypes.some((kvType) => placeLayers(meta, hw.gpus, { ctx, kvType }).fullOffload);
+}
+
+const selectedVariant = (variants) => variants.find((v) => v.selected) || variants[0] || null;
+
+// Lightest first. Bits per weight orders variants; file size is the fallback when any lacks it.
+const byWeight = (variants) => {
+  const fallback = variants.some((v) => v.meta.bitsPerWeight == null);
+  return [...variants].sort((a, b) => fallback ? a.meta.fileBytes - b.meta.fileBytes : a.meta.bitsPerWeight - b.meta.bitsPerWeight);
+};
+
+/** Pick the model variant a profile loads (or recommends), with the reason as a code. */
+export function pickVariant(profile, variants, hw, { ctx, kvTypes }) {
+  if (!variants.length) return { variant: null, reasonCode: 'profile.variant.none', fallback: false };
+  if (profile === 'speed') return { variant: byWeight(variants)[0], reasonCode: 'profile.variant.lightest', fallback: false };
+  if (profile === 'quality') {
+    const allowed = kvTypesFor('quality', kvTypes);
+    const heaviestFit = byWeight(variants).reverse().find((v) => fitsFullyOnGpu(v.meta, hw, { ctx, kvTypes: allowed }));
+    return heaviestFit
+      ? { variant: heaviestFit, reasonCode: 'profile.variant.heaviestFit', fallback: false }
+      : { variant: selectedVariant(variants), reasonCode: 'profile.variant.noFullGpu', fallback: true };
+  }
+  return { variant: selectedVariant(variants), reasonCode: 'profile.variant.selected', fallback: false };
+}
+
+/** Recommend the highest-quality profile whose outcome stays fully on GPU. */
+export function recommendProfile(variants, hw, { ctx, kvTypes }) {
+  const quality = pickVariant('quality', variants, hw, { ctx, kvTypes });
+  if (quality.variant && !quality.fallback) return { profile: 'quality', reasonCode: 'profile.recommend.qualityFits' };
+  const selected = selectedVariant(variants);
+  if (selected && fitsFullyOnGpu(selected.meta, hw, { ctx, kvTypes })) {
+    return { profile: 'balanced', reasonCode: 'profile.recommend.balancedFits' };
+  }
+  return { profile: 'speed', reasonCode: 'profile.recommend.partialOffload' };
+}
+
+// A GPU counts as busy above this fraction of its memory in use; a desktop compositor alone stays below it.
+export const VRAM_BUSY_FRACTION = 0.2;
+
+/** True when at least one GPU has more than `fraction` of its memory in use. */
+export function vramInUse(hw, fraction = VRAM_BUSY_FRACTION) {
+  if (!hw || !Array.isArray(hw.gpus) || hw.gpus.length === 0) return false;
+  return hw.gpus.some((gpu) => {
+    if (!gpu || !Number.isFinite(gpu.usedBytes) || !Number.isFinite(gpu.totalBytes)) return false;
+    return gpu.usedBytes > gpu.totalBytes * fraction;
+  });
+}
+
+// Heavier quantizations worth hinting at, with their bits per weight.
+// Source: llama.cpp tools/quantize/README.md, Llama-3.1-8B table.
+export const HINT_TARGETS = Object.freeze([
+  { quant: 'Q8_0', bitsPerWeight: 8.5008 },
+  { quant: 'Q6_K', bitsPerWeight: 6.5633 },
+  { quant: 'Q5_K_M', bitsPerWeight: 5.7036 },
+]);
+
+// A hint must be at least 5% heavier than the file on disk, because measured bits per weight
+// are rounded and the targets come from another model.
+export const HINT_MIN_GAIN = 1.05;
+
+/** Heavier quantizations, not downloaded, that would still fit fully on GPU (sizes estimated). */
+export function variantHints(meta, hw, { ctx, kvTypes, downloadedQuants = [] }) {
+  if (!meta.bitsPerWeight) return [];
+  const allowed = kvTypesFor('quality', kvTypes);
+  const downloaded = downloadedQuants.map((q) => String(q).toLowerCase());
+  const results = [];
+  for (const target of HINT_TARGETS) {
+    if (target.bitsPerWeight < meta.bitsPerWeight * HINT_MIN_GAIN) continue;
+    if (downloaded.includes(target.quant.toLowerCase())) continue;
+    const scale = target.bitsPerWeight / meta.bitsPerWeight;
+    const scaled = {
+      ...meta,
+      layerBytes: meta.layerBytes.map((b) => b * scale),
+      layerExpertBytes: meta.layerExpertBytes.map((b) => b * scale),
+      outputBytes: meta.outputBytes * scale,
+      embdBytes: meta.embdBytes * scale,
+      fileBytes: meta.fileBytes * scale,
+    };
+    if (fitsFullyOnGpu(scaled, hw, { ctx, kvTypes: allowed })) {
+      results.push({
+        quant: target.quant,
+        bitsPerWeight: target.bitsPerWeight,
+        estimatedBytes: Math.round(scaled.fileBytes),
+      });
+    }
+  }
+  return results;
+}

package/src/core/settings.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { configDir, readJson } from './util.js';
+import { normalizeLocale } from '../i18n/core.js';
+import { PROFILES } from './profiles.js';
+
+// User preferences shared by the CLI, the web UI and Electron.
+
+export const THEMES = Object.freeze(['system', 'light', 'dark']);
+export const DEFAULT_THEME = 'system';
+
+/** Returns the value if it is a valid profile, otherwise null. */
+function storedProfile(value) {
+  return PROFILES.includes(value) ? value : null;
+}
+
+export function normalizeTheme(theme) {
+  return THEMES.includes(theme) ? theme : DEFAULT_THEME;
+}
+
+export const settingsPath = () => path.join(configDir(), 'settings.json');
+
+/** Current settings. A missing, corrupt or hand-edited file yields the defaults; never throws. */
+export async function readSettings() {
+  const s = await readJson(settingsPath(), null);
+  return {
+    lang: normalizeLocale(s?.lang),
+    theme: normalizeTheme(s?.theme),
+    profile: storedProfile(s?.profile),
+  };
+}
+
+/** Merge `patch` into the saved settings and write them. */
+export async function writeSettings(patch) {
+  const current = await readJson(settingsPath(), null);
+  const base = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+  const lang = normalizeLocale(patch?.lang !== undefined ? patch.lang : base.lang);
+  const theme = normalizeTheme(patch?.theme !== undefined ? patch.theme : base.theme);
+  const profile = storedProfile(patch?.profile) ?? base.profile;
+  const next = { ...base, ...patch, lang, theme, profile };
+  await fs.mkdir(configDir(), { recursive: true });
+  await fs.writeFile(settingsPath(), JSON.stringify(next, null, 2));
+  return { lang: next.lang, theme: next.theme, profile: storedProfile(next.profile) };
+}

package/src/core/tuner.js

@@ -0,0 +1,305 @@
+import { EventEmitter } from 'node:events';
+import { detectHardware } from './hardware.js';
+import { planCandidates, maxFullOffloadContext } from './estimator.js';
+import { findPreset, savePreset, presetPath } from './presets.js';
+import { PROFILES, DEFAULT_PROFILE, normalizeProfile, kvTypesFor, meetsQuality, pickBest, pickVariant, recommendProfile, variantHints, vramInUse } from './profiles.js';
+import { lmstudio } from './engines/lmstudio.js';
+import { ollama } from './engines/ollama.js';
+import { TunerError, benchError } from './errors.js';
+
+export { pickBest };
+export const ENGINES = { lmstudio, ollama };
+
+/** Detect both engines and recommend one. */
+export async function detectEngines(hw) {
+  const out = [];
+  for (const e of Object.values(ENGINES)) {
+    let detection;
+    try { detection = await e.detect(); } catch (err) { detection = { installed: false, error: String(err.message || err) }; }
+    out.push({ id: e.id, name: e.name, detection });
+  }
+  const installed = out.filter((e) => e.detection.installed);
+  let recommended = null;
+  let reasonCode;
+  let reasonParams = {};
+  if (installed.length === 1) {
+    recommended = installed[0].id;
+    reasonCode = 'engine.reason.onlyInstalled';
+    reasonParams = { name: installed[0].name };
+  } else if (installed.length === 2) {
+    // LM Studio lets us fix KV type and GPU order per model and benchmarks the exact
+    // binary it will run; Ollama makes those server-wide. Prefer LM Studio for multi-GPU.
+    const multiGpu = (hw?.gpus?.length || 0) > 1;
+    recommended = multiGpu ? 'lmstudio' : 'ollama';
+    reasonCode = multiGpu ? 'engine.reason.multiGpu' : 'engine.reason.singleGpu';
+  } else {
+    recommended = (hw?.gpus?.length || 0) > 1 ? 'lmstudio' : 'ollama';
+    reasonCode = 'engine.reason.noneInstalled';
+  }
+  return { engines: out, recommended, reasonCode, reasonParams };
+}
+
+export class Tuner extends EventEmitter {
+  constructor(engineId, detection, hw) {
+    super();
+    this.engine = ENGINES[engineId];
+    if (!this.engine) throw new TunerError('errors.unknownEngine', { engine: engineId });
+    this.ctx = { detection, hw };
+    this.hw = hw;
+  }
+
+  static async create(engineId) {
+    if (!ENGINES[engineId]) throw new TunerError('errors.unknownEngine', { engine: engineId });
+    const hw = await detectHardware();
+    const detection = await ENGINES[engineId].detect();
+    return new Tuner(engineId, detection, hw);
+  }
+
+  log(type, data = {}) { this.emit('progress', { type, ...data, at: Date.now() }); }
+
+  listModels() { return this.engine.listModels(this.ctx); }
+
+  async modelInfo(key) {
+    const meta = await this.engine.modelMeta(this.ctx, key);
+    return { key, meta };
+  }
+
+  chat(model, messages) {
+    return this.engine.chat(this.ctx, model, messages);
+  }
+
+  /** Downloaded variants of a model with their metadata; never empty: at least the chosen key itself. */
+  async variants(key) {
+    const listed = (await this.engine.listVariants?.(this.ctx, key)) ?? [];
+    const out = [];
+    for (const item of listed) {
+      try {
+        const meta = await this.engine.modelMeta(this.ctx, item.key);
+        out.push({ key: item.key, quant: item.quant, sizeBytes: item.sizeBytes, selected: item.selected, meta });
+      } catch {
+        // A variant whose file cannot be read is not a candidate.
+      }
+    }
+    if (out.length > 0) {
+      return out;
+    }
+    const { meta } = await this.modelInfo(key);
+    return [{ key, quant: null, sizeBytes: meta.fileBytes, selected: true, meta }];
+  }
+
+  /** What each profile would load for a model and context, without measuring or unloading anything. */
+  async profilePlan(key, ctx) {
+    const variants = await this.variants(key);
+    const { kvTypes } = this.engine.capabilities;
+    const variantSelect = !!this.engine.capabilities.variantSelect;
+    const selected = variants.find((v) => v.selected) ?? variants[0];
+    const opts = { ctx, kvTypes };
+    const profiles = {};
+    // An engine that cannot select variants loads the selected one and only recommends the pick.
+    for (const profile of PROFILES) {
+      const pick = pickVariant(profile, variants, this.hw, opts);
+      profiles[profile] = {
+        variant: pick.variant.key,
+        quant: pick.variant.quant,
+        reasonCode: pick.reasonCode,
+        fallback: pick.fallback,
+        kvTypes: kvTypesFor(profile, kvTypes),
+        loads: variantSelect ? pick.variant.key : selected.key,
+        recommendSwitch: !variantSelect && pick.variant.key !== selected.key,
+      };
+    }
+    return {
+      variants: variants.map((v) => ({ key: v.key, quant: v.quant, sizeBytes: v.sizeBytes, selected: v.selected, bitsPerWeight: v.meta.bitsPerWeight ?? null })),
+      variantSelect,
+      recommended: recommendProfile(variants, this.hw, opts),
+      profiles,
+      hints: variantHints(selected.meta, this.hw, { ...opts, downloadedQuants: variants.map((v) => v.quant).filter(Boolean) }),
+      // The plan uses the VRAM that is free now; a real load unloads the engine's models first.
+      vramBusy: vramInUse(this.hw),
+    };
+  }
+
+  /** Pick the variant a non-balanced profile measures and loads with the hardware as it is now, and announce it. */
+  profileTarget(key, ctx, profile, model, variants) {
+    const { kvTypes } = this.engine.capabilities;
+    const canSelect = !!this.engine.capabilities.variantSelect;
+    const pick = pickVariant(profile, variants, this.hw, { ctx, kvTypes });
+    const selected = variants.find((v) => v.selected);
+
+    // An engine that cannot select variants always loads the one selected in the engine, under the chosen key.
+    const targetKey = canSelect ? pick.variant.key : key;
+    const loaded = canSelect ? pick.variant : (selected ?? { quant: null, sizeBytes: model.meta.fileBytes });
+    // The announced variant travels in every profile event, so an interface never has to remember an earlier one.
+    const picked = { key: pick.variant.key, quant: pick.variant.quant, sizeBytes: pick.variant.sizeBytes };
+
+    this.log('variant-picked', {
+      profile,
+      variant: picked,
+      reasonCode: pick.reasonCode,
+      loads: targetKey,
+      recommendSwitch: !canSelect && pick.variant.key !== (selected?.key ?? key),
+    });
+
+    if (pick.fallback) {
+      this.log('profile-fallback', { profile, reasonCode: pick.reasonCode, variant: picked });
+    }
+
+    return {
+      key: targetKey,
+      fallback: pick.fallback,
+      variant: { key: targetKey, quant: loaded.quant, sizeBytes: loaded.sizeBytes },
+      picked,
+    };
+  }
+
+  /** Announce the variant a profile preset stored: on a preset hit nothing is picked. */
+  presetTarget(key, profile, model, preset) {
+    const canSelect = !!this.engine.capabilities.variantSelect;
+    const stored = { key, quant: null, sizeBytes: model.meta.fileBytes, ...preset.variant };
+    // An engine that cannot select variants always loads under the chosen key.
+    const targetKey = canSelect ? stored.key : key;
+    const variant = { key: targetKey, quant: stored.quant, sizeBytes: stored.sizeBytes };
+
+    this.log('variant-picked', {
+      profile,
+      variant,
+      reasonCode: 'profile.variant.preset',
+      loads: targetKey,
+      recommendSwitch: false,
+    });
+
+    return {
+      key: targetKey,
+      fallback: false,
+      variant,
+    };
+  }
+
+  /** Unload the engine's loaded models and re-detect the hardware, so the free-VRAM snapshot is realistic. */
+  async freeVram() {
+    this.log('status', { code: 'status.freeingVram' });
+    await this.engine.prepare(this.ctx);
+    this.hw = this.ctx.hw = await detectHardware();
+  }
+
+  /**
+   * Estimate candidates for a context length. With `unload`, the engine's loaded
+   * models are unloaded first so the free-VRAM snapshot is realistic.
+   * The profile restricts the KV cache types.
+   */
+  async plan(key, ctx, { unload = false, profile = DEFAULT_PROFILE } = {}) {
+    if (unload) await this.freeVram();
+    const model = await this.modelInfo(key);
+    const engineKvTypes = this.engine.capabilities.kvTypes;
+    // The profile restricts the KV cache types that are planned; the context limits cover every engine type.
+    const kvTypes = kvTypesFor(normalizeProfile(profile), engineKvTypes);
+    const candidates = planCandidates(model.meta, this.hw, { ctx, kvTypes, allowCpuMoe: this.engine.capabilities.cpuMoe });
+    const maxContext = Object.fromEntries(engineKvTypes.map((k) => [k, maxFullOffloadContext(model.meta, this.hw, k)]));
+    return { model, candidates, maxContext, hw: this.hw };
+  }
+
+  /** Estimate, benchmark the top candidates for real, and return a report. The profile decides the winner. */
+  async run(key, ctx, { maxCandidates = 3, depthFraction = 0.5, genTokens = 200, profile: requested = DEFAULT_PROFILE } = {}) {
+    const profile = normalizeProfile(requested);
+    this.log('status', { code: 'status.engine', params: { name: this.engine.name } });
+    const { model, candidates, maxContext } = await this.plan(key, ctx, { unload: true, profile });
+    const model2 = { key, meta: model.meta };
+    const toTest = candidates.slice(0, maxCandidates);
+    this.log('plan', { candidates: toTest.map(slim), maxContext });
+
+    const depthTokens = Math.floor(ctx * depthFraction);
+    const results = [];
+    for (const [i, c] of toTest.entries()) {
+      this.log('candidate-start', { index: i, total: toTest.length, candidate: slim(c) });
+      let bench;
+      try {
+        bench = await this.engine.benchmark(this.ctx, model2, c, {
+          depthTokens, genTokens,
+          onProgress: (p) => this.log('bench-progress', { index: i, ...p }),
+        });
+      } catch (err) {
+        bench = err?.name === 'TunerError' ? benchError(err.code, err.params) : { ok: false, error: String(err.message || err) };
+      }
+      results.push({ candidate: c, bench });
+      this.log('candidate-done', { index: i, candidate: slim(c), bench });
+    }
+    const best = pickBest(results, profile);
+    const report = { engine: this.engine.id, model: key, ctx, profile, hw: this.hw, maxContext, results: results.map((r) => ({ candidate: slim(r.candidate), bench: r.bench })), best: best ? { candidate: best.candidate, bench: best.bench } : null };
+    this.log('done', { best: report.best && { candidate: slim(best.candidate), bench: best.bench } });
+    this.lastReport = { ...report, modelObj: model2 };
+    return report;
+  }
+
+  /**
+   * Main flow behind the "Load" button:
+   * preset for (model, ctx, hardware, profile)? -> apply + load.
+   * Otherwise benchmark -> save preset -> apply + load.
+   * Balanced measures and loads the key the user chose; speed and quality reuse the variant stored in
+   * the preset, or pick one once the VRAM is free.
+   */
+  async load(key, ctx, { force = false, dryRun = false, maxCandidates = 3, depthFraction = 0.5, measure = true, confirmApply = async () => true, profile: requested = DEFAULT_PROFILE } = {}) {
+    const profile = normalizeProfile(requested);
+    const model = await this.modelInfo(key);
+    const modelBytes = model.meta.fileBytes;
+    // Listing the variants of a non-balanced profile needs no hardware; picking one does, so the pick waits.
+    const variants = profile === DEFAULT_PROFILE ? null : await this.variants(key);
+    const listed = variants?.map((v) => ({ key: v.key, sizeBytes: v.sizeBytes, selected: v.selected }));
+    // A profile preset is keyed by the key the user chose plus the profile, and goes stale with the variant list or its selected entry.
+    const keyed = variants ? { profile, variants: listed } : {};
+    let target = null;
+    let source = 'preset';
+    let candidate;
+    let report = null;
+    let found = force ? { preset: null, reason: 'forced' } : await findPreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, ...keyed });
+
+    if (found.preset) {
+      candidate = found.preset.candidate;
+      this.log('preset-hit', { preset: found.preset, file: presetPath(this.engine.id, key, ctx, profile) });
+      // The preset remembers which variant it measured: nothing is picked and no VRAM is freed.
+      if (variants) target = this.presetTarget(key, profile, model, found.preset);
+    } else {
+      source = 'benchmark';
+      const code = { none: 'status.searchNone', hardware: 'status.searchHardware', model: 'status.searchModel', forced: 'status.searchForced', variants: 'status.searchVariants' }[found.reason];
+      this.log('status', { code });
+      if (variants) {
+        // The pick depends on the free VRAM, so the engine's models are unloaded before it.
+        await this.freeVram();
+        target = this.profileTarget(key, ctx, profile, model, variants);
+      }
+      report = await this.run(target?.key ?? key, ctx, { maxCandidates, depthFraction, profile });
+      if (!report.best) throw new TunerError('errors.noConfigWorked');
+      candidate = report.best.candidate;
+      // Quality found no configuration that keeps its promise: say so once.
+      if (profile === 'quality' && !target.fallback && !meetsQuality(candidate)) this.log('profile-fallback', { profile, reasonCode: 'profile.fallback.noFullGpuConfig', variant: target.picked });
+      if (!dryRun) {
+        const saved = await savePreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, best: report.best, results: this.lastReport.results, ...(target ? { profile, variant: target.variant, variants: listed } : {}) });
+        this.log('preset-saved', { file: saved.file, preset: saved.preset });
+      }
+    }
+
+    // The variant a profile picked is applied and loaded with its own metadata.
+    const loadKey = target?.key ?? key;
+    const meta = loadKey === key ? model.meta : variants?.find((v) => v.key === loadKey)?.meta ?? (await this.modelInfo(loadKey)).meta;
+    const modelObj = { key: loadKey, meta };
+    const preview = await this.engine.apply(this.ctx, modelObj, candidate, { dryRun: true });
+    if (dryRun) return { source, candidate: slim(candidate), report, preview, profile, variant: loadKey };
+    if (!(await confirmApply(preview))) return { source, candidate: slim(candidate), report, preview, applied: false, profile, variant: loadKey };
+
+    this.log('status', { code: 'status.applying' });
+    const applied = await this.engine.apply(this.ctx, modelObj, candidate, { useSudo: true, skipIfApplied: source === 'preset' });
+    this.log('applied', { result: applied });
+    if (applied.pendingCommands?.length) return { source, candidate: slim(candidate), report, applied, loaded: null, profile, variant: loadKey };
+
+    this.log('status', { code: 'status.loading' });
+    this.ctx.detection = await this.engine.detect();
+    const loaded = await this.engine.load(this.ctx, modelObj, { candidate, depthTokens: 0, genTokens: measure ? 200 : 1, onProgress: (p) => this.log('bench-progress', p) });
+    this.log('loaded', { bench: loaded });
+    return { source, candidate: slim(candidate), report, applied, loaded, profile, variant: loadKey };
+  }
+}
+
+/** Candidate without the bulky placement internals, for UIs and logs. */
+export function slim(c) {
+  const { placement, score, ...rest } = c;
+  return { ...rest, kvBytes: placement?.kvBytes, layersPerGpu: placement?.layersPerGpu };
+}

package/src/core/util.js

@@ -0,0 +1,148 @@
+import { execFile, spawn } from 'node:child_process';
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const PLATFORM = process.platform; // 'linux' | 'win32' | 'darwin'
+export const MiB = 1024 * 1024;
+export const GiB = 1024 * MiB;
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Run a command, resolve {code, stdout, stderr}; never rejects. */
+export function run(cmd, args = [], opts = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 30_000, maxBuffer: 64 * MiB, windowsHide: true, ...opts }, (err, stdout, stderr) => {
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? ''), error: err });
+    });
+  });
+}
+
+/** Locate an executable on PATH (plus extra candidate paths). */
+export async function which(name, extra = []) {
+  const exts = PLATFORM === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const c of extra) if (await exists(c)) return c;
+  for (const d of dirs) {
+    for (const e of exts) {
+      const p = path.join(d, name + e);
+      if (await exists(p)) return p;
+    }
+  }
+  return null;
+}
+
+export async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+export async function readJson(p, fallback = null) {
+  try { return JSON.parse(await fs.readFile(p, 'utf8')); } catch { return fallback; }
+}
+
+/** Write JSON atomically, keeping a timestamped backup of the previous file. */
+export async function writeJsonWithBackup(p, data, { indent = 2 } = {}) {
+  let backup = null;
+  if (await exists(p)) {
+    backup = `${p}.bak-llm-tuner-${timestamp()}`;
+    await fs.copyFile(p, backup);
+  } else {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+  }
+  const tmp = `${p}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, indent ? JSON.stringify(data, null, indent) : JSON.stringify(data));
+  await fs.rename(tmp, p);
+  return backup;
+}
+
+export function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+export function fmtBytes(b) {
+  if (b == null || Number.isNaN(b)) return '?';
+  if (Math.abs(b) >= GiB) return `${(b / GiB).toFixed(2)} GiB`;
+  return `${Math.round(b / MiB)} MiB`;
+}
+
+export const homeDir = () => os.homedir();
+
+/** Per-user config folder (presets, settings). LLM_TUNER_CONFIG_DIR overrides it (used by tests). */
+export function configDir() {
+  if (process.env.LLM_TUNER_CONFIG_DIR) return process.env.LLM_TUNER_CONFIG_DIR;
+  const base = PLATFORM === 'win32' ? (process.env.APPDATA || path.join(homeDir(), 'AppData', 'Roaming'))
+    : PLATFORM === 'darwin' ? path.join(homeDir(), 'Library', 'Application Support')
+    : (process.env.XDG_CONFIG_HOME || path.join(homeDir(), '.config'));
+  return path.join(base, 'llm-tuner');
+}
+
+/** Fetch JSON with timeout; returns null on network failure. */
+export async function fetchJson(url, { method = 'GET', body, timeout = 5000, headers = {} } = {}) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const res = await fetch(url, {
+      method,
+      signal: ctl.signal,
+      headers: body ? { 'Content-Type': 'application/json', ...headers } : headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch { /* not json */ }
+    return { ok: res.ok, status: res.status, json, text };
+  } catch (e) {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/** Find a free TCP port on localhost. */
+export async function freePort() {
+  const net = await import('node:net');
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+/** Spawn a long-running process, capturing its output into a ring buffer. */
+export function spawnLogged(cmd, args, opts = {}) {
+  const child = spawn(cmd, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+  const lines = [];
+  const push = (buf) => {
+    for (const l of String(buf).split(/\r?\n/)) if (l) { lines.push(l); if (lines.length > 400) lines.shift(); }
+  };
+  child.stdout?.on('data', push);
+  child.stderr?.on('data', push);
+  const exited = new Promise((r) => child.on('exit', (code, signal) => r({ code, signal })));
+  return { child, lines, exited };
+}
+
+export async function killProcess(child, graceMs = 5000) {
+  if (!child || child.exitCode !== null || child.signalCode) return;
+  child.kill(PLATFORM === 'win32' ? undefined : 'SIGTERM');
+  const done = await Promise.race([new Promise((r) => child.once('exit', () => r(true))), sleep(graceMs).then(() => false)]);
+  if (!done) child.kill('SIGKILL');
+}
+
+/** Sample overall CPU busy % between two os.cpus() snapshots (cross-platform). */
+export function cpuSnapshot() {
+  return os.cpus().map((c) => ({ ...c.times }));
+}
+export function cpuBusyPercent(a, b) {
+  let idle = 0, total = 0;
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    const ta = a[i], tb = b[i];
+    const t = (tb.user - ta.user) + (tb.nice - ta.nice) + (tb.sys - ta.sys) + (tb.idle - ta.idle) + (tb.irq - ta.irq);
+    idle += tb.idle - ta.idle;
+    total += t;
+  }
+  return total > 0 ? 100 * (1 - idle / total) : 0;
+}

package/src/i18n/core.js

@@ -0,0 +1,11 @@
+// Locale helpers shared by Node and the browser (served at /i18n/core.js). No imports.
+
+export const LOCALES = ['en', 'es'];
+export const DEFAULT_LOCALE = 'en';
+
+export const normalizeLocale = (value) => (LOCALES.includes(value) ? value : DEFAULT_LOCALE);
+
+/** Replace {name} with params.name. Missing or null params stay visible as {name}. */
+export function format(template, params = {}) {
+  return String(template).replace(/\{(\w+)\}/g, (match, name) => (params?.[name] ?? null) === null ? match : String(params[name]));
+}