@atomic-chat/core 0.5.1 → 0.13.2

package/dist/decision/args.js

@@ -0,0 +1,126 @@
+/**
+ * The decision process's argv, environment and thread count. Pure.
+ *
+ * Built here and never through the chat `args.ts`: that builder serves chat and embedding sessions
+ * (a GGUF without a chat head gets `--embedding --pooling mean`), and none of its flags mean anything
+ * to `--decision`, which ignores most of them with a warning. The argv follows DECISION.md:
+ *
+ *   llama-server --decision -m <gguf | checkpoint dir> [--decision-spec <file>] [-a <id>]
+ *                [--decision-convert-cache <dir> --decision-convert-type <f16|f32>] --device none -t <n>
+ *                --host 127.0.0.1 --port <p> --no-webui [--decision-allow-uncalibrated]
+ *
+ * The key travels in `LLAMA_API_KEY`, never in argv, where any local user could read it with `ps`.
+ *
+ * `-t` is always passed. The engine's precedence (atomic-llama-cpp-turboquant `server-decision.cpp`,
+ * `engine-laya.cpp`): the laya engine runs with `-t`, or without it llama.cpp's own default
+ * (`common_cpu_get_num_math`: the performance cores on Apple silicon and on hybrid Linux x86, the
+ * physical cores elsewhere, uncapped). A spec's `plan.n_threads` is never applied: the engine only
+ * warns when it differs from the thread count it runs with, because logits are bitwise stable only
+ * for a fixed count. So leaving `-t` out would not hand the choice to the spec, only to llama.cpp,
+ * and would lose the cap below.
+ */
+import { isAbsolute, join, win32 } from 'node:path';
+/** The environment variable the server's auth middleware reads (as `--api-key`), the fork's and upstream's. */
+export const DECISION_API_KEY_ENV = 'LLAMA_API_KEY';
+/**
+ * Where checkpoint folders are converted to, relative to the data folder. Ours rather than the
+ * engine's default (the OS user cache): it goes away with the app's data and does not depend on
+ * `LLAMA_CACHE`. The engine never deletes old entries; the decision service does.
+ */
+export const DECISION_CONVERT_CACHE_DIR = join('decision', 'gguf-cache');
+/**
+ * A configured file as an absolute path: absolute as given, relative against the data folder, empty
+ * as `undefined`. The core invents no folder for decision models; the app decides where they live.
+ */
+export function resolveDataPath(dataFolder, configured) {
+    const trimmed = configured.trim();
+    if (trimmed === '')
+        return undefined;
+    return isAbsolute(trimmed) || win32.isAbsolute(trimmed) ? trimmed : join(dataFolder, trimmed);
+}
+/** Loopback only: the public server forwards to it, nothing else should reach it. */
+export const DECISION_HOST = '127.0.0.1';
+/**
+ * Ceiling of the automatic thread count. The laya encoder is one CPU graph per request, and the chat
+ * model runs beside it; past eight threads the decision model mostly competes with the chat model
+ * (plan KPI K8) instead of getting faster. An explicit `threads` setting is not capped.
+ */
+export const MAX_AUTO_THREADS = 8;
+export function buildDecisionArgs(spec) {
+    const argv = ['--decision', '-m', spec.modelPath];
+    if (spec.specPath)
+        argv.push('--decision-spec', spec.specPath);
+    if (spec.modelId)
+        argv.push('-a', spec.modelId);
+    if (spec.convert)
+        argv.push('--decision-convert-cache', spec.convert.cacheDir, '--decision-convert-type', spec.convert.type);
+    // The laya engine is CPU only and ignores `--device`; it is still said out loud so a future engine
+    // that could use a GPU does not take VRAM the chat model counted on.
+    argv.push('--device', 'none');
+    argv.push('-t', String(spec.threads));
+    argv.push('--host', DECISION_HOST, '--port', String(spec.port));
+    argv.push('--no-webui');
+    if (spec.allowUncalibrated)
+        argv.push('--decision-allow-uncalibrated');
+    return argv;
+}
+/**
+ * The argv of stock llama.cpp (b11370 on) for a GGUF with `<arch>.decision.type`: no decision flag,
+ * the server reads the type from the file and serves `/v1/systemone` (and turns on embedding mode
+ * itself where the type needs it). No `--device none`: upstream decision models run up to 27B
+ * parameters, and the server's own fitting puts them on the GPU when there is room.
+ *
+ *   llama-server -m <gguf> [--mmproj <file>] [-a <id>] -c <n> -b <n> [-ub <n>] -t <n>
+ *                --host 127.0.0.1 --port <p> --no-webui
+ */
+export function buildUpstreamDecisionArgs(spec, upstream) {
+    const argv = ['-m', spec.modelPath];
+    if (upstream.mmprojPath)
+        argv.push('--mmproj', upstream.mmprojPath);
+    if (spec.modelId)
+        argv.push('-a', spec.modelId);
+    const ctx = String(upstream.ctxSize);
+    argv.push('-c', ctx, '-b', ctx);
+    if (upstream.wholePromptUbatch)
+        argv.push('-ub', ctx);
+    argv.push('-t', String(spec.threads));
+    argv.push('--host', DECISION_HOST, '--port', String(spec.port));
+    argv.push('--no-webui');
+    return argv;
+}
+/** The variables the core adds to the inherited environment. */
+export function decisionEnv(apiKey) {
+    return { [DECISION_API_KEY_ENV]: apiKey };
+}
+/** The engine reads its `--decision-*` flags from these variables too (DECISION.md, Flags). */
+export const DECISION_ENV_PREFIX = 'LLAMA_ARG_DECISION_';
+/**
+ * The inherited environment without `LLAMA_ARG_DECISION_*`: a stray `LLAMA_ARG_DECISION_DEBUG` in the
+ * owner's environment would turn on request logging and raw logits, and `…_QUEUE` or `…_PLAN` would
+ * change what the core asked for. The core states every decision flag it wants in argv. Matched
+ * without case, as Windows names are.
+ */
+export function withoutDecisionEnv(env) {
+    const out = {};
+    for (const [name, value] of Object.entries(env))
+        if (!name.toUpperCase().startsWith(DECISION_ENV_PREFIX))
+            out[name] = value;
+    return out;
+}
+/** `-t`: the setting when given, else the performance cores (or a guess at them), 1 … `MAX_AUTO_THREADS`. */
+export function decisionThreads(facts) {
+    if (Number.isInteger(facts.setting) && facts.setting > 0)
+        return facts.setting;
+    const physical = Number.isInteger(facts.physicalCores) && facts.physicalCores > 0 ? facts.physicalCores : 1;
+    let auto = physical;
+    if (facts.performanceCores !== undefined && facts.performanceCores > 0)
+        auto = facts.performanceCores;
+    else if (facts.hybrid)
+        auto = Math.ceil(physical / 2);
+    return Math.max(1, Math.min(MAX_AUTO_THREADS, auto));
+}
+/** The argv as the log shows it: the model path kept (it is not a secret), nothing else to hide. */
+export function commandSummary(exe, argv) {
+    return [exe, ...argv].map((part) => (/\s/.test(part) ? JSON.stringify(part) : part)).join(' ');
+}
+//# sourceMappingURL=args.js.map

