@otto-code/brain 0.7.5

package/dist/service/model-selector.d.ts

@@ -0,0 +1,36 @@
+import type { RankedModel } from "../ops/results.js";
+import type { GpuInfo, Model } from "../types.js";
+export declare const MIN_TRUSTED_RUNS = 2;
+export declare const MAX_TRUSTED_STD = 0.15;
+export declare const PROBE_CONTEXT_TOKENS = 8192;
+/** Whether a scanned model carries catalog metadata marking it a coder. */
+export declare function isCodingCapable(model: Model): boolean;
+export interface SelectCodingModelOptions {
+    /** Every scanned model (the catalog the router already has). */
+    models: Model[];
+    /** Track A's per-model bench ranking (mean score + runs + std). */
+    ranking: RankedModel[];
+    /**
+     * VRAM-fit predicate. Omit (or pass undefined) to skip the fit filter — the
+     * caller does this when GPU info is absent, mirroring serve.ts's "absent →
+     * skip" behaviour.
+     */
+    fits?: (model: Model) => boolean;
+    /** Id of the currently-loaded model, a tiebreak to avoid a needless swap. */
+    preferLoadedId?: string | null;
+    /** The existing default, returned when no candidate survives. */
+    fallback: Model | null;
+}
+/**
+ * Pick the best-ranked coding model that fits the VRAM budget. Pure and
+ * deterministic — no IO, no clock, no randomness.
+ */
+export declare function selectCodingModel({ models, ranking, fits, preferLoadedId, fallback, }: SelectCodingModelOptions): Model | null;
+/**
+ * Build the route-time VRAM-fit predicate, or undefined when GPU info is absent
+ * (no nvidia-smi) so the caller skips the fit filter entirely. The probe profile
+ * is built once and reused: a model fits when its weights + KV at
+ * PROBE_CONTEXT_TOKENS sit inside the card's total VRAM budget.
+ */
+export declare function makeVramFitPredicate(gpu: GpuInfo | null): ((model: Model) => boolean) | undefined;
+//# sourceMappingURL=model-selector.d.ts.map

package/dist/service/model-selector.js

