@atomic-chat/core 0.5.1 → 0.13.2

package/dist/embedding/engine.js

@@ -0,0 +1,100 @@
+/**
+ * Finding a stock llama.cpp `llama-server` new enough for the embedding model: the I/O half of the
+ * engine gate, the upstream half of the decision module's (`DecisionEngineResolver.resolveUpstream`).
+ *
+ * The installed packs of `llamacpp-upstream` are read from its folder directly: any of them may run
+ * the embedding model. The release tag is the gate (`orderUpstreamCandidates`): only packs at or above
+ * the model's floor, the build the user picked for chat first (it is known to run on this machine),
+ * then newest first, GPU before CPU. Readiness has the last word; a pack it refuses, or one that dies
+ * while loading, is handed back through `reject` and skipped until the file changes or the owner calls
+ * `forgetRejected` (a build was installed, the user asked for a load, the launch settings changed).
+ */
+import { stat } from 'node:fs/promises';
+import { AtomicCoreError } from '../contracts/index.js';
+import { resolveBackendExe, scanInstalledBackends } from '../backend/index.js';
+import { orderUpstreamCandidates } from '../decision/index.js';
+/** The provider whose builds run embedding models. */
+export const EMBEDDING_ENGINE_PROVIDER = 'llamacpp-upstream';
+const REFUSED_AT_READINESS = 'refused at readiness';
+const defaultMtime = (path) => stat(path).then((s) => (s.isFile() ? s.mtimeMs : undefined), () => undefined);
+export class EmbeddingEngineResolver {
+    deps;
+    /** `exe\0mtime` → why readiness refused it. A replaced file has a new mtime and is tried again. */
+    rejected = new Map();
+    platform;
+    constructor(deps) {
+        this.deps = deps;
+        this.platform = deps.platform ?? process.platform;
+    }
+    /**
+     * `enginePath` when given (it only has to exist and not be refused at readiness), otherwise the
+     * newest installed pack at or above `minBuild`. `EMBEDDING_ENGINE_UNSUPPORTED` names every pack it
+     * tried, and the build to update to.
+     */
+    async resolve(enginePath, minBuild) {
+        if (enginePath !== '') {
+            const reason = await this.check(enginePath);
+            if (reason === undefined)
+                return { path: enginePath, version_backend: null, provider: null };
+            throw new AtomicCoreError('EMBEDDING_ENGINE_UNSUPPORTED', 'The configured engine cannot run the embedding model.', `${enginePath}: ${reason}`);
+        }
+        const { eligible, tooOld } = orderUpstreamCandidates(await this.packs(), minBuild, this.deps.preferredUpstream?.() ?? '');
+        const tried = [];
+        for (const candidate of eligible) {
+            const reason = await this.check(candidate.path);
+            if (reason === undefined)
+                return {
+                    path: candidate.path,
+                    version_backend: candidate.info.version_backend,
+                    provider: EMBEDDING_ENGINE_PROVIDER,
+                };
+            tried.push(`${candidate.info.version_backend}: ${reason}`);
+        }
+        for (const pack of tooOld)
+            tried.push(`${pack.version}/${pack.backend}: older than b${minBuild}`);
+        const message = eligible.length > 0
+            ? `No installed llama.cpp build can run the embedding model: every build at b${minBuild} or newer was ${REFUSED_AT_READINESS}.`
+            : minBuild > 0
+                ? `No installed llama.cpp build can run the embedding model. Update llama.cpp to b${minBuild} or newer.`
+                : 'No llama.cpp build is installed. Install llama.cpp to run the embedding model.';
+        throw new AtomicCoreError('EMBEDDING_ENGINE_UNSUPPORTED', message, tried.length > 0
+            ? tried.join('\n')
+            : `no llama.cpp build in ${this.deps.layout.provider(EMBEDDING_ENGINE_PROVIDER).backendsDir}`);
+    }
+    /** `exe` started but readiness refused it: skip it in every later `resolve` until the file changes. */
+    async reject(exe, why) {
+        const mtime = await (this.deps.mtime ?? defaultMtime)(exe);
+        if (mtime === undefined)
+            return;
+        this.rejected.set(`${exe}\u0000${mtime}`, why);
+        this.deps.log?.('debug', `embedding engine ${exe} rejected at readiness: ${why}`);
+    }
+    /** Every build refused at readiness is tried again by the next `resolve`. */
+    forgetRejected() {
+        if (this.rejected.size === 0)
+            return;
+        this.rejected.clear();
+        this.deps.log?.('debug', 'embedding engines refused at readiness will be tried again');
+    }
+    /** `undefined` when `exe` may be tried, otherwise why not. */
+    async check(exe) {
+        const mtime = await (this.deps.mtime ?? defaultMtime)(exe);
+        if (mtime === undefined)
+            return 'no such file';
+        const refused = this.rejected.get(`${exe}\u0000${mtime}`);
+        return refused === undefined ? undefined : `${REFUSED_AT_READINESS}: ${refused}`;
+    }
+    async packs() {
+        if (this.deps.listPacks)
+            return this.deps.listPacks();
+        const { layout } = this.deps;
+        const packs = [];
+        for (const pack of await scanInstalledBackends(layout, EMBEDDING_ENGINE_PROVIDER, this.platform)) {
+            const path = await resolveBackendExe(layout, EMBEDDING_ENGINE_PROVIDER, pack.version, pack.backend, this.platform);
+            if (path)
+                packs.push({ version: pack.version, backend: pack.backend, path });
+        }
+        return packs;
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/embedding/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/embedding/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAG9D,sDAAsD;AACtD,MAAM,CAAC,MAAM,yBAAyB,GAA4B,mBAAmB,CAAA;AAErF,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AAiBnD,MAAM,YAAY,GAAG,CAAC,IAAY,EAA+B,EAAE,CACjE,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACb,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAC3C,GAAG,EAAE,CAAC,SAAS,CAChB,CAAA;AAEH,MAAM,OAAO,uBAAuB;IAKL;IAJ7B,mGAAmG;IAClF,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;IACpC,QAAQ,CAAiB;IAE1C,YAA6B,IAAiC;QAAjC,SAAI,GAAJ,IAAI,CAA6B;QAC5D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAA;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,UAAkB,EAAE,QAAgB;QAChD,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YAC3C,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;YAC5F,MAAM,IAAI,eAAe,CACvB,8BAA8B,EAC9B,uDAAuD,EACvD,GAAG,UAAU,KAAK,MAAM,EAAE,CAC3B,CAAA;QACH,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,uBAAuB,CAClD,MAAM,IAAI,CAAC,KAAK,EAAE,EAClB,QAAQ,EACR,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CACtC,CAAA;QACD,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YAC/C,IAAI,MAAM,KAAK,SAAS;gBACtB,OAAO;oBACL,IAAI,EAAE,SAAS,CAAC,IAAI;oBACpB,eAAe,EAAE,SAAS,CAAC,IAAI,CAAC,eAAe;oBAC/C,QAAQ,EAAE,yBAAyB;iBACpC,CAAA;YACH,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,MAAM,EAAE,CAAC,CAAA;QAC5D,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,iBAAiB,QAAQ,EAAE,CAAC,CAAA;QACjG,MAAM,OAAO,GACX,QAAQ,CAAC,MAAM,GAAG,CAAC;YACjB,CAAC,CAAC,6EAA6E,QAAQ,iBAAiB,oBAAoB,GAAG;YAC/H,CAAC,CAAC,QAAQ,GAAG,CAAC;gBACZ,CAAC,CAAC,kFAAkF,QAAQ,YAAY;gBACxG,CAAC,CAAC,gFAAgF,CAAA;QACxF,MAAM,IAAI,eAAe,CACvB,8BAA8B,EAC9B,OAAO,EACP,KAAK,CAAC,MAAM,GAAG,CAAC;YACd,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAClB,CAAC,CAAC,yBAAyB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC,WAAW,EAAE,CAChG,CAAA;IACH,CAAC;IAED,uGAAuG;IACvG,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,GAAW;QACnC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC,GAAG,CAAC,CAAA;QAC1D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,KAAK,EAAE,EAAE,GAAG,CAAC,CAAA;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,oBAAoB,GAAG,2BAA2B,GAAG,EAAE,CAAC,CAAA;IACnF,CAAC;IAED,6EAA6E;IAC7E,cAAc;QACZ,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,OAAM;QACpC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,4DAA4D,CAAC,CAAA;IACxF,CAAC;IAED,8DAA8D;IACtD,KAAK,CAAC,KAAK,CAAC,GAAW;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC,GAAG,CAAC,CAAA;QAC1D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,cAAc,CAAA;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,KAAK,EAAE,CAAC,CAAA;QACzD,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,oBAAoB,KAAK,OAAO,EAAE,CAAA;IAClF,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAA;QACrD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAA;QAC5B,MAAM,KAAK,GAA0B,EAAE,CAAA;QACvC,KAAK,MAAM,IAAI,IAAI,MAAM,qBAAqB,CAAC,MAAM,EAAE,yBAAyB,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjG,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAClC,MAAM,EACN,yBAAyB,EACzB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,QAAQ,CACd,CAAA;YACD,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QAC9E,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;CACF"}

package/dist/embedding/ffmpeg.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Video input needs `ffmpeg`: llama.cpp's mtmd helper decodes a clip by starting `ffmpeg` from PATH
+ * (`mtmd_helper_video_init`). Nothing bundles it, so the embedding process gets it only when the
+ * user has one. An app started from the Finder inherits a bare PATH (`/usr/bin:/bin:/usr/sbin:/sbin`)
+ * that misses Homebrew's, so the usual install folders are searched as well and the one holding
+ * `ffmpeg` is put on the process's PATH. Without it the module does not offer video at all
+ * (`EmbeddingStatus.modalities`), and a clip is refused with a 400 that says why.
+ */
+/** Where installers put `ffmpeg` outside a login shell's PATH, per platform. */
+export declare const FFMPEG_EXTRA_DIRS: Readonly<Partial<Record<NodeJS.Platform, readonly string[]>>>;
+/** The PATH variable of `env`, whatever its case (Windows spells it `Path`). */
+export declare function pathOf(env: NodeJS.ProcessEnv): string;
+/** The folders to look for `ffmpeg` in: PATH first, then the platform's usual ones, once each. Pure. */
+export declare function ffmpegSearchDirs(platform: NodeJS.Platform, pathValue: string): string[];
+/** `env` with `dir` in front of its PATH (in the key the environment already uses). Pure. */
+export declare function withPathDir(env: NodeJS.ProcessEnv, dir: string, platform: NodeJS.Platform): NodeJS.ProcessEnv;
+/** The folder holding `ffmpeg`, or `undefined` when there is none to be found. */
+export declare function findFfmpegDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, isFile?: (path: string) => Promise<boolean>): Promise<string | undefined>;

package/dist/embedding/ffmpeg.js

@@ -0,0 +1,63 @@
+/**
+ * Video input needs `ffmpeg`: llama.cpp's mtmd helper decodes a clip by starting `ffmpeg` from PATH
+ * (`mtmd_helper_video_init`). Nothing bundles it, so the embedding process gets it only when the
+ * user has one. An app started from the Finder inherits a bare PATH (`/usr/bin:/bin:/usr/sbin:/sbin`)
+ * that misses Homebrew's, so the usual install folders are searched as well and the one holding
+ * `ffmpeg` is put on the process's PATH. Without it the module does not offer video at all
+ * (`EmbeddingStatus.modalities`), and a clip is refused with a 400 that says why.
+ */
+import { stat } from 'node:fs/promises';
+import { posix, win32 } from 'node:path';
+/** Where installers put `ffmpeg` outside a login shell's PATH, per platform. */
+export const FFMPEG_EXTRA_DIRS = {
+    darwin: ['/opt/homebrew/bin', '/usr/local/bin', '/opt/local/bin'],
+    linux: ['/usr/local/bin', '/usr/bin', '/snap/bin'],
+};
+/**
+ * The key of `env`'s PATH: `PATH` itself when there is one (as `buildProcessEnv` reads it on
+ * Windows too), else the first spelling of it (Windows keeps `Path`).
+ */
+function pathKey(env) {
+    if (env['PATH'] !== undefined)
+        return 'PATH';
+    return Object.keys(env).find((k) => k.toUpperCase() === 'PATH');
+}
+/** The PATH variable of `env`, whatever its case (Windows spells it `Path`). */
+export function pathOf(env) {
+    const key = pathKey(env);
+    return (key !== undefined ? env[key] : undefined) ?? '';
+}
+/** The folders to look for `ffmpeg` in: PATH first, then the platform's usual ones, once each. Pure. */
+export function ffmpegSearchDirs(platform, pathValue) {
+    const separator = platform === 'win32' ? ';' : ':';
+    const dirs = [...pathValue.split(separator), ...(FFMPEG_EXTRA_DIRS[platform] ?? [])];
+    const seen = new Set();
+    return dirs.filter((dir) => {
+        const key = platform === 'win32' ? dir.toLowerCase() : dir;
+        if (dir.trim() === '' || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** `env` with `dir` in front of its PATH (in the key the environment already uses). Pure. */
+export function withPathDir(env, dir, platform) {
+    const separator = platform === 'win32' ? ';' : ':';
+    const key = pathKey(env) ?? 'PATH';
+    const current = env[key] ?? '';
+    if (current.split(separator).includes(dir))
+        return env;
+    return { ...env, [key]: current === '' ? dir : `${dir}${separator}${current}` };
+}
+const defaultIsFile = (path) => stat(path).then((s) => s.isFile(), () => false);
+/** The folder holding `ffmpeg`, or `undefined` when there is none to be found. */
+export async function findFfmpegDir(platform, env, isFile = defaultIsFile) {
+    const exe = platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+    // The platform's own separator, not the host's: a Linux path checked on a Windows host stays `/`.
+    const joinIn = platform === 'win32' ? win32.join : posix.join;
+    for (const dir of ffmpegSearchDirs(platform, pathOf(env)))
+        if (await isFile(joinIn(dir, exe)))
+            return dir;
+    return undefined;
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/embedding/ffmpeg.js.map

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

package/dist/embedding/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The embedding model: one stock llama.cpp `llama-server --embedding` that the public server's
+ * `/v1/embeddings` forwards to when a client names it, with a projector for one that reads images or
+ * audio. A module of its own, outside the sessions registry, like the decision model
+ * (ADR 2026-10-07-embedding-models-are-their-own-core-module). Wire types in
+ * `src/contracts/embedding.ts`; the catalog the app downloads from is `atomic-chat-conf/models/embedding.json`.
+ */
+export * from './args.js';
+export * from './engine.js';
+export * from './ffmpeg.js';
+export * from './model-facts.js';
+export * from './process.js';
+export * from './readiness.js';
+export * from './request.js';
+export * from './service.js';
+export * from './wiring.js';

package/dist/embedding/index.js

@@ -0,0 +1,17 @@
+/**
+ * The embedding model: one stock llama.cpp `llama-server --embedding` that the public server's
+ * `/v1/embeddings` forwards to when a client names it, with a projector for one that reads images or
+ * audio. A module of its own, outside the sessions registry, like the decision model
+ * (ADR 2026-10-07-embedding-models-are-their-own-core-module). Wire types in
+ * `src/contracts/embedding.ts`; the catalog the app downloads from is `atomic-chat-conf/models/embedding.json`.
+ */
+export * from './args.js';
+export * from './engine.js';
+export * from './ffmpeg.js';
+export * from './model-facts.js';
+export * from './process.js';
+export * from './readiness.js';
+export * from './request.js';
+export * from './service.js';
+export * from './wiring.js';
+//# sourceMappingURL=index.js.map

package/dist/embedding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embedding/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/dist/embedding/model-facts.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What an embedding GGUF says about how to run it, read from its header before a start: whether it is
+ * an embedding model at all, its pooling, its trained context, and the oldest upstream build that
+ * runs it. Pure but for `readEmbeddingModelFacts`.
+ *
+ * The build floors (ggml-org/llama.cpp, by the merge of each change):
+ *  - b11240: typed `content` parts (`image_url`, `input_audio`) in `/v1/embeddings` (#29556), which a
+ *    model with a projector needs to be given anything but text;
+ *  - b11454: the `gemma-embedding2` architecture, EmbeddingGemma 2 (#30054). b11452 and b11453 were
+ *    never released.
+ */
+import type { EmbeddingPooling } from '../contracts/index.js';
+/** `-c` when the settings leave it to the core: a long passage, an image or half a minute of audio. */
+export declare const EMBEDDING_DEFAULT_CTX = 2048;
+/** The first upstream build with typed `content` parts in `/v1/embeddings`. */
+export declare const EMBEDDING_CONTENT_PARTS_MIN_BUILD = 11240;
+/** The first upstream build that runs EmbeddingGemma 2. */
+export declare const EMBEDDING_GEMMA2_MIN_BUILD = 11454;
+export interface EmbeddingModelFacts {
+    /** `general.architecture`, lower case; `''` when the header has none. */
+    arch: string;
+    /** The header says embeddings (`isEmbeddingGguf`), not text, a decision or nothing. */
+    embedding: boolean;
+    /** A decision model: it runs in the decision module, never here. */
+    decision: boolean;
+    /** `<arch>.pooling_type`; `undefined` when the header has none. `rank` is a reranker. */
+    pooling?: 'none' | EmbeddingPooling | 'rank';
+    /** `<arch>.context_length`, when the file has one. */
+    contextTrain?: number;
+}
+/** The facts from parsed metadata (string values, as the GGUF reader returns them). Pure. */
+export declare function embeddingFactsOf(metadata: Record<string, unknown> | undefined): EmbeddingModelFacts;
+/** The facts of a GGUF file; `undefined` when its header cannot be read. */
+export declare function readEmbeddingModelFacts(path: string, read?: (path: string) => Promise<{
+    metadata: Record<string, unknown>;
+}>): Promise<EmbeddingModelFacts | undefined>;
+/**
+ * Why the file cannot run as an embedding model, or `undefined` when it can. A reranker (pooling
+ * `rank`) answers scores, not vectors, and `/v1/embeddings` refuses it.
+ */
+export declare function notAnEmbeddingModel(facts: EmbeddingModelFacts): string | undefined;
+/** The oldest upstream build that serves the model; 0 when any build does. */
+export declare function embeddingMinBuild(arch: string, projector: boolean): number;
+/** `-c`: the setting when given, else the default, never past the trained context. */
+export declare function embeddingCtxSize(setting: number, contextTrain: number | undefined): number;
+/**
+ * `--pooling`: the setting when given; else nothing, so the server reads the GGUF's own, unless the
+ * file names none at all (an old conversion), where `/v1/embeddings` would refuse every request:
+ * then `mean`, which is what such sentence-transformer models were trained with.
+ */
+export declare function embeddingPooling(setting: '' | EmbeddingPooling, facts: Pick<EmbeddingModelFacts, 'pooling'>): EmbeddingPooling | undefined;

package/dist/embedding/model-facts.js

@@ -0,0 +1,84 @@
+/**
+ * What an embedding GGUF says about how to run it, read from its header before a start: whether it is
+ * an embedding model at all, its pooling, its trained context, and the oldest upstream build that
+ * runs it. Pure but for `readEmbeddingModelFacts`.
+ *
+ * The build floors (ggml-org/llama.cpp, by the merge of each change):
+ *  - b11240: typed `content` parts (`image_url`, `input_audio`) in `/v1/embeddings` (#29556), which a
+ *    model with a projector needs to be given anything but text;
+ *  - b11454: the `gemma-embedding2` architecture, EmbeddingGemma 2 (#30054). b11452 and b11453 were
+ *    never released.
+ */
+import { isDecisionGguf, isEmbeddingGguf, readGgufMetadataFromFile } from '../models/index.js';
+/** `-c` when the settings leave it to the core: a long passage, an image or half a minute of audio. */
+export const EMBEDDING_DEFAULT_CTX = 2048;
+/** The first upstream build with typed `content` parts in `/v1/embeddings`. */
+export const EMBEDDING_CONTENT_PARTS_MIN_BUILD = 11240;
+/** The first upstream build that runs EmbeddingGemma 2. */
+export const EMBEDDING_GEMMA2_MIN_BUILD = 11454;
+/** Architectures newer than the oldest upstream build the core may find, by the build that added them. */
+const ARCH_MIN_BUILD = {
+    'gemma-embedding2': EMBEDDING_GEMMA2_MIN_BUILD,
+};
+/** `<arch>.pooling_type` as llama.cpp numbers it. */
+const POOLING_NAMES = {
+    '0': 'none',
+    '1': 'mean',
+    '2': 'cls',
+    '3': 'last',
+    '4': 'rank',
+};
+/** The facts from parsed metadata (string values, as the GGUF reader returns them). Pure. */
+export function embeddingFactsOf(metadata) {
+    const meta = (metadata ?? {});
+    const arch = String(meta['general.architecture'] ?? '')
+        .trim()
+        .toLowerCase();
+    const pooling = POOLING_NAMES[String(meta[`${arch}.pooling_type`] ?? '').trim()];
+    const context = Number(meta[`${arch}.context_length`]);
+    return {
+        arch,
+        embedding: isEmbeddingGguf(meta),
+        decision: isDecisionGguf(meta),
+        ...(pooling !== undefined ? { pooling } : {}),
+        ...(Number.isInteger(context) && context > 0 ? { contextTrain: context } : {}),
+    };
+}
+/** The facts of a GGUF file; `undefined` when its header cannot be read. */
+export async function readEmbeddingModelFacts(path, read = readGgufMetadataFromFile) {
+    const parsed = await read(path).catch(() => undefined);
+    return parsed ? embeddingFactsOf(parsed.metadata) : undefined;
+}
+/**
+ * Why the file cannot run as an embedding model, or `undefined` when it can. A reranker (pooling
+ * `rank`) answers scores, not vectors, and `/v1/embeddings` refuses it.
+ */
+export function notAnEmbeddingModel(facts) {
+    if (facts.decision)
+        return 'It is a decision model; turn it on as a decision model instead.';
+    if (facts.pooling === 'rank')
+        return 'It is a reranker, which answers scores rather than vectors.';
+    if (!facts.embedding)
+        return 'It is a text generation model, not an embedding model.';
+    return undefined;
+}
+/** The oldest upstream build that serves the model; 0 when any build does. */
+export function embeddingMinBuild(arch, projector) {
+    return Math.max(ARCH_MIN_BUILD[arch] ?? 0, projector ? EMBEDDING_CONTENT_PARTS_MIN_BUILD : 0);
+}
+/** `-c`: the setting when given, else the default, never past the trained context. */
+export function embeddingCtxSize(setting, contextTrain) {
+    const wanted = Number.isInteger(setting) && setting > 0 ? setting : EMBEDDING_DEFAULT_CTX;
+    return contextTrain !== undefined && contextTrain > 0 ? Math.min(wanted, contextTrain) : wanted;
+}
+/**
+ * `--pooling`: the setting when given; else nothing, so the server reads the GGUF's own, unless the
+ * file names none at all (an old conversion), where `/v1/embeddings` would refuse every request:
+ * then `mean`, which is what such sentence-transformer models were trained with.
+ */
+export function embeddingPooling(setting, facts) {
+    if (setting !== '')
+        return setting;
+    return facts.pooling === undefined || facts.pooling === 'none' ? 'mean' : undefined;
+}
+//# sourceMappingURL=model-facts.js.map

package/dist/embedding/model-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-facts.js","sourceRoot":"","sources":["../../src/embedding/model-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAG9F,uGAAuG;AACvG,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAA;AACzC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,iCAAiC,GAAG,KAAK,CAAA;AACtD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAA;AAE/C,0GAA0G;AAC1G,MAAM,cAAc,GAAqC;IACvD,kBAAkB,EAAE,0BAA0B;CAC/C,CAAA;AAED,qDAAqD;AACrD,MAAM,aAAa,GAAiE;IAClF,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;CACZ,CAAA;AAeD,6FAA6F;AAC7F,MAAM,UAAU,gBAAgB,CAAC,QAA6C;IAC5E,MAAM,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE,CAA2B,CAAA;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC;SACpD,IAAI,EAAE;SACN,WAAW,EAAE,CAAA;IAChB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAChF,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAA;IACtD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,eAAe,CAAC,IAAI,CAAC;QAChC,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC;QAC9B,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAA;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAY,EACZ,OAAyE,wBAAwB;IAEjG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACtD,OAAO,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA0B;IAC5D,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,iEAAiE,CAAA;IAC5F,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM;QAAE,OAAO,6DAA6D,CAAA;IAClG,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,wDAAwD,CAAA;IACrF,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,SAAkB;IAChE,OAAO,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC/F,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,YAAgC;IAChF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAA;IACzF,OAAO,YAAY,KAAK,SAAS,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;AACjG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA8B,EAC9B,KAA2C;IAE3C,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,OAAO,CAAA;IAClC,OAAO,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AACrF,CAAC"}

package/dist/embedding/process.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Spawning one embedding `llama-server` and waiting until it answers vectors.
+ *
+ * The same process mechanics the decision module borrows from the runtimes: `spawnManaged`,
+ * `randomFreePort`, `buildProcessEnv`, the backend-output sink, and the journal hooks (the caller
+ * writes the record right after the spawn under `provider: 'embedding'`, so a crashed owner's
+ * successor reaps it). Readiness is `readiness.ts`, polled until the startup deadline; an exit before
+ * it is reported with the last lines the process printed. On any failure the child is dead when this
+ * rejects.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+import type { EmbeddingEngineInfo, EmbeddingModality } from '../contracts/index.js';
+import type { DecisionHttp } from '../decision/index.js';
+import type { ExitInfo } from '../runtime/llamacpp/index.js';
+import type { BackendOutputSink, ManagedProcess, SpawnSpec } from '../runtime/shared/index.js';
+import type { EmbeddingLaunchSpec } from './args.js';
+/** SIGTERM → this long → SIGKILL. */
+export declare const EMBEDDING_TERMINATE_GRACE_MS = 5000;
+export declare const READY_POLL_INTERVAL_MS = 200;
+/** Lines of output kept for a post-mortem. */
+export declare const EMBEDDING_TAIL_CAPACITY = 100;
+export interface EmbeddingServerSpec extends Omit<EmbeddingLaunchSpec, 'port'> {
+    engine: EmbeddingEngineInfo;
+    startupTimeoutMs: number;
+}
+/** A running embedding process that answered a vector. */
+export interface EmbeddingProcessHandle {
+    pid: number;
+    port: number;
+    apiKey: string;
+    exe: string;
+    baseUrl: string;
+    /** The `-a` the process answers with. */
+    modelId: string;
+    dims: number;
+    modalities: EmbeddingModality[];
+    tail(): string[];
+    exitStatus(): ExitInfo | undefined;
+    exited: Promise<ExitInfo>;
+    terminate(graceMs?: number): Promise<ExitInfo>;
+}
+export interface SpawnEmbeddingDeps {
+    http: DecisionHttp;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    log?: (level: 'info' | 'warn' | 'debug', msg: string) => void;
+    backendOutput?: BackendOutputSink;
+    /** Right after the child started, before readiness: the journal entry goes here. */
+    onSpawned?: (pid: number, port: number, exe: string) => Promise<void>;
+    /** A child `onSpawned` saw is dead and will never be used. */
+    onGone?: (pid: number) => Promise<void>;
+    /** An unload or a shutdown while the process is still starting; the child is killed. */
+    signal?: AbortSignal;
+    freePort?: () => Promise<number>;
+    apiKey?: () => string;
+    /** Test seam: start the child (the fake engine in tests). */
+    spawn?: (spec: SpawnSpec, onData: (stream: 'stdout' | 'stderr', line: string) => void) => ManagedProcess;
+    /** The folder holding `ffmpeg` (`findFfmpegDir`); without one the process is offered no video. */
+    findFfmpeg?: (platform: NodeJS.Platform, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** The error for a process that died before it was ready: the engine's own last lines in the details. */
+export declare function embeddingEarlyExitError(exit: ExitInfo, tail: readonly string[]): AtomicCoreError;
+export declare function spawnEmbeddingServer(spec: EmbeddingServerSpec, deps: SpawnEmbeddingDeps): Promise<EmbeddingProcessHandle>;

package/dist/embedding/process.js

@@ -0,0 +1,131 @@
+/**
+ * Spawning one embedding `llama-server` and waiting until it answers vectors.
+ *
+ * The same process mechanics the decision module borrows from the runtimes: `spawnManaged`,
+ * `randomFreePort`, `buildProcessEnv`, the backend-output sink, and the journal hooks (the caller
+ * writes the record right after the spawn under `provider: 'embedding'`, so a crashed owner's
+ * successor reaps it). Readiness is `readiness.ts`, polled until the startup deadline; an exit before
+ * it is reported with the last lines the process printed. On any failure the child is dead when this
+ * rejects.
+ */
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { commandSummary } from '../decision/index.js';
+import { backendOutputReporter, buildProcessEnv, discoverCudaPaths, nodeCudaProbeEnv, randomFreePort, spawnManaged, } from '../runtime/shared/index.js';
+import { buildEmbeddingArgs, embeddingEnv, EMBEDDING_HOST } from './args.js';
+import { findFfmpegDir, withPathDir } from './ffmpeg.js';
+import { checkEmbeddingReadiness, READINESS_REQUEST_TIMEOUT_MS } from './readiness.js';
+/** SIGTERM → this long → SIGKILL. */
+export const EMBEDDING_TERMINATE_GRACE_MS = 5_000;
+export const READY_POLL_INTERVAL_MS = 200;
+/** Lines of output kept for a post-mortem. */
+export const EMBEDDING_TAIL_CAPACITY = 100;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function describeExit(exit) {
+    if (exit.code !== null)
+        return `code ${exit.code}`;
+    if (exit.signal !== null)
+        return `signal ${exit.signal}`;
+    return 'an unknown status';
+}
+/** The error for a process that died before it was ready: the engine's own last lines in the details. */
+export function embeddingEarlyExitError(exit, tail) {
+    return new AtomicCoreError('MODEL_LOAD_FAILED', `The embedding model exited with ${describeExit(exit)} while loading.`, tail.slice(-20).join('\n') || undefined);
+}
+export async function spawnEmbeddingServer(spec, deps) {
+    const platform = deps.platform ?? process.platform;
+    const inherited = deps.env ?? process.env;
+    // Video decodes through `ffmpeg` on the process's PATH (see `ffmpeg.ts`).
+    const ffmpegDir = await (deps.findFfmpeg ?? findFfmpegDir)(platform, inherited).catch(() => undefined);
+    const baseEnv = ffmpegDir !== undefined ? withPathDir(inherited, ffmpegDir, platform) : inherited;
+    const log = deps.log ?? (() => { });
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? Date.now;
+    const exe = spec.engine.path;
+    const port = await (deps.freePort ?? (() => randomFreePort([])))().catch((error) => {
+        throw new AtomicCoreError('MODEL_LOAD_FAILED', 'No free port for the embedding model.', error instanceof Error ? error.message : String(error));
+    });
+    const apiKey = (deps.apiKey ?? (() => randomBytes(24).toString('base64url')))();
+    const args = buildEmbeddingArgs({ ...spec, port });
+    log('info', `starting the embedding model: ${commandSummary(exe, args)}`);
+    const { env, cwd } = buildProcessEnv({
+        platform,
+        baseEnv,
+        exeDir: dirname(exe),
+        cuda: discoverCudaPaths(nodeCudaProbeEnv(platform, baseEnv)),
+        userEnv: embeddingEnv(apiKey),
+    });
+    const tail = [];
+    const reportOutput = backendOutputReporter(deps.backendOutput, deps.log);
+    const onLine = (stream, line) => {
+        reportOutput({ provider: 'embedding', model: spec.modelId, stream, line });
+        if (tail.length >= EMBEDDING_TAIL_CAPACITY)
+            tail.shift();
+        tail.push(line);
+    };
+    const proc = (deps.spawn ?? ((s, cb) => spawnManaged(s, cb, { captureOutput: false })))({ exe, args, env, cwd }, onLine);
+    let exit;
+    void proc.exited.then((e) => (exit = e));
+    const baseUrl = `http://${EMBEDDING_HOST}:${port}`;
+    const terminate = (graceMs = EMBEDDING_TERMINATE_GRACE_MS) => proc.terminate(graceMs);
+    try {
+        await deps.onSpawned?.(proc.pid, port, exe);
+    }
+    catch (error) {
+        await terminate(0);
+        throw error;
+    }
+    const fail = async (graceMs, error) => {
+        await terminate(graceMs);
+        await deps.onGone?.(proc.pid);
+        throw error;
+    };
+    const deadline = now() + spec.startupTimeoutMs;
+    let lastDetail = '';
+    for (;;) {
+        if (deps.signal?.aborted)
+            return fail(0, new AtomicCoreError('EMBEDDING_UNAVAILABLE', 'The embedding model start was stopped.'));
+        const spawnFailure = proc.spawnFailure();
+        if (spawnFailure) {
+            await deps.onGone?.(proc.pid);
+            throw new AtomicCoreError('MODEL_LOAD_FAILED', 'The embedding engine could not be started.', `${exe}: ${spawnFailure.message}`);
+        }
+        if (exit !== undefined) {
+            // Give the pipes a moment to deliver the final lines.
+            await sleep(50);
+            await deps.onGone?.(proc.pid);
+            log('warn', `the embedding model exited while loading (${describeExit(exit)})`);
+            throw embeddingEarlyExitError(exit, tail);
+        }
+        if (now() >= deadline)
+            return fail(EMBEDDING_TERMINATE_GRACE_MS, new AtomicCoreError('MODEL_LOAD_TIMED_OUT', `The embedding model did not become ready within ${Math.round(spec.startupTimeoutMs / 1000)} seconds.`, [lastDetail, ...tail.slice(-10)].filter(Boolean).join('\n') || undefined));
+        const result = await checkEmbeddingReadiness(deps.http, baseUrl, apiKey, spec.modelId, READINESS_REQUEST_TIMEOUT_MS);
+        if (result.kind === 'ready') {
+            // The projector may read clips, but without `ffmpeg` the engine cannot decode one.
+            const modalities = ffmpegDir === undefined ? result.modalities.filter((m) => m !== 'video') : result.modalities;
+            log('info', `the embedding model ${spec.modelId} is ready on port ${port} (${result.dims} dimensions, ${modalities.join(', ')})`);
+            return {
+                pid: proc.pid,
+                port,
+                apiKey,
+                exe,
+                baseUrl,
+                modelId: spec.modelId,
+                dims: result.dims,
+                modalities,
+                tail: () => [...tail],
+                exitStatus: () => exit,
+                exited: proc.exited,
+                terminate,
+            };
+        }
+        if (result.kind === 'unsupported')
+            return fail(EMBEDDING_TERMINATE_GRACE_MS, new AtomicCoreError('EMBEDDING_ENGINE_UNSUPPORTED', 'The engine started but does not serve embeddings.', `${exe}: ${result.detail}`));
+        if (result.kind === 'refused')
+            return fail(EMBEDDING_TERMINATE_GRACE_MS, new AtomicCoreError('MODEL_LOAD_FAILED', 'The embedding model started but refuses to produce vectors.', `${exe}: ${result.detail}`));
+        lastDetail = result.detail;
+        await sleep(deps.pollIntervalMs ?? READY_POLL_INTERVAL_MS);
+    }
+}
+//# sourceMappingURL=process.js.map

package/dist/embedding/process.js.map

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