@otto-code/brain 0.8.10 → 0.8.13

package/dist/tui/app.js

@@ -1,7 +1,7 @@
 import { Screen, box, meter, style, pad, truncate, width, onKeys } from "./screen.js";
 import { scanModels, managedModelsDir, diskUsage, totalModelBytes, planDelete, deleteModelFiles, listRepoQuants, searchModels, downloadRepoFiles, resolveHfToken, } from "../models/index.js";
 import * as profiles from "../config/profiles.js";
-import { formatReasoningBudget, loadBrainConfig, loadProfilesStore, saveProfilesStore, UNRESTRICTED_REASONING_BUDGET, } from "../config/index.js";
+import { formatReasoningBudget, loadBrainConfig, loadProfilesStore, profileWarnings, saveProfilesStore, UNRESTRICTED_REASONING_BUDGET, } from "../config/index.js";
 import * as vram from "../vram.js";
 import * as gpu from "../gpu.js";
 import { calibrate } from "../ops/calibrate.js";
@@ -61,6 +61,27 @@ export const FIELDS = [
         values: CACHE_CYCLE,
         format: (p) => p.cacheTypeV,
     },
+    {
+        key: "parallelSlots",
+        label: "Parallel slots",
+        kind: "number",
+        step: 1,
+        min: 1,
+        max: () => 16,
+        format: (p) => String(p.parallelSlots),
+        note: (p) => p.parallelSlots > 1 ? `${p.parallelSlots} concurrent requests, sharing one KV pool` : null,
+    },
+    {
+        key: "cachedChats",
+        label: "Cached KVs",
+        kind: "number",
+        step: 1,
+        min: 0,
+        max: () => 64,
+        format: (p) => (p.cachedChats ?? 0) > 0 ? String(p.cachedChats) : `default ${style.grey}(0)${style.reset}`,
+        // No inline note: the RAM estimate is the warning's job, and the warning
+        // lives in one place (profile-edit.ts). The panel reads it from there.
+    },
     {
         key: "flashAttention",
         label: "Flash attention",
@@ -97,6 +118,21 @@ export const FIELDS = [
         },
         note: (p) => p.reasoningBudget === -1 ? "unrestricted budget can consume every token on thinking" : null,
     },