package/dist/decision/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/decision/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAGnD,+GAA+G;AAC/G,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAA;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA;AAExE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,UAAkB;IACpE,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAA;IACjC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IACpC,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;AAC/F,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAkBjC,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,MAAM,IAAI,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACjD,IAAI,IAAI,CAAC,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC9D,IAAI,IAAI,CAAC,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAC/C,IAAI,IAAI,CAAC,OAAO;QACd,IAAI,CAAC,IAAI,CAAC,0BAA0B,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5G,mGAAmG;IACnG,qEAAqE;IACrE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;IACrC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/D,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;IACvB,IAAI,IAAI,CAAC,iBAAiB;QAAE,IAAI,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAA;IACtE,OAAO,IAAI,CAAA;AACb,CAAC;AAYD;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACvC,IAA4E,EAC5E,QAAgC;IAEhC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACnC,IAAI,QAAQ,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;IACnE,IAAI,IAAI,CAAC,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACpC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;IAC/B,IAAI,QAAQ,CAAC,iBAAiB;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IACrD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;IACrC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/D,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;IACvB,OAAO,IAAI,CAAA;AACb,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;AAC3C,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAA;AAExD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,GAAG,GAAsB,EAAE,CAAA;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IAC5E,OAAO,GAAG,CAAA;AACZ,CAAC;AAiBD,6GAA6G;AAC7G,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAA;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3G,IAAI,IAAI,GAAG,QAAQ,CAAA;IACnB,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC;QAAE,IAAI,GAAG,KAAK,CAAC,gBAAgB,CAAA;SAChG,IAAI,KAAK,CAAC,MAAM;QAAE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAA;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAA;AACtD,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,IAAuB;IACjE,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAChG,CAAC"}

