turbollm 1.0.0 → 1.2.1

package/README.md

@@ -225,6 +225,10 @@ the UI when something fails to load.
 ## Auto-tuning & performance
 
 - **Auto-benchmark on load** derives fast defaults for your exact GPU.
+- **Recommended sampling from the model card** — auto-tune reads the model's Hugging Face card
+  (falling back to the original model behind a requant) and prefills the author's recommended
+  `temperature / top_k / top_p / min_p`, shown in the results table and applied on Save. No
+  recommendation → your sampling is left untouched.
 - **Real measured tokens/sec** in the model list — **live** while a model is generating,
   **last-session** when it's idle (never a synthetic estimate).
 - **Full load-parameter UI**, a superset of what other tools expose:

package/dist/cli.js

@@ -2363,6 +2363,71 @@ var UpdateScheduler = class {
   }
 };
 
+// src/app-update.ts
+function compareAppVersions(installed, latest) {
+  return comparePipVersions(installed, latest);
+}
+var APP_PACKAGE = "turbollm";
+async function fetchNpmLatest(signal) {
+  const res = await fetch(`https://registry.npmjs.org/${APP_PACKAGE}/latest`, {
+    headers: { Accept: "application/json", "User-Agent": "turbollm" },
+    signal
+  });
+  if (!res.ok) throw new Error(`npm query failed: HTTP ${res.status}`);
+  const data = await res.json();
+  return data.version ?? "";
+}
+async function computeAppUpdateStatus(installed, fetcher = fetchNpmLatest, signal) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  let latest;
+  try {
+    latest = await fetcher(signal);
+  } catch {
+    return { installed, latest: null, hasUpdate: false, checkedAt, error: "offline", comparable: false };
+  }
+  if (!latest) {
+    return { installed, latest: null, hasUpdate: false, checkedAt, error: "offline", comparable: false };
+  }
+  const cmp = compareAppVersions(installed, latest);
+  return {
+    installed,
+    latest,
+    hasUpdate: cmp === "newer",
+    checkedAt,
+    comparable: cmp !== "unknown"
+  };
+}
+var APP_UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var AppUpdateChecker = class {
+  constructor(installed, fetcher = fetchNpmLatest) {
+    this.installed = installed;
+    this.fetcher = fetcher;
+  }
+  installed;
+  fetcher;
+  cache = null;
+  /** The last cached status, or null when never checked. */
+  get() {
+    return this.cache;
+  }
+  /** True when there's no cached status or it's older than the 24h TTL — i.e. a
+   *  re-check is warranted. `now` is injectable for tests. */
+  isStale(now = Date.now()) {
+    if (!this.cache) return true;
+    const at = Date.parse(this.cache.checkedAt);
+    return !Number.isFinite(at) || now - at >= APP_UPDATE_CHECK_INTERVAL_MS;
+  }
+  /** Re-check and cache the result. On an offline result we KEEP a prior successful
+   *  status (don't overwrite a real latest with "couldn't check"); the UI's relative
+   *  time naturally ages. Returns the status used. */
+  async check(signal) {
+    const fresh = await computeAppUpdateStatus(this.installed, this.fetcher, signal);
+    if (fresh.error === "offline" && this.cache && this.cache.latest !== null) return this.cache;
+    this.cache = fresh;
+    return fresh;
+  }
+};
+
 // src/engines/update-apply.ts
 import { rmSync as rmSync5 } from "fs";
 import { join as join9 } from "path";
@@ -3784,6 +3849,7 @@ var ConversationStore = class {
 // src/hf/hf.ts
 var BASE = "https://huggingface.co";
 var CACHE_TTL_MS = 5 * 60 * 1e3;
+var CARD_EXTRACT_MAX = 12e4;
 var HfError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -3862,22 +3928,50 @@ var HfClient = class {
       ...safetensors ? { safetensors } : {}
     };
   }