+    {
+        key: "preserveReasoning",
+        label: "Preserve reasoning",
+        kind: "cycle",
+        // The stored tri-state, in the order PRESERVE_REASONING_CYCLE names it.
+        values: [null, true, false],
+        format: (p) => p.preserveReasoning === true
+            ? `${style.brightGreen}on${style.reset}`
+            : p.preserveReasoning === false
+                ? `${style.yellow}off${style.reset}`
+                : `${style.grey}template default${style.reset}`,
+        // Offered wherever the template has thinking to preserve, not only where it
+        // spells the setting as a kwarg. See profileFieldDescriptors for why.
+        enabled: (ctx) => Boolean(ctx.model?.metadata?.reasoning || ctx.model?.reasoningPreservation),
+    },
     {
         key: "gpuLayers",
         label: "GPU layers",
@@ -106,16 +142,6 @@ export const FIELDS = [
         max: () => 999,
         format: (p) => p.gpuLayers >= 999 ? `all ${style.grey}(999)${style.reset}` : String(p.gpuLayers),
     },
-    {
-        key: "parallelSlots",
-        label: "Parallel slots",
-        kind: "number",
-        step: 1,
-        min: 1,
-        max: () => 16,
-        format: (p) => String(p.parallelSlots),
-        note: (p) => p.parallelSlots > 1 ? `${p.parallelSlots} concurrent requests, sharing one KV pool` : null,
-    },
 ];
 export class App {
     constructor({ runtime, listenPort, listenHost }) {
@@ -220,7 +246,7 @@ export class App {
             const fit = vram.fitToBudget({
                 model: target,
                 profile,
-                calibration: profiles.getCalibration(this.store, target, profile),
+                calibration: profiles.getCalibrationForBudget(this.store, target, profile),
                 totalVramBytes: info.totalBytes,
             });
             if (!fit.adjusted && !fit.budget.fits)
@@ -404,7 +430,7 @@ export class App {
         const profile = this.profile;
         if (!model || !profile)
             return null;
-        return profiles.getCalibration(this.store, model, profile);
+        return profiles.getCalibrationForBudget(this.store, model, profile);
     }
     get budget() {
         const model = this.model;
@@ -1179,11 +1205,14 @@ export class App {
             return;
         return this.guard("calibration", async () => {
             await this.supervisor.stop();
+            this.supervisor.recordLog(`operation calibrate: ${model.displayName}`);
             const measurement = await calibrate({
                 runtime: this.runtime,
                 model,
                 profile,
+                supervisor: this.supervisor,
                 onProgress: (p) => {
+                    this.supervisor.recordLog(`operation calibrate: ${p.phase} ${p.contextSize.toLocaleString()}${p.reason ? `: ${p.reason}` : ""}${p.error ? `: ${p.error}` : ""}`);
                     if (p.phase === "loading")
                         this.setStatus(`calibrating: loading at ${p.contextSize.toLocaleString()} ctx…`, "info");
                     if (p.phase === "measured")
@@ -1217,6 +1246,7 @@ export class App {
             this.setStatus(appliedTo !== null
                 ? `${measuredMsg} - context ${before.toLocaleString()} -> ${appliedTo.toLocaleString()}`
                 : measuredMsg, "good");
+            this.supervisor.recordLog(`operation calibrate: saved measurement for ${model.displayName}`);
         });
     }
     runSweep() {
@@ -1226,11 +1256,14 @@ export class App {
             return;
         return this.guard("sweep", async () => {
             await this.supervisor.stop();
+            this.supervisor.recordLog(`operation sweep: ${model.displayName}`);
             const result = await sweep({
                 runtime: this.runtime,
                 model,
                 profile,
+                supervisor: this.supervisor,
                 onProgress: (p) => {
+                    this.supervisor.recordLog(`operation sweep: budget ${p.budget} ${p.phase}${p.error ? `: ${p.error}` : ""}`);
                     if (p.phase === "loading")
                         this.setStatus(`sweep: loading with budget ${p.budget}…`, "info");
                     if (p.phase === "generating")
@@ -1245,6 +1278,7 @@ export class App {
                 profile.reasoningBudget = result.recommended;
                 this.persist();
                 this.setStatus(`sweep complete - reasoning budget set to ${result.recommended}`, "good");
+                this.supervisor.recordLog(`operation sweep: saved budget ${result.recommended}`);
             }
             else {
                 this.setStatus("sweep produced no usable result", "warn");
@@ -1364,7 +1398,9 @@ export class App {
                         // Only when it belongs to the model actually being benchmarked - the
                         // model may have been resident since before this fit was computed.
                         fit: this.lastFit?.modelId === model.id ? this.lastFit.fit : null,
-                        calibration: profile ? profiles.getCalibration(this.store, model, profile) : null,
+                        calibration: profile
+                            ? profiles.getCalibrationForBudget(this.store, model, profile)
+                            : null,
                         suite: {
                             // The TUI runs the full static suite; only concurrency varies, and
                             // it tracks the profile's slot count the same way runSuite is called.
@@ -1626,14 +1662,14 @@ export class App {
         const header = this.header(cols);
         const status = this.statusPanel(cols - 2);
         const footer = this.keybindings(cols - 1);
-        const title = truncate(`${style.brightCyan}llama-server log${style.reset}  ` +
+        const title = truncate(`${style.brightCyan}Brain log${style.reset}  ` +
             `${style.grey}${s.state}${logs.length ? ` · ${logs.length} lines` : ""} · esc or l to go back${style.reset}`, cols - 1);
         // header + blank + title + blank + [body] + blank + status + blank + footer.
         const overhead = 1 + 1 + 1 + 1 + 1 + status.length + 1 + footer.length;
         const bodyRows = Math.max(1, this.screen.rows - 1 - overhead);
         const body = [];
         if (logs.length === 0) {
-            body.push(`${style.grey}no logs yet - start a model with s to see llama-server output${style.reset}`);
+            body.push(`${style.grey}no logs yet - start a model or operation to see Brain output${style.reset}`);
         }
         else {
             for (const line of logs.slice(Math.max(0, logs.length - bodyRows)))
@@ -1739,9 +1775,23 @@ export class App {
                 if (focused)
                     focusLine = content.length;
                 content.push(`${arrow} ${pad(field.label, 17)} ${value}`);
-                const note = field.note?.(profile);
-                if (note)
-                    content.push(`  ${style.yellow}  ${note}${style.reset}`);
+                // The cachedChats estimate is a ProfileWarning, not a field note: it is
+                // computed once in profile-edit.ts, colored by how much of the machine's
+                // RAM it would take, and the app editor renders the very same object.
+                const cachedWarning = field.key === "cachedChats"
+                    ? profileWarnings(profile, model, this.store).find((w) => w.field === "cachedChats")
+                    : undefined;
+                const note = cachedWarning?.message ?? field.note?.(profile);
+                if (note) {
+                    const tone = cachedWarning?.severity === "error"
+                        ? style.red
+                        : cachedWarning?.severity === "warn"
+                            ? style.yellow
+                            : field.key === "cachedChats"
+                                ? style.grey
+                                : style.yellow;
+                    content.push(`  ${tone}  ${note}${style.reset}`);
+                }
             }
             const sweepResult = this.sweepResult;
             if (sweepResult) {
@@ -1770,8 +1820,12 @@ export class App {
             const start = Math.max(0, Math.min(focusLine - Math.floor(rows / 2), content.length - rows));
             lines = content.slice(start, start + rows);
         }
+        const stale = Boolean(this.profile?.calibrationRequired ||
+            (this.model &&
+                this.profile &&
+                profiles.hasStaleCalibration(this.store, this.model, this.profile)));
         return box({
-            title: `Configuration${this.calibration ? `  ${style.brightGreen}calibrated${style.reset}` : `  ${style.yellow}not calibrated${style.reset}`}`,
+            title: `Configuration${stale ? `  ${style.yellow}recalibrate${style.reset}` : this.calibration ? `  ${style.brightGreen}calibrated${style.reset}` : `  ${style.yellow}not calibrated${style.reset}`}`,
             lines,
             innerWidth,
             footer: `${style.grey}←→ change · enter edit${style.reset}`,
@@ -1799,18 +1853,21 @@ export class App {
             ` = ${style.bold}${vram.formatGiB(b.totalBytes)}${style.reset}`;
         const kvLabel = `kv ${(b.kvBytesPerToken / 1024).toFixed(1)} KB/token`;
         const cal = this.calibration;
+        const stale = Boolean(this.profile?.calibrationRequired ||
+            (this.model &&
+                this.profile &&
+                profiles.hasStaleCalibration(this.store, this.model, this.profile)));
         let sourceNote;
         if (b.source === "measured") {
             sourceNote = cal?.inherited
                 ? `${style.yellow}${kvLabel} (measured on a relative - press c to calibrate this model)${style.reset}`
-                : `${style.grey}${kvLabel} (measured)${style.reset}`;
+                : stale
+                    ? `${style.yellow}${kvLabel} (last measurement - press c to recalibrate)${style.reset}`
+                    : `${style.grey}${kvLabel} (measured)${style.reset}`;
         }
         else {
-            const stale = this.model && this.profile
-                ? profiles.hasStaleCalibration(this.store, this.model, this.profile)
-                : false;
             const hint = stale
-                ? "cache types changed - press c to recalibrate"
+                ? "recalibrate to refresh this value"
                 : "press c to calibrate; usually unlocks more context";
             sourceNote = `${style.yellow}${kvLabel} (theoretical - ${hint})${style.reset}`;
         }
@@ -1923,7 +1980,7 @@ export class App {
         item("u", "reset the selected model's name to its default (asks to confirm)");
         section("Views");
         item("b", "benchmark mode - rank models, run the coding suite");
-        item("l", "view the live llama-server log");
+        item("l", "view the live Brain log");
         item("/", "filter the model list (Enter apply, Esc clear)");
         item("r", "rescan the models folder");
         item("?", "this help");

package/dist/types.d.ts

@@ -21,6 +21,8 @@ export interface ModelMetadata {
      * flags a reasoning model - works for any local model, catalog or not.
      */
     reasoning?: boolean;
+    /** Native template key detected from `preserve_thinking` or `preserve_reasoning`. */
+    reasoningPreservationArgument?: string;
     [key: string]: unknown;
 }
 export interface ModelFeatures {
@@ -28,6 +30,16 @@ export interface ModelFeatures {
     imatrix: boolean;
     distilled: boolean;
 }
+/** Catalog-declared native chat-template argument names for reasoning controls. */
+export interface ReasoningTemplate {
+    enableThinkingArgument: string;
+    effortArgument: string;
+}
+/** The native argument behind Brain's provider-neutral Preserve reasoning setting. */
+export interface ReasoningPreservation {
+    templateArgument: string;
+    default?: boolean;
+}
 export type ModelComponentRole = "vision_projector" | "speculative_drafter";
 /** A catalog-declared companion artifact resolved against local disk. */
 export interface ModelComponent {
@@ -69,6 +81,12 @@ export interface Model {
     thinking?: boolean;
     /** Per-request reasoning levels accepted by the model's OpenAI-compatible API. */
     reasoningEfforts?: string[];
+    /** The model-native default among `reasoningEfforts`, when one is declared. */
+    reasoningEffortDefault?: string;
+    /** Template argument names needed to apply this model's reasoning controls. */
+    reasoningTemplate?: ReasoningTemplate;
+    /** Native template argument used by the model-profile Preserve reasoning setting. */
+    reasoningPreservation?: ReasoningPreservation;
     /** The catalog's advertised max context, if known. */
     contextMax?: number;
     /** Back-reference: the id of the reconciled catalog entry, if matched. */

package/dist/vram.d.ts

@@ -18,6 +18,43 @@ export declare function listCacheTypes(): string[];
 /** Worst-case KV bytes per token, assuming every layer holds a full cache. */
 export declare function theoreticalKvBytesPerToken(metadata: ModelMetadata | null, cacheTypeK: string, cacheTypeV: string): number | null;
 export type BudgetSource = "measured" | "theoretical" | "unknown";
+/**
+ * KV bytes per token for a profile: the measurement when one exists, otherwise
+ * the theoretical bound.
+ *
+ * The two are not interchangeable. The theoretical formula overestimates badly
+ * on architectures that only keep a full cache on a subset of layers - measured
+ * at 3.5x for Qwen3.8-27B and 20x for Gemma-4-31B on this repo's own stored
+ * calibrations - which is the whole reason `calibrate` exists. Callers that
+ * spend real memory on this number must therefore branch on `source` rather
+ * than treating the theoretical figure as an answer.
+ */
+export declare function kvBytesPerToken(model: Model, profile: Profile, calibration?: Calibration | null): {
+    value: number;
+    source: BudgetSource;
+    theoretical: number | null;
+};
+export interface PromptCacheSize {
+    /** One chat at its full per-slot window - the worst case for a single entry. */
+    perChatBytes: number;
+    /** What `--cache-ram` is set to, in bytes. */
+    totalBytes: number;
+    source: BudgetSource;
+}
+/**
+ * Turn `cachedChats` into a `--cache-ram` byte budget.
+ *
+ * llama-server parks the KV state of a chat that loses its slot in host RAM and
+ * copies it back when that chat returns, instead of re-prefilling its whole
+ * conversation. An entry is at most one slot's worth of KV, and a slot is
+ * `contextSize / parallelSlots` tokens, so the count the user picks is the
+ * count of chats guaranteed to survive. Real conversations rarely fill their
+ * window, so in practice more of them fit: the number is a floor, not a cap.
+ *
+ * Returns null when the size cannot be computed - `cachedChats` is 0 (leave
+ * llama.cpp's default alone) or nothing is known about this model's KV cost.
+ */
+export declare function promptCacheSize(model: Model, profile: Profile, calibration?: Calibration | null): PromptCacheSize | null;
 export interface Budget {
     weightsBytes: number;
     mmprojBytes: number;

package/dist/vram.js

@@ -32,6 +32,52 @@ export function theoreticalKvBytesPerToken(metadata, cacheTypeK, cacheTypeV) {
         (keyLength * cacheTypeBytes(cacheTypeK) +
             valueLength * cacheTypeBytes(cacheTypeV)));
 }
+/**
+ * KV bytes per token for a profile: the measurement when one exists, otherwise
+ * the theoretical bound.
+ *
+ * The two are not interchangeable. The theoretical formula overestimates badly
+ * on architectures that only keep a full cache on a subset of layers - measured
+ * at 3.5x for Qwen3.8-27B and 20x for Gemma-4-31B on this repo's own stored
+ * calibrations - which is the whole reason `calibrate` exists. Callers that
+ * spend real memory on this number must therefore branch on `source` rather
+ * than treating the theoretical figure as an answer.
+ */
+export function kvBytesPerToken(model, profile, calibration) {
+    const theoretical = theoreticalKvBytesPerToken(model.metadata, profile.cacheTypeK, profile.cacheTypeV);
+    if (calibration && calibration.kvBytesPerToken > 0) {
+        return { value: calibration.kvBytesPerToken, source: "measured", theoretical };
+    }
+    if (theoretical !== null)
+        return { value: theoretical, source: "theoretical", theoretical };
+    return { value: 0, source: "unknown", theoretical };
+}
+/**
+ * Turn `cachedChats` into a `--cache-ram` byte budget.
+ *
+ * llama-server parks the KV state of a chat that loses its slot in host RAM and
+ * copies it back when that chat returns, instead of re-prefilling its whole
+ * conversation. An entry is at most one slot's worth of KV, and a slot is
+ * `contextSize / parallelSlots` tokens, so the count the user picks is the
+ * count of chats guaranteed to survive. Real conversations rarely fill their
+ * window, so in practice more of them fit: the number is a floor, not a cap.
+ *
+ * Returns null when the size cannot be computed - `cachedChats` is 0 (leave
+ * llama.cpp's default alone) or nothing is known about this model's KV cost.
+ */
+export function promptCacheSize(model, profile, calibration) {
+    const chats = Math.floor(profile.cachedChats ?? 0);
+    if (chats < 1)
+        return null;
+    const { value, source } = kvBytesPerToken(model, profile, calibration);
+    if (value <= 0 || profile.contextSize <= 0)
+        return null;
+    const perSlotTokens = Math.floor(profile.contextSize / Math.max(1, profile.parallelSlots || 1));
+    if (perSlotTokens <= 0)
+        return null;
+    const perChatBytes = value * perSlotTokens;
+    return { perChatBytes, totalBytes: perChatBytes * chats, source };
+}
 /** Compute a VRAM budget for a profile. */
 export function budget({ model, profile, calibration = null, totalVramBytes, reserveBytes = 1.5 * GIB, }) {
     const weights = model.sizeBytes;
@@ -46,22 +92,8 @@ export function budget({ model, profile, calibration = null, totalVramBytes, res
             : 0;
     const mmproj = projector.reduce((total, component) => total + component.bytes, 0) ||
         (components.length ? 0 : componentBytes);
-    const theoretical = theoreticalKvBytesPerToken(model.metadata, profile.cacheTypeK, profile.cacheTypeV);
-    let kvBytesPerToken;
-    let source;
-    if (calibration && calibration.kvBytesPerToken > 0) {
-        kvBytesPerToken = calibration.kvBytesPerToken;
-        source = "measured";
-    }
-    else if (theoretical !== null) {
-        kvBytesPerToken = theoretical;
-        source = "theoretical";
-    }
-    else {
-        kvBytesPerToken = 0;
-        source = "unknown";
-    }
-    const kv = kvBytesPerToken * profile.contextSize;
+    const { value: perToken, source, theoretical } = kvBytesPerToken(model, profile, calibration);
+    const kv = perToken * profile.contextSize;
     // The speculative decoder keeps its own KV cache. Until component-specific
     // calibration exists, reserve the same conservative per-token cost.
     const drafterKv = drafters.length * kv;
@@ -84,7 +116,7 @@ export function budget({ model, profile, calibration = null, totalVramBytes, res
         usableBytes: usable,
         totalVramBytes,
         reserveBytes,
-        kvBytesPerToken,
+        kvBytesPerToken: perToken,
         source,
         theoreticalKvBytesPerToken: theoretical,
         fits: total <= usable,
@@ -107,7 +139,14 @@ export function maxContextThatFits({ model, profile, calibration, totalVramBytes
     const room = probe.usableBytes - fixed;
     if (room <= 0)
         return null;
-    const tokens = Math.floor(room / probe.kvBytesPerToken);
+    // More than one KV pool can scale with the context - a speculative drafter
+    // keeps its own. Derive the per-token cost from the probe rather than from
+    // `kvBytesPerToken` alone, so this can never hand back a context that
+    // `budget()` then declares does not fit.
+    const perToken = (probe.kvBytes + probe.drafterKvBytes) / step;
+    if (perToken <= 0)
+        return null;
+    const tokens = Math.floor(room / perToken);
     const native = model.metadata?.contextLength;
     const contextLimit = typeof native === "number" && native > 0 ? native * profile.contextMultiplier : tokens;
     const capped = Math.min(tokens, contextLimit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.10",
+  "version": "0.8.13",
   "description": "Otto Brain - self-contained host for local GGUF models, with measured VRAM budgeting and reasoning-budget control",
   "license": "AGPL-3.0-or-later",
   "bin": {