package/dist/decision/backoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * When to bring a crashed decision process back, and when to stop trying. Pure.
+ *
+ * Only a process that was ready and then died is restarted. A start that fails (a bad model file, an
+ * engine that refuses the spec) fails the same way the next time, so it goes straight to `failed`
+ * and waits for the user: a new setting or an explicit load.
+ */
+export declare const RESTART_BASE_DELAY_MS = 1000;
+export declare const RESTART_MAX_DELAY_MS = 30000;
+/**
+ * Restarts in a row the module attempts. The crash after the last of them (the sixth in a row) gives
+ * up and reports `failed`, with `restarts: MAX_RESTARTS + 1`.
+ */
+export declare const MAX_RESTARTS = 5;
+/** A process that stayed up this long wipes the crash count: the next crash is a first one again. */
+export declare const STABLE_RUN_MS = 60000;
+/** 1 s, 2 s, 4 s, … capped at 30 s, for the `attempt`-th restart (1-based). */
+export declare function restartDelayMs(attempt: number, base?: number, max?: number): number;
+/**
+ * The crash count after one more crash: reset first when the process had run long enough to count
+ * as healthy.
+ */
+export declare function nextRestartCount(previous: number, ranForMs: number, stableMs?: number): number;
+/** Whether the `restarts`-th crash in a row is one too many: `restarts > max`. */
+export declare function shouldGiveUp(restarts: number, max?: number): boolean;

package/dist/decision/backoff.js

@@ -0,0 +1,33 @@
+/**
+ * When to bring a crashed decision process back, and when to stop trying. Pure.
+ *
+ * Only a process that was ready and then died is restarted. A start that fails (a bad model file, an
+ * engine that refuses the spec) fails the same way the next time, so it goes straight to `failed`
+ * and waits for the user: a new setting or an explicit load.
+ */
+export const RESTART_BASE_DELAY_MS = 1_000;
+export const RESTART_MAX_DELAY_MS = 30_000;
+/**
+ * Restarts in a row the module attempts. The crash after the last of them (the sixth in a row) gives
+ * up and reports `failed`, with `restarts: MAX_RESTARTS + 1`.
+ */
+export const MAX_RESTARTS = 5;
+/** A process that stayed up this long wipes the crash count: the next crash is a first one again. */
+export const STABLE_RUN_MS = 60_000;
+/** 1 s, 2 s, 4 s, … capped at 30 s, for the `attempt`-th restart (1-based). */
+export function restartDelayMs(attempt, base = RESTART_BASE_DELAY_MS, max = RESTART_MAX_DELAY_MS) {
+    const n = Math.max(1, Math.floor(attempt));
+    return Math.min(max, base * 2 ** Math.min(n - 1, 30));
+}
+/**
+ * The crash count after one more crash: reset first when the process had run long enough to count
+ * as healthy.
+ */
+export function nextRestartCount(previous, ranForMs, stableMs = STABLE_RUN_MS) {
+    return (ranForMs >= stableMs ? 0 : previous) + 1;
+}
+/** Whether the `restarts`-th crash in a row is one too many: `restarts > max`. */
+export function shouldGiveUp(restarts, max = MAX_RESTARTS) {
+    return restarts > max;
+}
+//# sourceMappingURL=backoff.js.map

package/dist/decision/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/decision/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAA;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAA;AAC1C;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA;AAC7B,qGAAqG;AACrG,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAA;AAEnC,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAI,GAAG,qBAAqB,EAC5B,GAAG,GAAG,oBAAoB;IAE1B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,QAAgB,EAAE,QAAQ,GAAG,aAAa;IAC3F,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AAClD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,GAAG,GAAG,YAAY;IAC/D,OAAO,QAAQ,GAAG,GAAG,CAAA;AACvB,CAAC"}

