// Per-model settings: one schema, one validator, one resolver (GH-14). // // They live under `models` in ~/.pi/agent/pi-ollama.json // (config.ts), keyed by exact model id. A model's own value wins over the // global one (the file's top level, set by the slash commands, else the env // var). Keys starting with "_" are comments and are ignored everywhere. // // The file is hand-edited, so nothing in it is trusted: an invalid value is // dropped and reported, and the setting falls through to the global one. // // What is deliberately NOT here: per-model context window and output limit // (pi's models.json `modelOverrides` already does both for extension models) // and sampling / GPU options (an Ollama Modelfile sets those on the server). // // No runtime imports, so it can be tested on its own. export type Severity = "error" | "warning"; export interface ConfigIssue { severity: Severity; /** Where in the file, e.g. models["gemma4:12b"].keepAlive */ path: string; /** Reads after the path, e.g. `= "banana" must be ... - ignored`. */ message: string; } /** pi's thinking levels, in order. */ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const; export type ThinkingLevelName = (typeof THINKING_LEVELS)[number]; export interface ModelSettings { keepAlive?: string | number; warm?: boolean; /** * What happens to the model once the user leaves it (release.ts): 0 unloads * it at once, a duration that long after, "keep" leaves it loaded. */ releaseAfter?: string | number; /** Name of a `servers` entry this model lives on. Absent = the default server. */ server?: string; /** The thinking level that loads when this model becomes active (thinking-default.ts). */ thinkingLevel?: ThinkingLevelName; } /** An Ollama other than the default one, that models can be pinned to. */ export interface ServerEntry { /** Normalized: scheme and port filled in, no trailing slash. */ baseUrl: string; } export interface ModelConfigFile { /** Null-prototype map, so ids like "__proto__" are plain entries. */ models: Record; /** Named servers, by name. Null-prototype map. */ servers: Record; } export function emptyModelConfig(): ModelConfigFile { return { models: Object.create(null) as Record, servers: Object.create(null) as Record, }; } // ── validators: return why a value is invalid, or undefined when it's fine ── type Check = (v: unknown) => string | undefined; function isObject(v: unknown): v is Record { return typeof v === "object" && v !== null && !Array.isArray(v); } const bool: Check = (v) => (typeof v === "boolean" ? undefined : "must be true or false"); // The same Go-style duration settings.ts accepts for keep_alive. const GO_DURATION_RE = /^(\d+(\.\d+)?(ns|us|µs|ms|s|m|h))+$/; const keepAliveCheck: Check = (v) => { if (typeof v === "number" && Number.isInteger(v)) return undefined; if (typeof v === "string" && GO_DURATION_RE.test(v)) return undefined; return 'must be a duration like "30m" / "1h30m" or a whole number of seconds (-1 = keep loaded)'; }; /** * Why a releaseAfter value is invalid, or undefined when it's fine. "keep" * means leaving the model doesn't unload it; it has to be said explicitly * because unloading at once is the default. Shared with the global setting * (settings.ts, keep-alive-command.ts). */ export const releaseAfterCheck: Check = (v) => { if (v === "keep") return undefined; if (typeof v === "number" && Number.isInteger(v) && v >= 0) return undefined; if (typeof v === "string" && GO_DURATION_RE.test(v)) return undefined; return 'must be 0 (unload at once), a duration like "10m" / "1h30m", a whole number of seconds, or "keep" (don\'t unload it for leaving)'; }; /** `server` is checked against the servers block, which needs more than the value. */ const MODEL_FIELDS: Record, Check> = { keepAlive: keepAliveCheck, warm: bool, releaseAfter: releaseAfterCheck, thinkingLevel: (v) => typeof v === "string" && (THINKING_LEVELS as readonly string[]).includes(v) ? undefined : `must be one of ${THINKING_LEVELS.join(", ")}`, }; /** Ollama's own default port, used when a host gives neither a scheme nor a port. */ const OLLAMA_PORT = 11434; /** * A server address as a base URL, or why it can't be used. Accepts what * OLLAMA_HOST accepts ("host", "host:port", or a full http(s) URL, which may * carry a reverse-proxy path). Refuses anything that could send requests, or * a secret, somewhere unintended: other protocols, embedded credentials, a * query or a fragment. The reason never repeats the value, since the value * may contain a password. */ export function normalizeServerHost(raw: unknown): { baseUrl: string } | { reason: string } { if (typeof raw !== "string" || raw.trim() === "") { return { reason: 'must be an address like "10.0.0.5:11434" or "https://ollama.home"' }; } const text = raw.trim(); if (/\s/.test(text)) return { reason: "must not contain spaces" }; const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text); let url: URL; try { url = new URL(hasScheme ? text : `http://${text}`); } catch { return { reason: 'must be an address like "10.0.0.5:11434" or "https://ollama.home"' }; } if (url.protocol !== "http:" && url.protocol !== "https:") { return { reason: "must use http:// or https://" }; } if (url.username || url.password) return { reason: "must not contain a username or password" }; if (url.search || url.hash) return { reason: "must not contain a query or a fragment" }; // A bare host means "Ollama on that machine": its port, not the web's. if (!hasScheme && url.port === "") url.port = String(OLLAMA_PORT); return { baseUrl: url.toString().replace(/\/+$/, "") }; } const USE_MODEL_OVERRIDES = (field: string) => `is not set here - use modelOverrides in pi's models.json ("${field}") - ignored`; const USE_MODELFILE = "is not set here - use PARAMETER lines in an Ollama Modelfile - ignored"; /** Settings people reasonably expect here, and where they live instead. */ const ELSEWHERE: Record = { contextLength: USE_MODEL_OVERRIDES("contextWindow"), contextWindow: USE_MODEL_OVERRIDES("contextWindow"), maxTokens: USE_MODEL_OVERRIDES("maxTokens"), sampling: USE_MODELFILE, gpu: USE_MODELFILE, }; // ── loading ── const show = (v: unknown): string => JSON.stringify(v) ?? String(v); const own = (o: object, key: string) => Object.prototype.hasOwnProperty.call(o, key); function validateModel( raw: Record, path: string, servers: Record, issues: ConfigIssue[], ): ModelSettings { const out: Record = {}; for (const [key, value] of Object.entries(raw)) { if (key.startsWith("_")) continue; const keyPath = `${path}.${key}`; if (key === "server") { if (typeof value !== "string" || value === "") { issues.push({ severity: "error", path: keyPath, message: `= ${show(value)} must be the name of an entry in servers - ignored`, }); } else if (!own(servers, value)) { const defined = Object.keys(servers); issues.push({ severity: "error", path: keyPath, message: `= ${show(value)} is not one of the servers defined (${defined.length ? defined.join(", ") : "none are"}) - using the default server`, }); } else { out[key] = value; } continue; } if (own(MODEL_FIELDS, key)) { const reason = MODEL_FIELDS[key as keyof typeof MODEL_FIELDS](value); if (reason) { issues.push({ severity: "error", path: keyPath, message: `= ${show(value)} ${reason} - ignored` }); } else { out[key] = value; } continue; } issues.push({ severity: "warning", path: keyPath, message: own(ELSEWHERE, key) ? (ELSEWHERE[key] as string) : "is not a known setting - ignored", }); } return out as ModelSettings; } function validateServers(raw: unknown, issues: ConfigIssue[]): Record { const out = Object.create(null) as Record; if (raw === undefined) return out; if (!isObject(raw)) { issues.push({ severity: "error", path: "servers", message: `= ${show(raw)} must be an object - ignored` }); return out; } for (const [name, entry] of Object.entries(raw)) { if (name.startsWith("_")) continue; const path = `servers[${JSON.stringify(name)}]`; if (!isObject(entry)) { issues.push({ severity: "error", path, message: `= ${show(entry)} must be an object like { "host": "10.0.0.5:${OLLAMA_PORT}" } - ignored`, }); continue; } const host = normalizeServerHost(entry.host); if ("reason" in host) { // The value is left out on purpose: it may hold a password. issues.push({ severity: "error", path: `${path}.host`, message: `${host.reason} - server ignored` }); continue; } for (const key of Object.keys(entry)) { if (key !== "host" && !key.startsWith("_")) { issues.push({ severity: "warning", path: `${path}.${key}`, message: "is not a known setting - ignored" }); } } out[name] = host; } return out; } /** * Validate the `servers` and `models` blocks of the parsed config file. * Invalid values are dropped and reported as errors, so they fall through to * the global setting or the default server; unknown keys are warnings. The * file's other keys belong to settings.ts. */ export function loadModelConfig(raw: unknown): { config: ModelConfigFile; issues: ConfigIssue[] } { const issues: ConfigIssue[] = []; const config = emptyModelConfig(); if (!isObject(raw)) return { config, issues }; config.servers = validateServers(raw.servers, issues); if (raw.models === undefined) return { config, issues }; if (!isObject(raw.models)) { issues.push({ severity: "error", path: "models", message: `= ${show(raw.models)} must be an object - ignored` }); return { config, issues }; } for (const [id, entry] of Object.entries(raw.models)) { if (id.startsWith("_")) continue; const path = `models[${JSON.stringify(id)}]`; if (!isObject(entry)) { issues.push({ severity: "error", path, message: `= ${show(entry)} must be an object - ignored` }); continue; } config.models[id] = validateModel(entry, path, config.servers, issues); } return { config, issues }; } /** The base URL of the server a model is pinned to, or undefined for the default server. */ export function serverUrlFor(config: ModelConfigFile | undefined, modelId: string): string | undefined { if (!config || !own(config.models, modelId)) return undefined; const name = config.models[modelId]?.server; return name !== undefined && own(config.servers, name) ? config.servers[name]?.baseUrl : undefined; } // ── resolving ── /** The global layer: the file's top level, else the env var (settings.ts resolves both). */ export interface GlobalSettings { keepAlive?: string | number; warm: boolean; releaseAfter?: string | number; } export interface ResolvedModelSettings { /** Absent means the field is left out of the request and the server decides. */ keepAlive?: string | number; warm: boolean; /** 0 = unload when the user leaves it (the default), a duration, or "keep". */ releaseAfter: string | number; /** Only ever a model's own: there is no global thinking level here, pi has that. */ thinkingLevel?: ThinkingLevelName; } /** A used model is unloaded as soon as the user leaves it, unless they chose otherwise. */ export const DEFAULT_RELEASE_AFTER = 0; /** One model's effective settings: its own entry, else the global value. */ export function resolveModelSettings( config: ModelConfigFile | undefined, global: GlobalSettings, modelId: string | undefined, ): ResolvedModelSettings { const entry: ModelSettings = config && modelId !== undefined && own(config.models, modelId) ? (config.models[modelId] ?? {}) : {}; const keepAlive = entry.keepAlive ?? global.keepAlive; return { ...(keepAlive !== undefined && { keepAlive }), warm: entry.warm ?? global.warm, releaseAfter: entry.releaseAfter ?? global.releaseAfter ?? DEFAULT_RELEASE_AFTER, ...(entry.thinkingLevel !== undefined && { thinkingLevel: entry.thinkingLevel }), }; } // ── reporting ── export function formatIssue(issue: ConfigIssue): string { return `pi-ollama config: ${issue.path} ${issue.message}`; }