@otto-code/brain 0.7.5

package/dist/tui/screen.d.ts

@@ -0,0 +1,72 @@
+/** Minimal ANSI screen and input primitives - no dependencies. */
+export declare const ansi: {
+    altScreenOn: string;
+    altScreenOff: string;
+    hideCursor: string;
+    showCursor: string;
+    home: string;
+    clearScreen: string;
+    clearToEol: string;
+    clearBelow: string;
+    reset: string;
+};
+export declare const style: {
+    reset: string;
+    bold: string;
+    dim: string;
+    inverse: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    grey: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightCyan: string;
+};
+export declare const BOX: {
+    h: string;
+    v: string;
+    tl: string;
+    tr: string;
+    bl: string;
+    br: string;
+    full: string;
+    light: string;
+};
+/** Options for a titled box. */
+export interface BoxOptions {
+    title?: string;
+    lines: string[];
+    innerWidth: number;
+    footer?: string | null;
+    accent?: string;
+}
+/** Printable width, ignoring ANSI escapes. */
+export declare function width(text: string): number;
+export declare function truncate(text: string, max: number): string;
+export declare function pad(text: string, max: number): string;
+/** A titled box as an array of lines. */
+export declare function box({ title, lines, innerWidth, footer, accent, }: BoxOptions): string[];
+/** Horizontal meter, coloured by how close to the limit it sits. */
+export declare function meter(fraction: number, cells: number): string;
+export declare class Screen {
+    out: NodeJS.WriteStream;
+    previous: string[];
+    entered: boolean;
+    constructor(stream?: NodeJS.WriteStream);
+    get columns(): number;
+    get rows(): number;
+    enter(): void;
+    leave(): void;
+    /** Repaint only the lines that changed. */
+    render(lines: string[]): void;
+    invalidate(): void;
+}
+/** Decode a raw stdin chunk into a key name. */
+export declare function decodeKey(chunk: unknown): string | null;
+export declare function onKeys(handler: (key: string, chunk: unknown) => void, stream?: NodeJS.ReadStream): () => void;
+//# sourceMappingURL=screen.d.ts.map

package/dist/tui/screen.js