package/dist/decision/engine-candidates.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which installed packs may run the decision model, in the order they are tried. Pure.
+ *
+ * Every pack of the model's engine is a candidate, whether or not that provider is the one the user
+ * picked for chat: the decision model is a separate process, so the chat provider's flag says
+ * nothing about it.
+ *
+ * The fork's packs (`<data>/llamacpp/backends/`, `orderEngineCandidates`):
+ *  1. packs whose tag is at or above 1.7.0, then tags without a semver, then older tags (a dev build
+ *     can serve `--decision` under an old number, so older tags are still probed, last);
+ *  2. newer upstream builds first;
+ *  3. inside one version, the pack that runs on the CPU with the fewest extra libraries first: the
+ *     decision model is started with `--device none`, and a CUDA or ROCm pack may not even start
+ *     without its runtime libraries.
+ *
+ * Upstream packs (`<data>/llamacpp-upstream/backends/`, `orderUpstreamCandidates`): only tags at or
+ * above the model's floor. The build the user runs `llamacpp-upstream` chat on goes first when it is
+ * one of them: it is the one known to work on this machine, and a GPU kind the user did not pick (a
+ * ROCm pack beside the recommended Vulkan one) may not run on this card at all. Then newest first,
+ * the picked build's backend first inside a release, then GPU packs before CPU ones: upstream
+ * decision models run up to 27B parameters and are started on the GPU when the pack has one.
+ */
+import type { DecisionEngineInfo } from '../contracts/index.js';
+export interface InstalledEnginePack {
+    version: string;
+    backend: string;
+    /** The pack's `llama-server`. */
+    path: string;
+}
+export interface EngineCandidate extends InstalledEnginePack {
+    info: DecisionEngineInfo;
+}
+/** Lower is tried first. */
+export declare function backendPreference(backend: string): number;
+export declare function engineInfoOf(pack: InstalledEnginePack): DecisionEngineInfo;
+/**
+ * Lower is tried first: the GPU packs, then the CPU ones. Upstream names its plain builds without a
+ * `cpu` marker (`ubuntu-x64`, `win-cpu-x64`), so anything without a GPU marker counts as CPU.
+ */
+export declare function upstreamBackendPreference(backend: string): number;
+export interface UpstreamCandidates {
+    /** Packs new enough for the model, in the order to try them. */
+    eligible: EngineCandidate[];
+    /** Installed packs older than the floor (or with a tag that is not a build number). */
+    tooOld: InstalledEnginePack[];
+}
+/**
+ * `preferred` is the `llamacpp-upstream` build the user picked (`version_backend`, `b11463/win-vulkan-x64`);
+ * empty or not installed, the order is the release's and the GPU kind's alone.
+ */
+export declare function orderUpstreamCandidates(packs: readonly InstalledEnginePack[], minBuild: number, preferred?: string): UpstreamCandidates;
+export declare function orderEngineCandidates(packs: readonly InstalledEnginePack[]): EngineCandidate[];

package/dist/decision/engine-candidates.js