@@ -0,0 +1,123 @@
+/**
+ * Route-time model selection for the UNNAMED request path.
+ *
+ * When a client hits the brain without naming a model, the old default served
+ * "whatever is loaded, else catalog[0]" — blind to which local model is actually
+ * the best coder. This picks the best-ranked coding-capable model that fits the
+ * VRAM budget instead, wiring together Track A (the bench ranking) and Track B1
+ * (the catalog coding metadata carried onto the scanned Model).
+ *
+ * `selectCodingModel` is PURE: it takes the models, the ranking, an optional
+ * VRAM-fit predicate, and a fallback, and returns the chosen model with no IO —
+ * so the decision logic is trivially testable. `makeVramFitPredicate` is the one
+ * impure edge (it reads GPU total VRAM and runs a vram.budget), deliberately kept
+ * out of the pure path.
+ */
+import { ProfileSchema } from "../config/schema.js";
+import * as vram from "../vram.js";
+// --- Minimum-confidence gate. A bench score is only "trusted" for ranking when
+// it is backed by enough repeated runs and its spread across those runs is
+// tight. rankModels reports one entry per model with the MEAN overall score
+// (0..1), the run COUNT, and the sample STD (also 0..1). A single run has std 0
+// — falsely confident — so we require at least two runs, and we reject a mean
+// whose runs disagree by more than MAX_TRUSTED_STD. Untrusted models stay
+// eligible but sort below every trusted one.
+export const MIN_TRUSTED_RUNS = 2;
+export const MAX_TRUSTED_STD = 0.15;
+// --- Route-time fit probe. We do not have the saved per-model profile or a
+// measured calibration here, so fit is tested at a modest working context: a
+// model whose weights + KV at PROBE_CONTEXT_TOKENS overflow VRAM is excluded,
+// and one that fits is includable (serve.ts clamps the real context down at load
+// time via fitToBudget).
+export const PROBE_CONTEXT_TOKENS = 8192;
+const CODING_USE_CASE = "coding";
+// Matches curated tier labels like "coding", "coder", "code-specialist".
+const CODING_TIER_RE = /cod(ing|er|e-)/i;
+/** Whether a scanned model carries catalog metadata marking it a coder. */
+export function isCodingCapable(model) {
+    if (model.useCases?.some((u) => u.toLowerCase() === CODING_USE_CASE))
+        return true;
+    if (model.tier && CODING_TIER_RE.test(model.tier))
+        return true;
+    return false;
+}
+/** Look a scanned model up in the ranking by id first, then display name. */
+function rankingLookup(ranking) {
+    const byId = new Map();
+    const byName = new Map();
+    for (const entry of ranking) {
+        if (entry.id)
+            byId.set(entry.id, entry);
+        if (!byName.has(entry.displayName))
+            byName.set(entry.displayName, entry);
+    }
+    return (model) => byId.get(model.id) ?? byName.get(model.displayName) ?? null;
+}
+/**
+ * Decision order:
+ *   trusted bench score (desc) → any bench score (desc, untrusted-with-data over
+ *   none) → loaded model (avoid a swap) → larger advertised context → name.
+ * The trailing name comparison makes the order total, so the pick is fully
+ * deterministic given the same inputs.
+ */
+function compareCandidates(a, b, preferLoadedId) {
+    if (a.trusted !== b.trusted)
+        return a.trusted ? -1 : 1;
+    if (a.score !== b.score)
+        return b.score - a.score;
+    const aLoaded = preferLoadedId != null && a.model.id === preferLoadedId;
+    const bLoaded = preferLoadedId != null && b.model.id === preferLoadedId;
+    if (aLoaded !== bLoaded)
+        return aLoaded ? -1 : 1;
+    const aCtx = a.model.contextMax ?? 0;
+    const bCtx = b.model.contextMax ?? 0;
+    if (aCtx !== bCtx)
+        return bCtx - aCtx;
+    return a.model.displayName.localeCompare(b.model.displayName);
+}
+/**
+ * Pick the best-ranked coding model that fits the VRAM budget. Pure and
+ * deterministic — no IO, no clock, no randomness.
+ */
+export function selectCodingModel({ models, ranking, fits, preferLoadedId = null, fallback, }) {
+    if (models.length === 0)
+        return fallback;
+    // 1. Candidate set: coding-capable models. If nothing is tagged (a catalog
+    //    with no coding metadata, or hand-placed models), don't fail closed —
+    //    fall back to the whole set.
+    const tagged = models.filter(isCodingCapable);
+    let candidates = tagged.length > 0 ? tagged : models;
+    // 2. VRAM fit filter (skipped when no predicate — i.e. GPU info absent). If
+    //    nothing coding-capable fits, keep the existing default rather than
+    //    forcing a model that overflows the budget.
+    if (fits) {
+        const fitting = candidates.filter((m) => fits(m));
+        if (fitting.length === 0)
+            return fallback;
+        candidates = fitting;
+    }
+    // 3. Rank by bench score behind the confidence gate.
+    const lookup = rankingLookup(ranking);
+    const scored = candidates.map((model) => {
+        const entry = lookup(model);
+        const trusted = Boolean(entry && entry.runs >= MIN_TRUSTED_RUNS && entry.std <= MAX_TRUSTED_STD);
+        const score = entry ? entry.overall : Number.NEGATIVE_INFINITY;
+        return { model, trusted, score };
+    });
+    scored.sort((a, b) => compareCandidates(a, b, preferLoadedId));
+    return scored[0]?.model ?? fallback;
+}
+/**
+ * Build the route-time VRAM-fit predicate, or undefined when GPU info is absent
+ * (no nvidia-smi) so the caller skips the fit filter entirely. The probe profile
+ * is built once and reused: a model fits when its weights + KV at
+ * PROBE_CONTEXT_TOKENS sit inside the card's total VRAM budget.
+ */
+export function makeVramFitPredicate(gpu) {
+    if (!gpu)
+        return undefined;
+    const profile = ProfileSchema.parse({ contextSize: PROBE_CONTEXT_TOKENS });
+    const totalVramBytes = gpu.totalBytes;
+    return (model) => vram.budget({ model, profile, totalVramBytes }).fits;
+}
+//# sourceMappingURL=model-selector.js.map