@@ -0,0 +1,176 @@
+/** Minimal ANSI screen and input primitives - no dependencies. */
+const ESC = "\x1b";
+const CSI = `${ESC}[`;
+export const ansi = {
+    altScreenOn: `${CSI}?1049h`,
+    altScreenOff: `${CSI}?1049l`,
+    hideCursor: `${CSI}?25l`,
+    showCursor: `${CSI}?25h`,
+    home: `${CSI}H`,
+    clearScreen: `${CSI}2J`,
+    clearToEol: `${CSI}K`,
+    clearBelow: `${CSI}J`,
+    reset: `${CSI}0m`,
+};
+export const style = {
+    reset: `${CSI}0m`,
+    bold: `${CSI}1m`,
+    dim: `${CSI}2m`,
+    inverse: `${CSI}7m`,
+    red: `${CSI}31m`,
+    green: `${CSI}32m`,
+    yellow: `${CSI}33m`,
+    blue: `${CSI}34m`,
+    magenta: `${CSI}35m`,
+    cyan: `${CSI}36m`,
+    white: `${CSI}37m`,
+    grey: `${CSI}90m`,
+    brightGreen: `${CSI}92m`,
+    brightYellow: `${CSI}93m`,
+    brightCyan: `${CSI}96m`,
+};
+export const BOX = {
+    h: "─",
+    v: "│",
+    tl: "┌",
+    tr: "┐",
+    bl: "└",
+    br: "┘",
+    full: "█",
+    light: "░",
+};
+/** Printable width, ignoring ANSI escapes. */
+export function width(text) {
+    return String(text).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+export function truncate(text, max) {
+    const plain = String(text);
+    if (width(plain) <= max)
+        return plain;
+    // Only called on unstyled strings, so a plain slice is safe.
+    return `${plain.slice(0, Math.max(0, max - 1))}…`;
+}
+export function pad(text, max) {
+    const gap = max - width(text);
+    return gap > 0 ? text + " ".repeat(gap) : text;
+}
+/** A titled box as an array of lines. */
+export function box({ title, lines, innerWidth, footer = null, accent = style.grey, }) {
+    const out = [];
+    const label = title ? ` ${title} ` : "";
+    const dashes = Math.max(0, innerWidth - width(label));
+    out.push(`${accent}${BOX.tl}${label}${BOX.h.repeat(dashes)}${BOX.tr}${style.reset}`);
+    for (const line of lines) {
+        out.push(`${accent}${BOX.v}${style.reset}${pad(truncate(line, innerWidth), innerWidth)}${accent}${BOX.v}${style.reset}`);
+    }
+    if (footer !== null) {
+        out.push(`${accent}${BOX.v}${style.reset}${pad(truncate(footer, innerWidth), innerWidth)}${accent}${BOX.v}${style.reset}`);
+    }
+    out.push(`${accent}${BOX.bl}${BOX.h.repeat(innerWidth)}${BOX.br}${style.reset}`);
+    return out;
+}
+/** Horizontal meter, coloured by how close to the limit it sits. */
+export function meter(fraction, cells) {
+    const clamped = Math.max(0, Math.min(1.2, fraction));
+    const filled = Math.min(cells, Math.round(clamped * cells));
+    let colour = style.brightGreen;
+    if (clamped > 1)
+        colour = style.red;
+    else if (clamped > 0.9)
+        colour = style.brightYellow;
+    return `${colour}${BOX.full.repeat(filled)}${style.grey}${BOX.light.repeat(Math.max(0, cells - filled))}${style.reset}`;
+}
+export class Screen {
+    constructor(stream = process.stdout) {
+        this.out = stream;
+        this.previous = [];
+        this.entered = false;
+    }
+    get columns() {
+        return this.out.columns || 100;
+    }
+    get rows() {
+        return this.out.rows || 30;
+    }
+    enter() {
+        if (this.entered)
+            return;
+        this.entered = true;
+        this.out.write(ansi.altScreenOn + ansi.hideCursor + ansi.clearScreen + ansi.home);
+    }
+    leave() {
+        if (!this.entered)
+            return;
+        this.entered = false;
+        this.out.write(ansi.showCursor + ansi.altScreenOff);
+    }
+    /** Repaint only the lines that changed. */
+    render(lines) {
+        let frame = ansi.home;
+        const height = Math.min(lines.length, this.rows - 1);
+        for (let i = 0; i < height; i += 1) {
+            if (this.previous[i] === lines[i]) {
+                frame += `${CSI}${i + 2};1H`;
+                continue;
+            }
+            frame += `${CSI}${i + 1};1H${lines[i]}${ansi.clearToEol}`;
+        }
+        if (this.previous.length > height) {
+            frame += `${CSI}${height + 1};1H${ansi.clearBelow}`;
+        }
+        this.out.write(frame);
+        this.previous = lines.slice(0, height);
+    }
+    invalidate() {
+        this.previous = [];
+        this.out.write(ansi.clearScreen);
+    }
+}
+/** Decode a raw stdin chunk into a key name. */
+export function decodeKey(chunk) {
+    const s = String(chunk);
+    const named = {
+        "\x1b[A": "up",
+        "\x1b[B": "down",
+        "\x1b[C": "right",
+        "\x1b[D": "left",
+        "\x1b[H": "home",
+        "\x1b[F": "end",
+        "\x1b[5~": "pageup",
+        "\x1b[6~": "pagedown",
+        "\r": "enter",
+        "\n": "enter",
+        "\t": "tab",
+        "\x1b[Z": "shifttab",
+        "\x7f": "backspace",
+        "\b": "backspace",
+        "\x1b": "escape",
+        "\x03": "ctrl-c",
+        "\x04": "ctrl-d",
+        " ": "space",
+    };
+    if (named[s])
+        return named[s];
+    if (s.length === 1)
+        return s;
+    return null;
+}
+export function onKeys(handler, stream = process.stdin) {
+    if (stream.isTTY)
+        stream.setRawMode(true);
+    stream.resume();
+    stream.setEncoding("utf8");
+    const listener = (chunk) => {
+        const key = decodeKey(chunk);
+        if (key)
+            handler(key, chunk);
+    };
+    stream.on("data", listener);
+    return () => {
+        stream.off("data", listener);
+        if (stream.isTTY)
+            stream.setRawMode(false);
+        stream.pause();
+    };
+}
+//# sourceMappingURL=screen.js.map

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared domain interfaces used across discovery, decision, and runtime layers.
+ * Kept dependency-free so any module can import the shapes without pulling in
+ * behavior. Behavioral defaults live with the code that produces each value.
+ */
+export interface ModelMetadata {
+    arch?: string | null;
+    contextLength?: number | null;
+    blockCount?: number | null;
+    headCount?: number | null;
+    headCountKv?: number | null;
+    keyLength?: number | null;
+    valueLength?: number | null;
+    embeddingLength?: number | null;
+    /**
+     * Whether the model's chat template exposes a thinking/reasoning channel
+     * (a `<think>` block, `reasoning_content`, or an `enable_thinking` toggle).
+     * Derived from the GGUF template in `gguf.summarize`, mirroring how LM Studio
+     * flags a reasoning model - works for any local model, catalog or not.
+     */
+    reasoning?: boolean;
+    [key: string]: unknown;
+}
+export interface ModelFeatures {
+    mtp: boolean;
+    imatrix: boolean;
+    distilled: boolean;
+}
+/** A GGUF model discovered on disk (or resolvable from the download catalog). */
+export interface Model {
+    id: string;
+    displayName: string;
+    modelPath: string;
+    mmprojPath: string | null;
+    mmprojBytes: number;
+    quant: string | null;
+    sizeBytes: number;
+    publisher?: string | null;
+    dir?: string;
+    sharded?: boolean;
+    features: ModelFeatures;
+    metadata: ModelMetadata | null;
+    metadataError?: string | null;
+    /** Which source the model was found in, for scan display. */
+    origin?: "managed" | "lmstudio";
+    /** Curated use-case tags from the catalog (e.g. "coding", "reasoning"). */
+    useCases?: string[];
+    /** Curation tier label from the catalog. */
+    tier?: string;
+    /** Whether the catalog marks this as a thinking/reasoning model. */
+    thinking?: boolean;
+    /** The catalog's advertised max context, if known. */
+    contextMax?: number;
+    /** Back-reference: the id of the reconciled catalog entry, if matched. */
+    catalogId?: string;
+    /** Back-reference: the hfRepo of the reconciled catalog entry, if matched. */
+    catalogHfRepo?: string;
+}
+/** A resolved llama.cpp runtime: an executable paired with its vendor DLL dir. */
+export interface Runtime {
+    label: string;
+    version: string;
+    dir: string;
+    exe: string;
+    vendorDir: string | null;
+    source: "lmstudio" | "managed";
+}
+export interface GpuInfo {
+    name: string;
+    totalBytes: number;
+    usedBytes: number;
+    freeBytes: number;
+    driver: string;
+    computeCapability: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared domain interfaces used across discovery, decision, and runtime layers.
+ * Kept dependency-free so any module can import the shapes without pulling in
+ * behavior. Behavioral defaults live with the code that produces each value.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,8 @@
+/** Resolves the package version at runtime from package.json. */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export function resolveVersion() {
+    const pkg = require("../package.json");
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+//# sourceMappingURL=version.js.map

package/dist/vram.d.ts

@@ -0,0 +1,67 @@
+/**
+ * VRAM budgeting.
+ *
+ * A purely theoretical KV-cache formula is not trustworthy here. For a dense
+ * model, KV bytes/token = layers * kv_heads * (k_dim + v_dim) * bytes_per_elem.
+ * Measured against Qwen3.6-27B (`qwen35`) that formula overestimates by ~4x,
+ * because the architecture only carries a full KV cache on a subset of its
+ * layers. Guessing the ratio per architecture would be fragile, so the
+ * theoretical value is treated as a worst-case bound and a measured
+ * bytes-per-token from `calibrate` is preferred whenever one exists.
+ */
+import type { Calibration, Profile } from "./config/schema.js";
+import type { Model, ModelMetadata } from "./types.js";
+export declare const GIB: number;
+export declare const CACHE_TYPE_BYTES: Record<string, number>;
+export declare function cacheTypeBytes(type: string): number;
+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";
+export interface Budget {
+    weightsBytes: number;
+    mmprojBytes: number;
+    kvBytes: number;
+    overheadBytes: number;
+    totalBytes: number;
+    usableBytes: number;
+    totalVramBytes: number;
+    reserveBytes: number;
+    kvBytesPerToken: number;
+    source: BudgetSource;
+    theoreticalKvBytesPerToken: number | null;
+    fits: boolean;
+    headroomBytes: number;
+    utilization: number;
+}
+export interface BudgetOptions {
+    model: Model;
+    profile: Profile;
+    calibration?: Calibration | null;
+    totalVramBytes: number;
+    reserveBytes?: number;
+}
+/** Compute a VRAM budget for a profile. */
+export declare function budget({ model, profile, calibration, totalVramBytes, reserveBytes, }: BudgetOptions): Budget;
+export interface MaxContextOptions extends BudgetOptions {
+    step?: number;
+}
+/** Largest context that still fits, rounded down to a friendly step. */
+export declare function maxContextThatFits({ model, profile, calibration, totalVramBytes, reserveBytes, step, }: MaxContextOptions): number | null;
+export interface FitResult {
+    profile: Profile;
+    adjusted: boolean;
+    reason: string | null;
+    budget: Budget;
+}
+/**
+ * Adapt a profile to the hardware it is about to run on.
+ *
+ * Refusing to load because a saved profile asks for more context than this
+ * machine has is unhelpful when a slightly smaller context would work — and it
+ * is the difference between a model being usable on a 32GB desktop and a 24GB
+ * laptop. Clamp the context instead, and report what changed.
+ */
+export declare function fitToBudget({ model, profile, calibration, totalVramBytes, reserveBytes, }: BudgetOptions): FitResult;
+export declare function formatGiB(bytes: number, digits?: number): string;
+//# sourceMappingURL=vram.d.ts.map

package/dist/vram.js

@@ -0,0 +1,132 @@
+export const GIB = 1024 ** 3;
+// Bytes per element for each KV cache type (block size / elements per block).
+export const CACHE_TYPE_BYTES = {
+    f32: 4,
+    f16: 2,
+    bf16: 2,
+    q8_0: 34 / 32,
+    q5_1: 24 / 32,
+    q5_0: 22 / 32,
+    q4_1: 20 / 32,
+    q4_0: 18 / 32,
+};
+export function cacheTypeBytes(type) {
+    const bytes = CACHE_TYPE_BYTES[String(type).toLowerCase()];
+    if (bytes === undefined)
+        throw new Error(`unknown KV cache type "${type}"`);
+    return bytes;
+}
+export function listCacheTypes() {
+    return Object.keys(CACHE_TYPE_BYTES);
+}
+/** Worst-case KV bytes per token, assuming every layer holds a full cache. */
+export function theoreticalKvBytesPerToken(metadata, cacheTypeK, cacheTypeV) {
+    if (!metadata)
+        return null;
+    const { blockCount, headCountKv, keyLength, valueLength } = metadata;
+    if (![blockCount, headCountKv, keyLength, valueLength].every((v) => typeof v === "number" && v > 0)) {
+        return null;
+    }
+    return (blockCount *
+        headCountKv *
+        (keyLength * cacheTypeBytes(cacheTypeK) +
+            valueLength * cacheTypeBytes(cacheTypeV)));
+}
+/** Compute a VRAM budget for a profile. */
+export function budget({ model, profile, calibration = null, totalVramBytes, reserveBytes = 1.5 * GIB, }) {
+    const weights = model.sizeBytes;
+    const mmproj = profile.vision && model.mmprojPath ? model.mmprojBytes : 0;
+    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;
+    // Compute buffers and the CUDA context; measured at ~0.6 GB for a 27B and
+    // superseded by the calibrated value when available.
+    const overhead = calibration && calibration.baseOverheadBytes > 0 ? calibration.baseOverheadBytes : 0.6 * GIB;
+    const total = weights + mmproj + kv + overhead;
+    const usable = totalVramBytes - reserveBytes;
+    return {
+        weightsBytes: weights,
+        mmprojBytes: mmproj,
+        kvBytes: kv,
+        overheadBytes: overhead,
+        totalBytes: total,
+        usableBytes: usable,
+        totalVramBytes,
+        reserveBytes,
+        kvBytesPerToken,
+        source,
+        theoreticalKvBytesPerToken: theoretical,
+        fits: total <= usable,
+        headroomBytes: usable - total,
+        utilization: total / usable,
+    };
+}
+/** Largest context that still fits, rounded down to a friendly step. */
+export function maxContextThatFits({ model, profile, calibration, totalVramBytes, reserveBytes = 1.5 * GIB, step = 4096, }) {
+    const probe = budget({
+        model,
+        profile: { ...profile, contextSize: step },
+        calibration,
+        totalVramBytes,
+        reserveBytes,
+    });
+    if (probe.kvBytesPerToken <= 0)
+        return null;
+    const fixed = probe.weightsBytes + probe.mmprojBytes + probe.overheadBytes;
+    const room = probe.usableBytes - fixed;
+    if (room <= 0)
+        return null;
+    const tokens = Math.floor(room / probe.kvBytesPerToken);
+    const capped = model.metadata?.contextLength
+        ? Math.min(tokens, model.metadata.contextLength)
+        : tokens;
+    return Math.max(0, Math.floor(capped / step) * step);
+}
+/**
+ * Adapt a profile to the hardware it is about to run on.
+ *
+ * Refusing to load because a saved profile asks for more context than this
+ * machine has is unhelpful when a slightly smaller context would work — and it
+ * is the difference between a model being usable on a 32GB desktop and a 24GB
+ * laptop. Clamp the context instead, and report what changed.
+ */
+export function fitToBudget({ model, profile, calibration, totalVramBytes, reserveBytes = 1.5 * GIB, }) {
+    const initial = budget({ model, profile, calibration, totalVramBytes, reserveBytes });
+    if (initial.fits) {
+        return { profile, adjusted: false, reason: null, budget: initial };
+    }
+    const max = maxContextThatFits({ model, profile, calibration, totalVramBytes, reserveBytes });
+    if (!max || max < 4096) {
+        return {
+            profile,
+            adjusted: false,
+            reason: `does not fit at any usable context (needs ${formatGiB(initial.totalBytes)}, ` +
+                `${formatGiB(initial.usableBytes)} usable)`,
+            budget: initial,
+        };
+    }
+    const fitted = { ...profile, contextSize: max };
+    return {
+        profile: fitted,
+        adjusted: true,
+        reason: `context reduced ${profile.contextSize.toLocaleString()} -> ${max.toLocaleString()} to fit ${formatGiB(totalVramBytes)} of VRAM`,
+        budget: budget({ model, profile: fitted, calibration, totalVramBytes, reserveBytes }),
+    };
+}
+export function formatGiB(bytes, digits = 1) {
+    return `${(bytes / GIB).toFixed(digits)}G`;
+}
+//# sourceMappingURL=vram.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@otto-code/brain",
+  "version": "0.7.5",
+  "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": {
+    "otto-brain": "bin/otto-brain"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "node": "./dist/cli.js",
+      "import": "./src/cli.ts",
+      "default": "./src/cli.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node ../../scripts/clean-package-dist.mjs",
+    "build": "tsc -p tsconfig.json --incremental false",
+    "build:clean": "npm run clean && npm run build",
+    "prepack": "npm run build:clean",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "selfsigned": "^2.4.1",
+    "yaml": "^2.8.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}