@@ -0,0 +1,138 @@
+/**
+ * Which installed packs may run the decision model, in the order they are tried. Pure.
+ *
+ * Every pack of the model's engine is a candidate, whether or not that provider is the one the user
+ * picked for chat: the decision model is a separate process, so the chat provider's flag says
+ * nothing about it.
+ *
+ * The fork's packs (`<data>/llamacpp/backends/`, `orderEngineCandidates`):
+ *  1. packs whose tag is at or above 1.7.0, then tags without a semver, then older tags (a dev build
+ *     can serve `--decision` under an old number, so older tags are still probed, last);
+ *  2. newer upstream builds first;
+ *  3. inside one version, the pack that runs on the CPU with the fewest extra libraries first: the
+ *     decision model is started with `--device none`, and a CUDA or ROCm pack may not even start
+ *     without its runtime libraries.
+ *
+ * Upstream packs (`<data>/llamacpp-upstream/backends/`, `orderUpstreamCandidates`): only tags at or
+ * above the model's floor. The build the user runs `llamacpp-upstream` chat on goes first when it is
+ * one of them: it is the one known to work on this machine, and a GPU kind the user did not pick (a
+ * ROCm pack beside the recommended Vulkan one) may not run on this card at all. Then newest first,
+ * the picked build's backend first inside a release, then GPU packs before CPU ones: upstream
+ * decision models run up to 27B parameters and are started on the GPU when the pack has one.
+ */
+import { meetsForkVersion, parseForkSemver, formatSemver } from './engine-version.js';
+import { meetsUpstreamBuild, upstreamBuildOf } from './upstream-version.js';
+/** `b10269-1.7.0` → 10269; anything else sorts as 0. */
+function buildOf(version) {
+    const match = /^b(\d+)/.exec(version.trim());
+    return match ? Number(match[1]) : 0;
+}
+/** Lower is tried first. */
+export function backendPreference(backend) {
+    const id = backend.toLowerCase();
+    if (id.includes('cpu'))
+        return 0;
+    if (id.startsWith('macos'))
+        return 1;
+    if (id.includes('vulkan'))
+        return 2;
+    return 3;
+}
+function gateRank(gate) {
+    if (gate === true)
+        return 0;
+    if (gate === undefined)
+        return 1;
+    return 2;
+}
+export function engineInfoOf(pack) {
+    const semver = parseForkSemver(pack.version);
+    const gate = meetsForkVersion(pack.version);
+    return {
+        path: pack.path,
+        version_backend: `${pack.version}/${pack.backend}`,
+        fork_version: semver ? formatSemver(semver) : null,
+        version_gate: gate ?? null,
+        dialect: 'turboquant',
+        provider: 'llamacpp',
+    };
+}
+/**
+ * Lower is tried first: the GPU packs, then the CPU ones. Upstream names its plain builds without a
+ * `cpu` marker (`ubuntu-x64`, `win-cpu-x64`), so anything without a GPU marker counts as CPU.
+ */
+export function upstreamBackendPreference(backend) {
+    const id = backend.toLowerCase();
+    if (id.startsWith('macos'))
+        return 0;
+    if (id.includes('cuda'))
+        return 1;
+    if (id.includes('rocm') || id.includes('hip'))
+        return 2;
+    if (id.includes('vulkan'))
+        return 3;
+    if (id.includes('sycl') || id.includes('openvino') || id.includes('opencl'))
+        return 4;
+    return 5;
+}
+/**
+ * `preferred` is the `llamacpp-upstream` build the user picked (`version_backend`, `b11463/win-vulkan-x64`);
+ * empty or not installed, the order is the release's and the GPU kind's alone.
+ */
+export function orderUpstreamCandidates(packs, minBuild, preferred = '') {
+    const eligible = [];
+    const tooOld = [];
+    for (const pack of packs) {
+        if (meetsUpstreamBuild(pack.version, minBuild) !== true) {
+            tooOld.push(pack);
+            continue;
+        }
+        eligible.push({
+            ...pack,
+            info: {
+                path: pack.path,
+                version_backend: `${pack.version}/${pack.backend}`,
+                fork_version: null,
+                version_gate: true,
+                dialect: 'upstream',
+                provider: 'llamacpp-upstream',
+            },
+        });
+    }
+    const picked = preferred.trim();
+    const pickedBackend = picked.slice(picked.indexOf('/') + 1);
+    const rank = (pack, key) => (key(pack) ? 0 : 1);
+    eligible.sort((a, b) => {
+        const exact = (pack) => picked !== '' && pack.info.version_backend === picked;
+        const first = rank(a, exact) - rank(b, exact);
+        if (first !== 0)
+            return first;
+        const build = (upstreamBuildOf(b.version) ?? 0) - (upstreamBuildOf(a.version) ?? 0);
+        if (build !== 0)
+            return build;
+        const sameKind = (pack) => picked.includes('/') && pack.backend === pickedBackend;
+        const kind = rank(a, sameKind) - rank(b, sameKind);
+        if (kind !== 0)
+            return kind;
+        const backend = upstreamBackendPreference(a.backend) - upstreamBackendPreference(b.backend);
+        return backend !== 0 ? backend : a.backend.localeCompare(b.backend);
+    });
+    return { eligible, tooOld };
+}
+export function orderEngineCandidates(packs) {
+    return packs
+        .map((pack) => ({ ...pack, info: engineInfoOf(pack) }))
+        .sort((a, b) => {
+        const gate = gateRank(a.info.version_gate ?? undefined) - gateRank(b.info.version_gate ?? undefined);
+        if (gate !== 0)
+            return gate;
+        const build = buildOf(b.version) - buildOf(a.version);
+        if (build !== 0)
+            return build;
+        const backend = backendPreference(a.backend) - backendPreference(b.backend);
+        if (backend !== 0)
+            return backend;
+        return a.version === b.version ? a.backend.localeCompare(b.backend) : b.version.localeCompare(a.version);
+    });
+}
+//# sourceMappingURL=engine-candidates.js.map