+  /** Public model-card fetch (ADR-099): the cleaned README for `owner/repo`, or '' when
+   *  missing/unreachable. Used by auto-tune to read recommended sampling from the card.
+   *  Uses a LARGER cap than the display path: popular requanters (e.g. unsloth) put their
+   *  recommended-settings section in the BACK HALF of a long card, past the 12k display cap —
+   *  the extra window is what lets the heuristic actually find them (live-verified). */
+  fetchModelCard(repo) {
+    return this.getCard(repo, CARD_EXTRACT_MAX);
+  }
+  /** Resolve the upstream base model for a repo (ADR-099 base-model fallback): the `base_model`
+   *  declared in the repo's HF card metadata. Most local GGUFs are third-party requants
+   *  (lmstudio-community / unsloth / noctrex / …) whose card omits the author's recommended
+   *  sampling — but they name the ORIGINAL model, whose card has it. Returns `owner/name`, or null
+   *  when none is declared / unreachable. Handles the array form and the `base_model:[relation:]repo`
+   *  tag form. Cached via {@link getJson}. */
+  async baseModelOf(repo) {
+    try {
+      const info = await this.getJson(`${BASE}/api/models/${repo}`);
+      const bm = info.cardData?.base_model;
+      const first = Array.isArray(bm) ? bm[0] : bm;
+      if (typeof first === "string" && first.includes("/")) return first;
+      const tag = (info.tags ?? []).find((t) => t.startsWith("base_model:"));
+      const fromTag = tag ? tag.split(":").pop() ?? "" : "";
+      return fromTag.includes("/") ? fromTag : null;
+    } catch {
+      return null;
+    }
+  }
   /** Fetch the repo README (the model card), strip its YAML frontmatter, and cap the
-   *  length for display. Best-effort — a missing/unreachable README yields '' rather
-   *  than failing the whole repo-detail request. Cached like other HF reads. */
-  async getCard(repo) {
+   *  length. Best-effort — a missing/unreachable README yields '' rather than failing the
+   *  whole repo-detail request. The full (up to {@link CARD_EXTRACT_MAX}) card is cached and
+   *  each caller slices to its own `maxLen` (display 12k; extraction larger), so the two
+   *  paths share one fetch without the cache returning a too-short slice. */
+  async getCard(repo, maxLen = 12e3) {
     const url = `${BASE}/${repo}/raw/main/README.md`;
     const now = Date.now();
     const hit = this.cache.get(url);
-    if (hit && now - hit.at < CACHE_TTL_MS) return hit.value;
+    if (hit && now - hit.at < CACHE_TTL_MS) return hit.value.slice(0, maxLen);
     try {
       const res = await fetch(url, { headers: this.authHeaders(), redirect: "follow" });
       if (!res.ok) return "";
       const raw = await res.text();
-      const body3 = raw.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
-      const card = body3.slice(0, 12e3);
-      this.cache.set(url, { at: now, value: card });
-      return card;
+      const full = raw.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim().slice(0, CARD_EXTRACT_MAX);
+      this.cache.set(url, { at: now, value: full });
+      return full.slice(0, maxLen);
     } catch {
       return "";
     }
@@ -4345,6 +4439,110 @@ import { execFile as execFile6 } from "child_process";
 import { mkdirSync as mkdirSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "fs";
 import { join as join15 } from "path";
 import { randomUUID as randomUUID4 } from "crypto";
+
+// src/api/path-utils.ts
+function inferRepoFromPath(filePath, modelDirs) {
+  const norm = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
+  const fp = norm(filePath);
+  const seg = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+  for (const dir of modelDirs) {
+    const root = norm(dir);
+    if (!fp.toLowerCase().startsWith(root.toLowerCase() + "/")) continue;
+    const parts = fp.slice(root.length + 1).split("/");
+    if (parts.length >= 2 && seg.test(parts[0]) && seg.test(parts[1])) {
+      return `${parts[0]}/${parts[1]}`;
+    }
+    return null;
+  }
+  return null;
+}
+
+// src/models/card-sampling.ts
+var FIELDS = [
+  { key: "temp", alias: "temp(?:erature)?", min: 0, max: 2 },
+  { key: "topP", alias: "top[_\\-\\s]?p", min: 0, max: 1 },
+  { key: "topK", alias: "top[_\\-\\s]?k", min: 0, max: 1e3, integer: true },
+  { key: "minP", alias: "min[_\\-\\s]?p", min: 0, max: 1 }
+];
+var NUM = "(\\d*\\.?\\d+)";
+var SEP = "[\\s:=|*\"'`~]{0,6}";
+function clampCardSampling(s) {
+  const out = {};
+  for (const f of FIELDS) {
+    const v = s[f.key];
+    if (v == null || !Number.isFinite(v)) continue;
+    const n = f.integer ? Math.round(v) : v;
+    if (n < f.min || n > f.max) continue;
+    out[f.key] = n;
+  }
+  return out;
+}
+function parseCardSampling(card) {
+  const out = {};
+  if (!card) return out;
+  const prose = card.replace(/```[\s\S]*?```/g, " ").replace(/~~~[\s\S]*?~~~/g, " ");
+  for (const f of FIELDS) {
+    const re = new RegExp(`\\b${f.alias}\\b${SEP}${NUM}`, "i");
+    const m = re.exec(prose);
+    if (!m) continue;
+    const v = Number(m[1]);
+    if (Number.isFinite(v)) out[f.key] = v;
+  }
+  return clampCardSampling(out);
+}
+function hasAnySampling(s) {
+  return s.temp != null || s.topP != null || s.topK != null || s.minP != null;
+}
+function relevantCardExcerpt(card, maxLen = 8e3) {
+  if (card.length <= maxLen) return card;
+  const strong = /\b(?:recommended\s+(?:settings|sampling|parameters)|sampling\s+(?:settings|parameters|params)|best\s+practices?|generation\s+config)\b/i.exec(card);
+  const cue = strong ?? /\b(?:temp(?:erature)?|top[_\-\s]?[pk]|min[_\-\s]?p)\b/i.exec(card);
+  if (!cue || cue.index < maxLen) return card.slice(0, maxLen);
+  const start = Math.max(0, cue.index - Math.floor(maxLen * 0.3));
+  return card.slice(start, start + maxLen);
+}
+function buildCardExtractionPrompt(card) {
+  const trimmed = relevantCardExcerpt(card, 8e3);
+  return [
+    "Extract the model author's RECOMMENDED sampling settings from the model card below.",
+    "Output ONLY a single JSON object, no prose, with exactly these keys:",
+    '{"temperature": number|null, "top_k": number|null, "top_p": number|null, "min_p": number|null}',
+    "Use a value ONLY if the card explicitly recommends it; otherwise use null. Do not guess.",
+    "",
+    "MODEL CARD:",
+    trimmed
+  ].join("\n");
+}
+function parseLlmSampling(text) {
+  const m = /\{[\s\S]*\}/.exec(text);
+  if (!m) return {};
+  let obj;
+  try {
+    obj = JSON.parse(m[0]);
+  } catch {
+    return {};
+  }
+  if (typeof obj !== "object" || obj === null) return {};
+  const num = (v) => {
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+    if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) return Number(v);
+    return null;
+  };
+  const out = {};
+  const map = [
+    ["temperature", "temp"],
+    ["top_p", "topP"],
+    ["top_k", "topK"],
+    ["min_p", "minP"]
+  ];
+  for (const [jsonKey, field] of map) {
+    const v = num(obj[jsonKey]);
+    if (v !== null) out[field] = v;
+  }
+  return clampCardSampling(out);
+}
+
+// src/bench/bench.ts
 var READY_TIMEOUT_MS = 15e4;
 var PER_TEST_TIMEOUT_MS = 3 * 6e4;
 var PREFILL_GRACE_MS = 8e3;
@@ -4360,18 +4558,20 @@ var BenchError = class extends Error {
   code;
 };
 var BenchRunner = class {
-  constructor(manager2, store2, scanner2, registry2, version2) {
+  constructor(manager2, store2, scanner2, registry2, version2, hf2) {
     this.manager = manager2;
     this.store = store2;
     this.scanner = scanner2;
     this.registry = registry2;
     this.version = version2;
+    this.hf = hf2;
   }
   manager;
   store;
   scanner;
   registry;
   version;
+  hf;
   state = { running: false };
   cancelled = false;
   deadline = 0;
@@ -4464,13 +4664,38 @@ var BenchRunner = class {
     await this.manager.stopAndWait().catch(() => {
     });
     if (best) {
-      this.winning = { modelKey, profile: best.profile, cand: best.cand, entry, sys, engineVersion: active?.version ?? "" };
+      let recommended;
+      if (!this.cancelled && Date.now() <= this.deadline) {
+        recommended = await this.extractCardSampling(entry, best.profile, caps, sys).catch(() => void 0);
+        await this.manager.stopAndWait().catch(() => {
+        });
+      }
+      if (this.cancelled) {
+        this.state = { running: false, modelKey, done: true, candidates: results };
+        return;
+      }
+      const profile = recommended && hasAnySampling(recommended) ? { ...best.profile, sampling: { ...best.profile.sampling, ...recommended } } : best.profile;
+      this.winning = { modelKey, profile, cand: best.cand, entry, sys, engineVersion: active?.version ?? "" };
       this.state = {
         running: false,
         modelKey,
         done: true,
         bestTps: best.cand.tps ?? void 0,
-        result: { params: best.cand.params, tps: best.cand.tps ?? 0, ttftMs: best.cand.ttftMs ?? 0, vramMb: best.cand.vramMb },
+        result: {
+          params: best.cand.params,
+          tps: best.cand.tps ?? 0,
+          ttftMs: best.cand.ttftMs ?? 0,
+          vramMb: best.cand.vramMb,
+          // The full sampling that Save will persist (winning profile, card values merged in) so
+          // the results dialog can show the COMPLETE config — not just the card-derived delta.
+          sampling: {
+            temp: profile.sampling.temp,
+            topK: profile.sampling.topK,
+            topP: profile.sampling.topP,
+            minP: profile.sampling.minP
+          },
+          ...recommended && hasAnySampling(recommended) ? { recommendedSampling: recommended } : {}
+        },
         candidates: results
       };
     } else {
@@ -4837,6 +5062,101 @@ var BenchRunner = class {
     if (!t || typeof t.predicted_per_second !== "number") return null;
     return { tps: t.predicted_per_second, ttftMs: typeof t.prompt_ms === "number" ? t.prompt_ms : 0 };
   }
+  // ---- card-derived recommended sampling (ADR-099) ------------------------
+  /** Resolve the model's HF card and extract recommended sampling (temp/top_k/top_p/min_p).
+   *  Order (ADR-099): (1) heuristic on the LOCAL repo card; (2) heuristic on the BASE model's card
+   *  — most local GGUFs are third-party requants (lmstudio-community/unsloth/noctrex/…) whose card
+   *  omits the author's recommended sampling, but they declare the original model, whose card has
+   *  it (e.g. Gemma QAT → `google/gemma-…`); (3) LLM fallback (one reload) on the richer card for
+   *  prose-only recommendations. Returns undefined when the repo can't be resolved (hand-placed
+   *  file), no card is reachable, or nothing parseable is found — the caller then leaves sampling
+   *  at the resolved defaults. Never throws.
+   *
+   *  NOTE: a gated base model (e.g. Gemma's `google/…`) needs a configured HF token to fetch — without
+   *  one its card 401s and we fall through (sampling unchanged). */
+  async extractCardSampling(entry, winningProfile, caps, sys) {
+    const repo = inferRepoFromPath(entry.path, this.store.snapshot().modelDirs);
+    if (!repo) return void 0;
+    this.state = { ...this.state, step: "Reading model-card recommendations\u2026" };
+    const localCard = await this.hf.fetchModelCard(repo).catch(() => "");
+    const localH = parseCardSampling(localCard);
+    if (hasAnySampling(localH)) return localH;
+    let baseCard = "";
+    if (!this.cancelled) {
+      const baseRepo = await this.hf.baseModelOf(repo).catch(() => null);
+      if (baseRepo && baseRepo !== repo) {
+        baseCard = await this.hf.fetchModelCard(baseRepo).catch(() => "");
+        const baseH = parseCardSampling(baseCard);
+        if (hasAnySampling(baseH)) return baseH;
+      }
+    }
+    if (this.cancelled) return void 0;
+    const card = baseCard.length > localCard.length ? baseCard : localCard;
+    if (!card) return void 0;
+    const llm = await this.llmExtractSampling(entry, winningProfile, caps, sys, card).catch(() => void 0);
+    return llm && hasAnySampling(llm) ? llm : void 0;
+  }
+  /** LLM fallback for {@link extractCardSampling}: briefly reload the winning profile, ask the
+   *  model to extract recommended sampling as JSON, then stop. The recommendation is
+   *  model-specific (independent of the swept offload), so reusing the winning profile is exact.
+   *  Bounded by the readiness window + a short generation timeout; any failure → undefined, and
+   *  the engine is always left stopped. */
+  async llmExtractSampling(entry, profile, caps, sys, card) {
+    const active = this.registry.active();
+    if (!active) return void 0;
+    const opts = {
+      engine: active,
+      model: { key: entry.key, name: entry.name, quant: entry.quant, ctx: profile.ctx, vision: entry.vision },
+      modelPath: entry.path,
+      extraArgs: profileToArgs(profile, entry, caps, sys.cores)
+    };
+    try {
+      await this.manager.start(opts);
+    } catch {
+      return void 0;
+    }
+    const ready = await this.awaitReady(Date.now() + READY_TIMEOUT_MS);
+    const target = ready === "ok" ? this.manager.target() : null;
+    if (!target) {
+      await this.manager.stopAndWait().catch(() => {
+      });
+      return void 0;
+    }
+    const text = await this.chatText(target, buildCardExtractionPrompt(card), 200, 6e4).catch(() => null);
+    await this.manager.stopAndWait().catch(() => {
+    });
+    return text ? parseLlmSampling(text) : void 0;
+  }
+  /** One non-streaming completion that returns the generated TEXT (vs {@link chat}, which
+   *  returns timings). Used by the card-sampling LLM fallback. Honors the per-call timeout and
+   *  the cancel kill-switch; null on a non-OK response.
+   *
+   *  `enable_thinking: false` is REQUIRED here (live-verified): a reasoning model (Gemma 4,
+   *  Qwen3, …) otherwise spends the whole token budget on hidden reasoning and either emits no
+   *  JSON or truncates it (`finish_reason: length`) — the extraction returns nothing on exactly
+   *  the models people run. Card extraction is a structured task that needs no reasoning; with
+   *  thinking off, even a 4B model emits clean JSON in well under 200 tokens. Templates that
+   *  don't know the kwarg ignore it. */
+  async chatText(target, content, maxTokens, timeoutMs) {
+    const signals = [AbortSignal.timeout(timeoutMs)];
+    if (this.abort) signals.push(this.abort.signal);
+    const res = await fetch(`${target}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "bench",
+        messages: [{ role: "user", content }],
+        max_tokens: maxTokens,
+        temperature: 0,
+        stream: false,
+        chat_template_kwargs: { enable_thinking: false }
+      }),
+      signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0]
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? null;
+  }
   /** Save the winning profile as the model's saved profile (tunedBy:'bench') and
    *  persist a benchResults row. Both via the same ConfigStore the route uses. */
   persistBest(modelKey, profile, cand) {
@@ -7748,23 +8068,6 @@ function recommendEngines(p, engines) {
   return { recommended: null, fits };
 }
 
-// src/api/path-utils.ts
-function inferRepoFromPath(filePath, modelDirs) {
-  const norm = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
-  const fp = norm(filePath);
-  const seg = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-  for (const dir of modelDirs) {
-    const root = norm(dir);
-    if (!fp.toLowerCase().startsWith(root.toLowerCase() + "/")) continue;
-    const parts = fp.slice(root.length + 1).split("/");
-    if (parts.length >= 2 && seg.test(parts[0]) && seg.test(parts[1])) {
-      return `${parts[0]}/${parts[1]}`;
-    }
-    return null;
-  }
-  return null;
-}
-
 // src/api/routes.ts
 function err2(c, status, code, message) {
   return c.json({ error: { code, message } }, status);
@@ -8255,6 +8558,16 @@ function registerApi(app2, d) {
     for (const e of engines) policies[e.id] = normalizeUpdatePolicy(e.updatePolicy);
     return c.json({ updates: updates2, policies });
   });
+  app2.get("/api/v1/app/update", (c) => {
+    const fallback = { installed: d.version, latest: null, hasUpdate: false, checkedAt: (/* @__PURE__ */ new Date()).toISOString(), comparable: false };
+    if (!d.appUpdates) return c.json(fallback);
+    const refresh = c.req.query("refresh") === "1";
+    if (refresh || d.appUpdates.isStale()) {
+      void d.appUpdates.check(AbortSignal.timeout(1e4)).catch(() => {
+      });
+    }
+    return c.json(d.appUpdates.get() ?? fallback);
+  });
   app2.put("/api/v1/engines/:id/update-policy", async (c) => {
     const b = await body2(c);
     if (b.policy !== "off" && b.policy !== "notify" && b.policy !== "auto") {
@@ -9925,7 +10238,7 @@ var hashes = new HashStore(store.dir());
 var db = new ConversationStore(store.dir());
 var hf = new HfClient(() => store.snapshot().hf.token, version);
 var downloads = new DownloadManager(store, () => void scanner.rescan(), () => hf.authHeaders());
-var bench = new BenchRunner(manager, store, scanner, registry, version);
+var bench = new BenchRunner(manager, store, scanner, registry, version, hf);
 var comfy = new ComfyGuard(store, manager);
 var modelRouter = new ModelRouter(store, registry, manager, scanner, comfy);
 var toolRegistry = new ToolRegistry(store.snapshot().tools);
@@ -9934,8 +10247,11 @@ void (async () => {
   await toolRegistry.syncMcpServers(cfg2.mcp.servers);
 })();
 var startedAt = Date.now();
-var deps = { store, registry, manager, scanner, hashes, db, provision, updates, hf, downloads, bench, modelRouter, comfy, tools: toolRegistry, version, startedAt };
+var appUpdates = new AppUpdateChecker(version);
+var deps = { store, registry, manager, scanner, hashes, db, provision, updates, appUpdates, hf, downloads, bench, modelRouter, comfy, tools: toolRegistry, version, startedAt };
 var app = createApp(deps);
+setTimeout(() => void appUpdates.check(AbortSignal.timeout(1e4)).catch(() => {
+}), 5e3).unref();
 var updateScheduler = new UpdateScheduler({
   store,
   registry,