package/dist/service/pid-lock.d.ts

@@ -0,0 +1,18 @@
+export interface PidRecord {
+    pid: number;
+    host: string;
+    port: number;
+    startedAt: string;
+    /** Whether the listener terminates TLS. Absent on records written before TLS support. */
+    secure?: boolean;
+    /** The user-facing address (MagicDNS/cert hostname when TLS is on). Optional for old records. */
+    displayHost?: string;
+}
+export declare function writePidFile(record: PidRecord, env?: NodeJS.ProcessEnv): void;
+export declare function readPidFile(env?: NodeJS.ProcessEnv): PidRecord | null;
+export declare function removePidFile(env?: NodeJS.ProcessEnv): void;
+/** signal 0 probes liveness without delivering a signal; EPERM means alive. */
+export declare function isProcessAlive(pid: number): boolean;
+/** The running service record, clearing a stale pid file if the process is gone. */
+export declare function readRunningService(env?: NodeJS.ProcessEnv): PidRecord | null;
+//# sourceMappingURL=pid-lock.d.ts.map

package/dist/service/pid-lock.js

@@ -0,0 +1,50 @@
+/**
+ * The service pid/lock file, following the daemon's `otto.pid` pattern: a small
+ * JSON record of the running brain's pid + bind address under
+ * `$OTTO_HOME/otto-brain/otto-brain.pid`. Lets `otto brain status`/`stop` find a
+ * running instance and lets the Otto daemon supervise a managed child.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { resolveBrainPaths } from "../config/paths.js";
+import { writePrivateFileAtomicSync } from "../config/private-files.js";
+export function writePidFile(record, env = process.env) {
+    const { pidFile } = resolveBrainPaths(env);
+    writePrivateFileAtomicSync(pidFile, `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readPidFile(env = process.env) {
+    const { pidFile } = resolveBrainPaths(env);
+    if (!existsSync(pidFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(pidFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function removePidFile(env = process.env) {
+    const { pidFile } = resolveBrainPaths(env);
+    rmSync(pidFile, { force: true });
+}
+/** signal 0 probes liveness without delivering a signal; EPERM means alive. */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** The running service record, clearing a stale pid file if the process is gone. */
+export function readRunningService(env = process.env) {
+    const record = readPidFile(env);
+    if (!record)
+        return null;
+    if (!isProcessAlive(record.pid)) {
+        removePidFile(env);
+        return null;
+    }
+    return record;
+}
+//# sourceMappingURL=pid-lock.js.map

package/dist/service/router.d.ts