package/dist/decision/engine-candidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-candidates.js","sourceRoot":"","sources":["../../src/decision/engine-candidates.ts"],"names":[],"mappings":"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"}

package/dist/decision/engine-fallback.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Starting the first installed engine build that runs, for the decision and the embedding module: both
+ * resolve a build through their engine gate, spawn it, and hand a build that will not run back to the
+ * gate (`reject`) so the next resolve skips it.
+ *
+ * A build will not run when readiness refused it as unsupported (`unsupportedCode`: an API version this
+ * core does not speak), or when it died before it was ready (`MODEL_LOAD_FAILED`: it crashed while
+ * loading, or could not be spawned). The second is a build matter as often as the first: a ROCm build
+ * whose rocBLAS has no kernels for the card's gfx target loads the model and dies on its first matrix
+ * product (`hipErrorInvalidKernelFile`), while the Vulkan build of the same release runs. A start used
+ * to stop at that crash with the Vulkan build never tried.
+ *
+ * An explicit engine path has nothing to fall back to. When a build crashed and no other is left, the
+ * start fails with that crash and its output, not with "no build can run the model", which would hide
+ * why; the gate's list of every build it tried goes along in the details.
+ */
+/** Builds a start may skip, before it gives up. */
+export declare const MAX_ENGINE_ATTEMPTS = 8;
+export interface EngineFallbackOptions<E extends {
+    path: string;
+}, H> {
+    /** `decision` or `embedding`, for the log. */
+    label: string;
+    /** The gate's answer: the next build to try. Throws `unsupportedCode` when none is left. */
+    resolve: () => Promise<E>;
+    /** Called with every resolved build, before it is started. */
+    onEngine: (engine: E) => void;
+    /** Throws when the start was stopped meanwhile. */
+    throwIfStopped: () => void;
+    spawn: (engine: E) => Promise<H>;
+    /** The module's "this build cannot run the model" code. */
+    unsupportedCode: string;
+    /** An engine path the settings name: refusals end the start. */
+    explicit: boolean;
+    /** Skip `exe` from now on (the gate's `reject`); absent, nothing falls back. */
+    reject?: (exe: string, why: string) => Promise<void>;
+    log: (level: 'warn', msg: string) => void;
+}
+export declare function spawnOnFirstGoodEngine<E extends {
+    path: string;
+}, H>(options: EngineFallbackOptions<E, H>): Promise<H>;

package/dist/decision/engine-fallback.js

@@ -0,0 +1,57 @@
+/**
+ * Starting the first installed engine build that runs, for the decision and the embedding module: both
+ * resolve a build through their engine gate, spawn it, and hand a build that will not run back to the
+ * gate (`reject`) so the next resolve skips it.
+ *
+ * A build will not run when readiness refused it as unsupported (`unsupportedCode`: an API version this
+ * core does not speak), or when it died before it was ready (`MODEL_LOAD_FAILED`: it crashed while
+ * loading, or could not be spawned). The second is a build matter as often as the first: a ROCm build
+ * whose rocBLAS has no kernels for the card's gfx target loads the model and dies on its first matrix
+ * product (`hipErrorInvalidKernelFile`), while the Vulkan build of the same release runs. A start used
+ * to stop at that crash with the Vulkan build never tried.
+ *
+ * An explicit engine path has nothing to fall back to. When a build crashed and no other is left, the
+ * start fails with that crash and its output, not with "no build can run the model", which would hide
+ * why; the gate's list of every build it tried goes along in the details.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+/** Builds a start may skip, before it gives up. */
+export const MAX_ENGINE_ATTEMPTS = 8;
+export async function spawnOnFirstGoodEngine(options) {
+    let crash;
+    for (let attempt = 1;; attempt++) {
+        let engine;
+        try {
+            engine = await options.resolve();
+        }
+        catch (error) {
+            if (crash !== undefined && error instanceof AtomicCoreError && error.code === options.unsupportedCode)
+                throw new AtomicCoreError(crash.code, crash.message, [error.details, crash.details].filter((part) => part !== undefined && part !== '').join('\n\n') ||
+                    undefined);
+            throw error;
+        }
+        options.onEngine(engine);
+        options.throwIfStopped();
+        try {
+            return await options.spawn(engine);
+        }
+        catch (error) {
+            const refused = error instanceof AtomicCoreError && error.code === options.unsupportedCode;
+            const died = error instanceof AtomicCoreError && error.code === 'MODEL_LOAD_FAILED';
+            const fallback = (refused || died) &&
+                !options.explicit &&
+                options.reject !== undefined &&
+                attempt < MAX_ENGINE_ATTEMPTS;
+            if (!fallback)
+                throw error;
+            const failure = error;
+            // A crash's own output stays with the crash; the gate keeps one line for its list.
+            const why = died ? failure.message : (failure.details ?? failure.message);
+            if (died)
+                crash = failure;
+            options.log('warn', `${options.label} engine ${engine.path} ${died ? 'failed to start' : 'refused at readiness'}, trying the next: ${why}`);
+            await options.reject?.(engine.path, why);
+        }
+    }
+}
+//# sourceMappingURL=engine-fallback.js.map

package/dist/decision/engine-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-fallback.js","sourceRoot":"","sources":["../../src/decision/engine-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,mDAAmD;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAqBpC,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAoC;IAEpC,IAAI,KAAkC,CAAA;IACtC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,MAAS,CAAA;QACb,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,YAAY,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,eAAe;gBACnG,MAAM,IAAI,eAAe,CACvB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,OAAO,EACb,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;oBAC7F,SAAS,CACZ,CAAA;YACH,MAAM,KAAK,CAAA;QACb,CAAC;QACD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACxB,OAAO,CAAC,cAAc,EAAE,CAAA;QACxB,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,eAAe,CAAA;YAC1F,MAAM,IAAI,GAAG,KAAK,YAAY,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAA;YACnF,MAAM,QAAQ,GACZ,CAAC,OAAO,IAAI,IAAI,CAAC;gBACjB,CAAC,OAAO,CAAC,QAAQ;gBACjB,OAAO,CAAC,MAAM,KAAK,SAAS;gBAC5B,OAAO,GAAG,mBAAmB,CAAA;YAC/B,IAAI,CAAC,QAAQ;gBAAE,MAAM,KAAK,CAAA;YAC1B,MAAM,OAAO,GAAG,KAAwB,CAAA;YACxC,mFAAmF;YACnF,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;YACzE,IAAI,IAAI;gBAAE,KAAK,GAAG,OAAO,CAAA;YACzB,OAAO,CAAC,GAAG,CACT,MAAM,EACN,GAAG,OAAO,CAAC,KAAK,WAAW,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,sBAAsB,sBAAsB,GAAG,EAAE,CACvH,CAAA;YACD,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/decision/engine-version.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The fork's release semver, read from a pack's version tag, and the floor for `--decision`.
+ *
+ * TurboQuant releases are tagged `b<upstream build>-<fork semver>` (`b10269-1.7.0`). The decision role
+ * shipped in 1.7.0, so a tag at or above it is a strong hint. It is only a hint: a `dev` build carries
+ * whatever `TURBOQUANT_VERSION` the branch had (1.5.1 while 1.7.0 was being built) and a legacy
+ * `turboquant-<id>-<sha>` tag has no semver at all. The `-h` probe is the real gate; this ordering
+ * only decides which pack is probed first. A unified tag is read by the backend module's
+ * `unifiedReleaseRank`, the parser the release index and the install sort use, so the two never
+ * disagree about what a tag says; only the bare `1.7.0` / `v1.7.0` form is read here.
+ */
+/** The first fork release with `llama-server --decision` (API version 1). */
+export declare const DECISION_MIN_FORK_VERSION = "1.7.0";
+export type Semver = readonly [number, number, number];
+/**
+ * `b10269-1.7.0` → `[1, 7, 0]`; a bare `1.7.0` / `v1.7.0` too (the floor, a user-typed version).
+ * Anything else (`b6325`, `turboquant-…`, `1.7`) has no semver: `undefined`.
+ */
+export declare function parseForkSemver(version: string): Semver | undefined;
+/** Numeric, part by part: `1.10.0` > `1.9.9`. */
+export declare function compareSemver(a: Semver, b: Semver): -1 | 0 | 1;
+export declare function formatSemver(v: Semver): string;
+/**
+ * Whether the tag says the build is new enough: `true` / `false` when it has a semver, `undefined`
+ * when it does not (then only the probe can tell).
+ */
+export declare function meetsForkVersion(version: string, floor?: string): boolean | undefined;