@@ -0,0 +1,144 @@
+import http from "node:http";
+import type { Supervisor } from "./supervisor.js";
+import { type RankedModel } from "../ops/results.js";
+import type { GpuInfo, Model } from "../types.js";
+import type { Profile } from "../config/schema.js";
+type Verdict = "ok" | "reasoning-only" | "truncated" | "failed";
+/** A logger sink; only `warn` is used by the router. */
+export interface Logger {
+    warn(message: string): void;
+}
+/** A source of the catalog: a getter, a snapshot array, or nothing. */
+export type GetCatalog = (() => Model[]) | Model[] | null;
+interface TelemetryTotals {
+    requests: number;
+    ok: number;
+    reasoningOnly: number;
+    truncated: number;
+    failed: number;
+}
+/** One recorded completion outcome; fields vary by streaming vs. buffered. */
+export interface TelemetryRecord {
+    verdict: string;
+    at?: string;
+    path?: string;
+    ms?: number;
+    streamed?: boolean;
+    finishReason?: string | null;
+    contentChars?: number;
+    reasoningChars?: number;
+    outputTokens?: number | null;
+    toolCalls?: number;
+    error?: string;
+}
+/** The verdict of classifying a completion body. */
+export interface Analysis {
+    finishReason: string | null;
+    contentChars: number;
+    reasoningChars: number;
+    outputTokens: number | null;
+    toolCalls: number;
+    verdict: Verdict;
+}
+export declare class Telemetry {
+    keep: number;
+    records: TelemetryRecord[];
+    totals: TelemetryTotals;
+    constructor(keep?: number);
+    record(entry: TelemetryRecord): void;
+    /** Advice derived from observed behaviour, not guesswork. */
+    get warning(): string | null;
+}
+/** Classify a completion body (Anthropic or OpenAI shaped). */
+export declare function analyse(bodyText: string): Analysis | null;
+type ModelState = "loaded" | "loading" | "not-loaded";
+interface DescribeOptions {
+    state?: ModelState;
+    profile?: Profile | null;
+    createdAt?: Date | null;
+}
+/** An LM Studio-style model description, an OpenAI model object enriched. */
+export interface ModelEntry {
+    id: string;
+    object: "model";
+    created: number;
+    owned_by: string;
+    type: "vlm" | "llm";
+    publisher: string | null;
+    arch: string | null;
+    compatibility_type: "gguf";
+    quantization: string | null;
+    state: ModelState;
+    max_context_length: number | null;
+    loaded_context_length?: number;
+}
+/**
+ * Describe one catalog model the way LM Studio's API does. Returns an
+ * OpenAI-style model object enriched with LM Studio's fields (arch,
+ * quantization, state, context lengths) so clients can display the real name
+ * and know the context window. `state` is 'loaded' | 'loading' | 'not-loaded';
+ * `loaded_context_length` is only meaningful for the model actually running.
+ */
+export declare function describeModel(model: Model, options?: DescribeOptions): ModelEntry;
+export declare function describeModel(model: Model | null, options?: DescribeOptions): ModelEntry | null;
+/**
+ * Build the LM Studio-style catalog: every model found on disk, with the one
+ * the supervisor is running marked 'loaded'. Falls back to just the running
+ * model when no catalog provider is wired in.
+ */
+export declare function buildModelList(supervisor: Supervisor, getCatalog: GetCatalog): ModelEntry[];
+export type ModelGateResult = {
+    ok: true;
+    model: Model;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+/**
+ * Pure model-admission decision, factored out of the router so it is unit
+ * testable. `pinned` is the single model a locked host serves; `resolved` is the
+ * normal catalog resolution used when the lock is off. With the lock on, a
+ * request naming a model other than the pin is refused (409) rather than queuing
+ * a switch; an unnamed request rides the pin.
+ */
+export declare function decideModelGate(params: {
+    lockModel: boolean;
+    requestedName: string | null;
+    pinned: Model | null;
+    resolved: Model | null;
+}): ModelGateResult;
+export interface RouterOptions {
+    supervisor: Supervisor;
+    telemetry: Telemetry;
+    logger?: Logger | null;
+    getCatalog?: GetCatalog;
+    loadModel?: ((model: Model) => Promise<void>) | null;
+    loadRanking?: () => RankedModel[];
+    queryGpuInfo?: () => Promise<GpuInfo | null>;
+    /** The brain package version, reported on `/__host/status` for the host UI. */
+    version?: string | null;
+    /** Effective config with secrets redacted — served on `/__host/config`. */
+    getConfig?: (() => unknown) | null;
+    /** Benchmark rankings/variance/latest — served on `/__host/evals`. */
+    getEvals?: (() => unknown) | null;
+    /** Live: pin the host to one model (refuse completions naming a different one). */
+    getLockModel?: () => boolean;
+    /** Live: the configured default model, the pin target before one is resident. */
+    getDefaultModel?: () => string | null;
+    /**
+     * Apply an editable config patch (write config.json, live-switch the model,
+     * update the lock), for POST /__host/config. Absent = the write endpoint is
+     * not offered. Returns the new effective config (secrets redacted).
+     */
+    applyConfigPatch?: ((patch: unknown) => Promise<unknown>) | null;
+    /**
+     * Live: whether remote clients may WRITE config (POST /__host/config). Off by
+     * default, so a shared brain can be used but not reconfigured over the network
+     * until its owner opts in. Read/use are unaffected.
+     */
+    getAllowConfigWrite?: () => boolean;
+}
+export declare function createRouter({ supervisor, telemetry, logger, getCatalog, loadModel, loadRanking, queryGpuInfo, version, getConfig, getEvals, getLockModel, getDefaultModel, applyConfigPatch, getAllowConfigWrite, }: RouterOptions): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+export {};
+//# sourceMappingURL=router.d.ts.map