package/dist/decision/engine-version.js

@@ -0,0 +1,54 @@
+/**
+ * The fork's release semver, read from a pack's version tag, and the floor for `--decision`.
+ *
+ * TurboQuant releases are tagged `b<upstream build>-<fork semver>` (`b10269-1.7.0`). The decision role
+ * shipped in 1.7.0, so a tag at or above it is a strong hint. It is only a hint: a `dev` build carries
+ * whatever `TURBOQUANT_VERSION` the branch had (1.5.1 while 1.7.0 was being built) and a legacy
+ * `turboquant-<id>-<sha>` tag has no semver at all. The `-h` probe is the real gate; this ordering
+ * only decides which pack is probed first. A unified tag is read by the backend module's
+ * `unifiedReleaseRank`, the parser the release index and the install sort use, so the two never
+ * disagree about what a tag says; only the bare `1.7.0` / `v1.7.0` form is read here.
+ */
+import { unifiedReleaseRank } from '../backend/index.js';
+/** The first fork release with `llama-server --decision` (API version 1). */
+export const DECISION_MIN_FORK_VERSION = '1.7.0';
+const PLAIN_SEMVER = /^v?(\d+)\.(\d+)\.(\d+)$/;
+/**
+ * `b10269-1.7.0` → `[1, 7, 0]`; a bare `1.7.0` / `v1.7.0` too (the floor, a user-typed version).
+ * Anything else (`b6325`, `turboquant-…`, `1.7`) has no semver: `undefined`.
+ */
+export function parseForkSemver(version) {
+    const trimmed = version.trim();
+    const rank = unifiedReleaseRank(trimmed);
+    if (rank)
+        return [rank[1], rank[2], rank[3]];
+    const match = PLAIN_SEMVER.exec(trimmed);
+    if (!match)
+        return undefined;
+    const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return parts.every((n) => Number.isSafeInteger(n)) ? parts : undefined;
+}
+/** Numeric, part by part: `1.10.0` > `1.9.9`. */
+export function compareSemver(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+export function formatSemver(v) {
+    return `${v[0]}.${v[1]}.${v[2]}`;
+}
+/**
+ * Whether the tag says the build is new enough: `true` / `false` when it has a semver, `undefined`
+ * when it does not (then only the probe can tell).
+ */
+export function meetsForkVersion(version, floor = DECISION_MIN_FORK_VERSION) {
+    const have = parseForkSemver(version);
+    const need = parseForkSemver(floor);
+    if (!have || !need)
+        return undefined;
+    return compareSemver(have, need) >= 0;
+}
+//# sourceMappingURL=engine-version.js.map

package/dist/decision/engine-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-version.js","sourceRoot":"","sources":["../../src/decision/engine-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAA;AAIhD,MAAM,YAAY,GAAG,yBAAyB,CAAA;AAE9C;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IAC9B,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IACxC,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAU,CAAA;IAC7E,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACxE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAI,CAAC,CAAC,CAAC,CAAY,CAAA;QAC7C,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,QAAgB,yBAAyB;IAEzC,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAA;IACrC,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IACnC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAA;IACpC,OAAO,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC"}