@gjsify/embeddings 0.0.0-stage → 0.64.26

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @gjsify/embeddings
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Text embeddings in the WebML CG lifecycle shape: an `Embedder` with `availability()`, `create({ monitor, signal })` and `destroy()`, vectors checked before they reach the caller, and a local llama.cpp engine that runs GGUF models on Node and on GJS. The engine is a parameter, so an app can plug in a remote provider without gjsify shipping it.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project. **Tier 3 (experimental, ADR 0003)**: the `Embedder` and the engine's availability logic are unit-tested on Node and GJS; the llama.cpp engine has been run by hand against a real model, on CPU and on Vulkan. Design: ADR 0132.
+
+## Installation
+
+```bash
+gjsify install @gjsify/embeddings
+```
+
+The root export needs nothing else. The llama.cpp engine needs its optional peers:
+
+```bash
+gjsify install node-llama-cpp @node-llama-cpp/linux-x64 @node-llama-cpp/linux-x64-vulkan
+gjsify install @gjsify/napi   # GJS only
+```
+
+## Usage
+
+```typescript
+import { Embedder } from '@gjsify/embeddings';
+import { llamaEmbeddings } from '@gjsify/embeddings/llama';
+
+const engine = llamaEmbeddings({ dimensions: 256 });
+
+if ((await Embedder.availability({ engine })) !== 'unavailable') {
+    const embedder = await Embedder.create({
+        engine,
+        monitor: (m) => m.addEventListener('downloadprogress', (e) => console.log(e.loaded)),
+    });
+    const query = await embedder.embedQuery('how do I renew a passport');
+    const docs = await embedder.embedDocuments([{ title: 'Passports', text: 'Renewal takes six weeks.' }]);
+    await embedder.destroy();
+}
+```
+
+`create()` downloads the model when it is missing (through `@gjsify/model-store`, digest-checked) and loads it. `availability()` reads no model bytes: it checks for the prebuilt binaries, the model file, and whether the machine has the memory for it (`@gjsify/machine-fit`).
+
+## Exports
+
+- **`.`** — `Embedder` and the types around it.
+- **`./engine`** — the `EmbeddingEngine` / `EmbeddingEngineFactory` interfaces, plus `checkVector`, `normalize`, `truncateVector` and `embedAcross` for writing an engine of your own, local or remote.
+- **`./llama`** — `llamaEmbeddings(options)`, the model manifest `EMBEDDING_MODELS` and `collectGarbage`.
+
+What `Embedder` guarantees for every engine:
+
+- Every vector is a finite `Float32Array` of `dimensions` length, one per input.
+- One call runs at a time; later calls queue behind it.
+- An aborted `signal` rejects at once. A signal that is already aborted never reaches the engine.
+- `destroy()` waits for the calls it has already accepted, then frees the model. Later calls reject.
+
+## The llama.cpp engine
+
+| Option | Default | |
+|---|---|---|
+| `model` | `embeddinggemma-2-q8_0` | an id from `EMBEDDING_MODELS` |
+| `modelPath` | — | a file you already have, checked against the manifest |
+| `dimensions` | the model's native size | one of the model's `truncations` (EmbeddingGemma: 768 or 256) |
+| `gpu` | `auto` | a `GpuSetting`, e.g. `parseGpuSetting(env.MYAPP_GPU)` from `@gjsify/machine-fit` |
+| `gpuGuardDir` | shared by all gjsify GPU engines | where the GPU guard keeps its pin |
+| `collectGarbage` | `true` | run the GC after each `embedDocuments` on GJS |
+
+Input longer than the model's context is cut, not rejected.
+
+**The GPU guard.** A Vulkan driver can hang a process instead of failing. Before going to the GPU, the engine leaves a pin in `gpuGuardDir` and removes it when the work finishes. A pin left over from a crash keeps the next run on the CPU and reports it through `onGpuPinned`. `gpu: 'on'` removes the pin.
+
+**`collectGarbage` on GJS.** SpiderMonkey decides when to collect from the size of the JS heap, but an embedding run's garbage is mostly native memory behind small wrapper objects. One measured run of 1500 documents grew from 0.85 GB to 1.8 GB; with one collection per batch it stayed at 0.85 GB. A collection inside a database transaction has broken commits before, so if you embed inside one, set `collectGarbage: false` and call `collectGarbage()` after the commit.
+
+### Bundling for GJS
+
+`./llama` imports `node-llama-cpp` statically. Evaluating the module loads no addon and no model. The import is static because a bundled dynamic `import('node-llama-cpp')` never settles on GJS: its modules with top-level await become lazy async initialisers, and the import hangs without an error.
+
+The app bundle needs one alias, `ipull` → `ipull/node`:
+
+```json
+{ "gjsify": { "aliases": { "ipull": "ipull/node" } } }
+```
+
+gjsify resolves with the `browser` condition, and ipull's browser build lacks the `downloadFile` that node-llama-cpp's model downloader imports. This engine never downloads through ipull, but the barrel still has to link.
+
+On GJS the native addon is loaded through `@gjsify/napi`. Start the app with `gjsify run` so the napi typelib is found.
+
+On macOS and Windows the llama.cpp engine runs on Node only, because the GJS route loads node-llama-cpp's Linux prebuilt binaries.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/embedder.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{checkVector as e}from"./vectors.js";function untilAborted(e){if(e===void 0)return{promise:new Promise(()=>{}),dispose(){}};let onAbort=()=>{};return{promise:new Promise((t,n)=>{onAbort=()=>n(e.reason),e.addEventListener(`abort`,onAbort,{once:!0})}),dispose:()=>e.removeEventListener(`abort`,onAbort)}}var t=class Embedder{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}static availability(e){return e.engine.availability()}static async create(e){e.signal?.throwIfAborted();let t=await e.engine.create({monitor:e.monitor,signal:e.signal});if(e.signal?.aborted&&(await t.destroy().catch(()=>void 0),e.signal.throwIfAborted()),!Number.isInteger(t.dimensions)||t.dimensions<=0)throw await t.destroy().catch(()=>void 0),Error(`engine ${t.info.name} reports ${t.dimensions} dimensions`);return new Embedder(t)}get engine(){return this.#e.info}get modelId(){return this.#e.modelId}get dimensions(){return this.#e.dimensions}get backend(){return this.#e.backend}async embedQuery(e,t={}){let[n]=await this.#r(1,t,t=>this.#e.embedQuery(e,{signal:t}).then(e=>[e]));return n}async embedDocuments(e,t={}){return e.length===0?[]:this.#r(e.length,t,t=>this.#e.embedDocuments(e,{signal:t}))}async destroy(){this.#n||(this.#n=!0,await this.#t.catch(()=>void 0),await this.#e.destroy())}#r(t,n,r){if(this.#n)return Promise.reject(Error(`Embedder was destroyed`));let{signal:i}=n;if(i?.aborted)return Promise.reject(i.reason);let a=this.#t.catch(()=>void 0).then(async()=>{i?.throwIfAborted();let n=await r(i);if(n.length!==t)throw Error(`engine ${this.#e.info.name} returned ${n.length} vectors for ${t} inputs`);for(let t of n){if(!(t instanceof Float32Array))throw TypeError(`engine returned a vector that is not a Float32Array`);if(t.length!==this.#e.dimensions)throw Error(`engine returned ${t.length} dimensions, ${this.#e.dimensions} expected`);e(t)}return n});this.#t=a;let o=untilAborted(i);return Promise.race([a,o.promise]).finally(o.dispose)}};export{t as Embedder};

package/lib/esm/engine.js

@@ -0,0 +1 @@
+import{checkVector as e,normalize as t,truncateVector as n}from"./vectors.js";import{embedAcross as r}from"./pool.js";export{e as checkVector,r as embedAcross,t as normalize,n as truncateVector};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{Embedder as e}from"./embedder.js";export{e as Embedder};

package/lib/esm/llama-bins.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{runningOnGjs as e}from"./llama-runtime.js";import{join as t}from"node:path";import n from"node:process";import{hasVulkan as r}from"@gjsify/machine-fit";const i=`_nlcBuildMetadata.json`;async function loadLinuxX64(){return import(`@node-llama-cpp/linux-x64`)}async function loadLinuxArm64(){return import(`@node-llama-cpp/linux-arm64`)}async function loadLinuxX64Vulkan(){return import(`@node-llama-cpp/linux-x64-vulkan`)}const a={"linux-x64":loadLinuxX64,"linux-x64-vulkan":loadLinuxX64Vulkan,"linux-arm64":loadLinuxArm64},o=new Set([`darwin-arm64`,`darwin-x64`,`win32-arm64`,`win32-x64`,`linux-arm64`,`linux-x64`]);function currentTarget(e=n){return`${e.platform}-${e.arch}`}function hasPrebuiltBins(t=currentTarget(),n=e()){return n?a[t]!==void 0:o.has(t)}function backendCandidates(e,t,n){let i=`${e}-vulkan`;return a[i]===void 0||t===`off`?[e]:t===`on`||r(n)?[i,e]:[e]}async function prebuiltBinsDir(e){let n=a[e];if(n===void 0)throw Error(`no prebuilt llama.cpp binaries for ${e}`);let{binsDir:r}=(await n()).getBinsDir();return t(r,e)}export{i as BUILD_METADATA_FILE,backendCandidates,currentTarget,hasPrebuiltBins,prebuiltBinsDir};

package/lib/esm/llama-engine.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{normalize as e,truncateVector as t}from"./vectors.js";import{embedAcross as n}from"./pool.js";import{collectGarbage as r,runningOnGjs as i}from"./llama-runtime.js";import{BUILD_METADATA_FILE as a,backendCandidates as o,currentTarget as s,hasPrebuiltBins as c,prebuiltBinsDir as l}from"./llama-bins.js";import{EMBEDDING_MODELS as u}from"./llama-models.js";import{documentPrompt as d,fitTokens as f,queryPrompt as p}from"./llama-prompts.js";import{join as m}from"node:path";import{checkFit as h,createGpuGuard as g,defaultGuardDir as _,readMachineMemory as v,systemProbe as y}from"@gjsify/machine-fit";import{readFileSync as b}from"node:fs";import{ModelStore as x}from"@gjsify/model-store";const S={name:`llama.cpp`,locality:`local`},C=2,w=2;async function loadNapi(){return import(`@gjsify/napi`)}async function createLlamaOnGjs(e,t,n){let[{loadAddon:r},i]=await Promise.all([loadNapi(),l(t)]),o=m(i,`llama-addon.node`);return e.Llama._create({bindings:r(o),bindingPath:o,extBackendsPath:i,buildType:`prebuilt`,buildMetadata:JSON.parse(b(m(i,a),`utf8`)),logLevel:e.LlamaLogLevel.warn,logger:e.Llama.defaultConsoleLogger,maxThreads:n,vramPadding:0,ramPadding:0,debug:!1,numa:!1,tempDir:!1})}async function createLlamaOnNode(e,t){if(!t)return{llama:await e.getLlama({gpu:`auto`}),onCpu:!1};try{return{llama:await e.getLlama({gpu:!1,build:`never`}),onCpu:!1}}catch{let t=await e.getLlama({gpu:`auto`,build:`never`});return{llama:t,onCpu:t.gpu!==!1}}}async function openOn(e,t,n=!1){let r=e.gpu!==!1&&!n,i=r?Math.max(1,Math.trunc(t.gpuContexts)):1,a=await e.loadModel({modelPath:t.modelPath,...n?{gpuLayers:0}:{}}),o=[];try{for(let e=0;e<i;e++)o.push(await a.createEmbeddingContext({contextSize:t.entry.contextTokens,threads:t.threads}));return{llama:e,model:a,contexts:o,gpu:r}}catch(e){throw await Promise.all(o.map(e=>e.dispose().catch(()=>void 0))),await a.dispose(),e}}async function openOnGjs(e,t,n){for(let[r,i]of t.entries()){let a=r===t.length-1,o;try{if(o=await createLlamaOnGjs(e,i,n.threads),!a&&o.gpu===!1)throw Error(`${i} found no GPU`);return await openOn(o,n)}catch(e){if(await o?.dispose().catch(()=>void 0),a)throw e}}throw Error(`no llama.cpp build to try`)}let T=!1;function defaultOnGpuPinned(e){console.error(`The GPU is switched off for embeddings: process ${e.pid} died while using it (${e.at}). Turn the GPU setting on to try it again.`)}function storeFor(e){return e.store??new x({capability:`embeddings`,models:u,defaultModel:`embeddinggemma-2-q8_0`,appDataDirs:e.appDataDirs})}function createLlamaEmbeddings(a,l={}){let u=storeFor(l),m=u.require(l.model),b=l.dimensions??m.dimensions;if(!m.truncations.includes(b))throw RangeError(`${m.id} gives ${m.truncations.join(` or `)} dimensions, not ${b}`);let x=l.gpu??`auto`,C=l.threads??2,w,gpuGuard=()=>w??=g({dir:l.gpuGuardDir??_(`gjsify`)}),gpuBarred=()=>{if(x===`off`)return!0;if(x===`on`)return gpuGuard().clear(),!1;let e=gpuGuard().pin();return e===void 0?!1:(T||(T=!0,(l.onGpuPinned??defaultOnGpuPinned)(e)),!0)},openSession=async(e,t)=>{let n=t||gpuBarred(),open=async()=>{let t={modelPath:e,entry:m,threads:C,gpuContexts:l.gpuContexts??2};if(i()){let e=s();return openOnGjs(a,n?[e]:o(e,x,l.probe??y()),t)}let{llama:r,onCpu:c}=await createLlamaOnNode(a,n);return openOn(r,t,c)};return n?open():gpuGuard().during(open)},closeSession=async e=>{let close=async()=>{await Promise.all(e.contexts.map(e=>e.dispose())),await e.model.dispose(),await e.llama.dispose()};await(e.gpu?gpuGuard().during(close):close())};return{info:S,async availability(){let e=l.probe??y();if(!c(s(e)))return`unavailable`;let t=v(e);return h(m.footprintBytes,t).placement===`none`?`unavailable`:u.availability(m.id,{path:l.modelPath})},async create(i={}){let a=await u.install(m.id,{path:l.modelPath,monitor:i.monitor,signal:i.signal});i.signal?.throwIfAborted();let o=await openSession(a,!1),embedOnce=async(n,r,i)=>{let{vector:a}=await r.getEmbeddingFor(f(n.model,i,m.contextTokens));return b===m.dimensions?e(a):t(a,b)},embed=async e=>{let t=o,{vectors:r,failure:i}=await n(t.contexts,e,(e,n)=>embedOnce(t,e,n));if(i!==void 0){if(!t.gpu)throw i.error;await closeSession(t),o=await openSession(a,!0);for(let[t,n]of e.entries())r[t]??=await embedOnce(o,o.contexts[0],n)}return r},guarded=e=>o.gpu?gpuGuard().during(e):e();return{info:S,modelId:m.modelId,dimensions:b,get backend(){return o.gpu?`gpu`:`cpu`},async embedQuery(e){let[t]=await guarded(()=>embed([p(m,e)]));return t},async embedDocuments(e){let t=await guarded(()=>embed(e.map(e=>d(m,e))));return l.collectGarbage!==!1&&r(),t},async destroy(){await closeSession(o)}}}}}export{w as DEFAULT_GPU_CONTEXTS,C as DEFAULT_THREADS,S as LLAMA_ENGINE,createLlamaEmbeddings};

package/lib/esm/llama-models.js

@@ -0,0 +1 @@
+const e=`embeddinggemma-2-q8_0`,t=[{id:e,file:`embeddinggemma-2-Q8_0.gguf`,url:`https://huggingface.co/ggml-org/embeddinggemma-2-GGUF/resolve/58faf90940886df2d62be555c8765d00dac362c5/embeddinggemma-2-Q8_0.gguf`,bytes:309855456,sha256:`2188ac1deca4b77dffefd603c2776a9d76d9d74ec01841392982ebb840b09135`,license:`Apache-2.0`,redistributable:!0,modelId:`ggml-org/embeddinggemma-2-GGUF:Q8_0`,description:`EmbeddingGemma 2, Q8_0 (296 MiB): multilingual, 768 dimensions, truncatable to 256.`,dimensions:768,truncations:[768,256],queryTemplate:`task: search result | query: {text}`,documentTemplate:`title: {title} | text: {text}`,emptyTitle:`none`,contextTokens:512,footprintBytes:850*1024*1024}];export{e as DEFAULT_EMBEDDING_MODEL,t as EMBEDDING_MODELS};

package/lib/esm/llama-prompts.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function queryPrompt(e,t){return e.queryTemplate.replace(`{text}`,()=>t)}function documentPrompt(e,t){let n=t.title?.trim()||e.emptyTitle;return e.documentTemplate.replace(`{title}`,()=>n).replace(`{text}`,()=>t.text)}function fitTokens(e,t,n){let r=n-8,i=e.tokenize(t);return i.length<=r?t:e.detokenize(i.slice(0,r))}export{documentPrompt,fitTokens,queryPrompt};

package/lib/esm/llama-runtime.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function runningOnGjs(e=globalThis){return e.imports!==void 0&&e.process?.versions?.gjs!==void 0}function collectGarbage(){(globalThis.imports?.system)?.gc?.()}export{collectGarbage,runningOnGjs};

package/lib/esm/llama.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{collectGarbage as e}from"./llama-runtime.js";import{DEFAULT_EMBEDDING_MODEL as t,EMBEDDING_MODELS as n}from"./llama-models.js";import{DEFAULT_GPU_CONTEXTS as r,DEFAULT_THREADS as i,LLAMA_ENGINE as a,createLlamaEmbeddings as o}from"./llama-engine.js";import*as s from"node-llama-cpp";function llamaEmbeddings(e={}){return o(s,e)}export{t as DEFAULT_EMBEDDING_MODEL,r as DEFAULT_GPU_CONTEXTS,i as DEFAULT_THREADS,n as EMBEDDING_MODELS,a as LLAMA_ENGINE,e as collectGarbage,llamaEmbeddings};

package/lib/esm/pool.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";async function embedAcross(e,t,n){let r=Array.from({length:t.length}),i,a=0;return await Promise.all(e.map(async e=>{for(;i===void 0&&a<t.length;){let o=a++;try{r[o]=await n(e,t[o])}catch(e){i??={error:e}}}})),i===void 0?{vectors:r}:{vectors:r,failure:i}}export{embedAcross};

package/lib/esm/vectors.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function checkVector(e){if(e.length===0)throw Error(`embedding engine returned an empty vector`);let t=0;for(let n=0;n<e.length;n++){let r=e[n];if(!Number.isFinite(r))throw Error(`embedding engine returned a non-finite value`);t+=r*r}if(t===0)throw Error(`embedding engine returned a zero-norm vector`)}function normalize(e){checkVector(e);let t=0;for(let n=0;n<e.length;n++)t+=e[n]*e[n];let n=Math.sqrt(t),r=new Float32Array(e.length);for(let t=0;t<e.length;t++)r[t]=e[t]/n;return r}function truncateVector(e,t){if(e.length<t)throw Error(`cannot truncate a ${e.length}-dimensional vector to ${t}`);return normalize(Array.prototype.slice.call(e,0,t))}export{checkVector,normalize,truncateVector};

package/lib/types/embedder.d.ts

@@ -0,0 +1,22 @@
+import type { Availability, EmbedCallOptions, EmbedDocument, EmbeddingEngineFactory, EngineCreateOptions, EngineInfo } from './engine.js';
+export interface EmbedderAvailabilityOptions {
+    readonly engine: EmbeddingEngineFactory;
+}
+export interface EmbedderCreateOptions extends EngineCreateOptions {
+    readonly engine: EmbeddingEngineFactory;
+}
+export declare class Embedder {
+    #private;
+    private constructor();
+    static availability(options: EmbedderAvailabilityOptions): Promise<Availability>;
+    /** Downloads the model when the engine needs one and it is missing, then loads it. */
+    static create(options: EmbedderCreateOptions): Promise<Embedder>;
+    get engine(): EngineInfo;
+    get modelId(): string;
+    get dimensions(): number;
+    get backend(): 'gpu' | 'cpu' | undefined;
+    embedQuery(text: string, options?: EmbedCallOptions): Promise<Float32Array>;
+    embedDocuments(documents: readonly EmbedDocument[], options?: EmbedCallOptions): Promise<Float32Array[]>;
+    /** Waits for a running call, then frees the model. Later calls reject. */
+    destroy(): Promise<void>;
+}

package/lib/types/embedder.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/engine.d.ts

@@ -0,0 +1,43 @@
+import type { CreateMonitorCallback } from '@gjsify/model-store';
+export { checkVector, normalize, truncateVector } from './vectors.js';
+export { embedAcross, type PoolResult } from './pool.js';
+/** The WebML CG availability states. */
+export type Availability = 'unavailable' | 'downloadable' | 'downloading' | 'available';
+/**
+ * A document as an embedding model sees it. Title and text stay apart because
+ * instruction-tuned models give the title its own prompt field.
+ */
+export interface EmbedDocument {
+    readonly title?: string;
+    readonly text: string;
+}
+/** Which engine runs, so a surface can say where the text goes (ADR 0132 § 3). */
+export interface EngineInfo {
+    readonly name: string;
+    readonly locality: 'local' | 'remote';
+}
+export interface EmbedCallOptions {
+    readonly signal?: AbortSignal;
+}
+/** A loaded model. Every method may be called again after the previous call settled. */
+export interface EmbeddingEngine {
+    readonly info: EngineInfo;
+    /** What produced the vectors, recorded by an index next to them. */
+    readonly modelId: string;
+    readonly dimensions: number;
+    /** Where the vectors are computed right now, when the engine knows; it can change mid-run. */
+    readonly backend?: 'gpu' | 'cpu';
+    embedQuery(text: string, options?: EmbedCallOptions): Promise<Float32Array>;
+    embedDocuments(documents: readonly EmbedDocument[], options?: EmbedCallOptions): Promise<Float32Array[]>;
+    destroy(): Promise<void>;
+}
+export interface EngineCreateOptions {
+    readonly monitor?: CreateMonitorCallback;
+    readonly signal?: AbortSignal;
+}
+/** How `Embedder` asks an engine whether it can run, and starts it. */
+export interface EmbeddingEngineFactory {
+    readonly info: EngineInfo;
+    availability(): Promise<Availability>;
+    create(options?: EngineCreateOptions): Promise<EmbeddingEngine>;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,2 @@
+export { Embedder, type EmbedderAvailabilityOptions, type EmbedderCreateOptions } from './embedder.js';
+export type { Availability, EmbedCallOptions, EmbedDocument, EngineInfo } from './engine.js';

package/lib/types/llama-bins.d.ts

@@ -0,0 +1,22 @@
+import { type GpuSetting, type MachineProbe } from '@gjsify/machine-fit';
+/** The build description node-llama-cpp writes beside every prebuilt binary. */
+export declare const BUILD_METADATA_FILE = "_nlcBuildMetadata.json";
+/** This machine, as node-llama-cpp names its binary directories. */
+export declare function currentTarget(probe?: Pick<MachineProbe, 'platform' | 'arch'>): string;
+/**
+ * Is there a prebuilt binary for this machine? A table lookup, so it is free
+ * to ask; `true` does not promise the model loads.
+ *
+ * Two answers, because the runtimes reach the binary differently: under GJS
+ * the engine hands node-llama-cpp a directory, under Node `getLlama()` looks
+ * for it. Answering from the GJS table on Node would rule out every Mac.
+ */
+export declare function hasPrebuiltBins(target?: string, onGjs?: boolean): boolean;
+/**
+ * The GJS builds to try, best first; the last is always the CPU build. Only
+ * Linux x64 has two. Not asking `getLlama()` is deliberate: it `fork`s a
+ * second interpreter to self-test the binary.
+ */
+export declare function backendCandidates(target: string, gpu: GpuSetting, probe: MachineProbe): string[];
+/** The directory holding the addon and its backends, or an error naming the machine. */
+export declare function prebuiltBinsDir(target: string): Promise<string>;

package/lib/types/llama-engine.d.ts

@@ -0,0 +1,81 @@
+import { type GpuPin, type GpuSetting, type MachineProbe } from '@gjsify/machine-fit';
+import { ModelStore } from '@gjsify/model-store';
+import type { EmbeddingEngineFactory, EngineInfo } from './engine.js';
+import { type EmbeddingModelEntry } from './llama-models.js';
+export declare const LLAMA_ENGINE: EngineInfo;
+/** Two, not "all cores": an indexer may run for hours next to the person's own work. */
+export declare const DEFAULT_THREADS = 2;
+/**
+ * Contexts that evaluate side by side on a GPU. One context holds one
+ * sequence and node-llama-cpp serialises calls on it, so a lone context leaves
+ * the device idle between calls. Measured on an RX 6600, 400 documents in
+ * batches of 16: one context 24.6/s, two 27.5/s, four and six no more than
+ * two. The CPU keeps one: there the threads are the budget.
+ */
+export declare const DEFAULT_GPU_CONTEXTS = 2;
+export interface LlamaEmbeddingsOptions {
+    /** An id from {@link EMBEDDING_MODELS}. */
+    readonly model?: string;
+    /** A file the person already has; checked against the manifest's size and digest. */
+    readonly modelPath?: string;
+    /** Directories the app ships models in, read-only, searched before the cache. */
+    readonly appDataDirs?: readonly string[];
+    /** A store of {@link EMBEDDING_MODELS}; tests and apps with their own cache root. */
+    readonly store?: ModelStore<EmbeddingModelEntry>;
+    /** One of the model's `truncations`. Default: its native size. */
+    readonly dimensions?: number;
+    /** The person's GPU switch, e.g. `parseGpuSetting(env.MYAPP_GPU)`. `on` also lifts a pin. */
+    readonly gpu?: GpuSetting;
+    readonly threads?: number;
+    readonly gpuContexts?: number;
+    /**
+     * Where the GPU guard keeps its pin. Default: the one shared by every
+     * gjsify GPU engine (ADR 0132 § 6), so a hang under one app warns the next.
+     */
+    readonly gpuGuardDir?: string;
+    /** Told once per process when a pin keeps this engine on the CPU. Default: a line on stderr. */
+    readonly onGpuPinned?: (pin: GpuPin) => void;
+    /** Run the GC after each `embedDocuments` on GJS; see `collectGarbage`. Default `true`. */
+    readonly collectGarbage?: boolean;
+    /** The machine `availability()` asks. */
+    readonly probe?: MachineProbe;
+}
+interface EmbeddingContextLike {
+    getEmbeddingFor(text: string): Promise<{
+        vector: readonly number[];
+    }>;
+    dispose(): Promise<void>;
+}
+interface ModelLike {
+    tokenize(text: string): readonly number[];
+    detokenize(tokens: readonly number[]): string;
+    createEmbeddingContext(options: {
+        contextSize: number;
+        threads?: number;
+    }): Promise<EmbeddingContextLike>;
+    dispose(): Promise<void>;
+}
+interface LlamaLike {
+    gpu: false | string;
+    loadModel(options: {
+        modelPath: string;
+        gpuLayers?: number;
+    }): Promise<ModelLike>;
+    dispose(): Promise<void>;
+}
+export interface NodeLlamaCpp {
+    getLlama(options: {
+        gpu: 'auto' | false;
+        build?: 'never';
+    }): Promise<LlamaLike>;
+    Llama: {
+        _create(options: Record<string, unknown>): Promise<LlamaLike>;
+        defaultConsoleLogger: unknown;
+    };
+    LlamaLogLevel: {
+        warn: unknown;
+    };
+}
+/** {@link llamaEmbeddings} with node-llama-cpp passed in. */
+export declare function createLlamaEmbeddings(nlc: NodeLlamaCpp, options?: LlamaEmbeddingsOptions): EmbeddingEngineFactory;
+export {};

package/lib/types/llama-models.d.ts

@@ -0,0 +1,27 @@
+import type { ModelEntry } from '@gjsify/model-store';
+export interface EmbeddingModelEntry extends ModelEntry {
+    /**
+     * What an index records next to the vectors (`Embedder.modelId`). Never
+     * changes for an entry: a new value makes every existing index stale.
+     */
+    readonly modelId: string;
+    /** Native vector size. */
+    readonly dimensions: number;
+    /** Sizes the model was trained to be truncated to (Matryoshka), largest first. */
+    readonly truncations: readonly number[];
+    /** The query prompt; `{text}` is replaced. */
+    readonly queryTemplate: string;
+    /** The document prompt; `{title}` and `{text}` are replaced. */
+    readonly documentTemplate: string;
+    /** What `{title}` becomes for a document without one. */
+    readonly emptyTitle: string;
+    /** Tokens per context. Longer input is cut to fit (`fitTokens`). */
+    readonly contextTokens: number;
+    /**
+     * Memory one loaded copy needs, runtime included, for `checkFit`
+     * (ADR 0136 § 6). Measured, not derived from the file size.
+     */
+    readonly footprintBytes: number;
+}
+export declare const DEFAULT_EMBEDDING_MODEL = "embeddinggemma-2-q8_0";
+export declare const EMBEDDING_MODELS: readonly EmbeddingModelEntry[];

package/lib/types/llama-prompts.d.ts

@@ -0,0 +1,18 @@
+import type { EmbedDocument } from './engine.js';
+import type { EmbeddingModelEntry } from './llama-models.js';
+type Templates = Pick<EmbeddingModelEntry, 'queryTemplate' | 'documentTemplate' | 'emptyTitle'>;
+export declare function queryPrompt(model: Templates, text: string): string;
+/** The title goes into its own field only; repeating it in the text would weigh it twice. */
+export declare function documentPrompt(model: Templates, document: EmbedDocument): string;
+/** The two tokenizer calls {@link fitTokens} needs; a loaded model has both. */
+export interface Tokenizing {
+    tokenize(text: string): readonly number[];
+    detokenize(tokens: readonly number[]): string;
+}
+/**
+ * Cut the text to what a context of `contextTokens` holds. A character limit
+ * is only a guess: digits and rare scripts cost about one token per
+ * character, and llama.cpp rejects an over-long input instead of truncating.
+ */
+export declare function fitTokens(model: Tokenizing, text: string, contextTokens: number): string;
+export {};

package/lib/types/llama-runtime.d.ts

@@ -0,0 +1,28 @@
+/** What {@link runningOnGjs} looks at; injected so the Node-with-node-gi case is testable. */
+export interface RuntimeHost {
+    imports?: unknown;
+    process?: {
+        versions?: {
+            gjs?: string;
+        };
+    };
+}
+/**
+ * Is this GJS? Not "is there an `imports`": node-gi defines
+ * `globalThis.imports` on Node too, and asking only that sent a Node app down
+ * the `@gjsify/napi` route, which Node cannot load.
+ */
+export declare function runningOnGjs(host?: RuntimeHost): boolean;
+/**
+ * Run SpiderMonkey's garbage collector now; a no-op on Node.
+ *
+ * GJS decides when to collect from the JS heap alone, and an embedding run's
+ * garbage is mostly NATIVE memory behind small wrapper objects. The heap looks
+ * small, so no collection comes: a 1500-document run climbed from 0.85 GB to
+ * 1.8 GB, and one collection per batch held it at 0.85 GB.
+ *
+ * A collection inside a database transaction has broken commits before. A
+ * caller that embeds inside one sets `collectGarbage: false` on the engine and
+ * calls this after the commit.
+ */
+export declare function collectGarbage(): void;

package/lib/types/llama.d.ts

@@ -0,0 +1,7 @@
+import type { EmbeddingEngineFactory } from './engine.js';
+import { type LlamaEmbeddingsOptions } from './llama-engine.js';
+export { DEFAULT_GPU_CONTEXTS, DEFAULT_THREADS, LLAMA_ENGINE, type LlamaEmbeddingsOptions } from './llama-engine.js';
+export { DEFAULT_EMBEDDING_MODEL, EMBEDDING_MODELS, type EmbeddingModelEntry } from './llama-models.js';
+export { collectGarbage } from './llama-runtime.js';
+/** The llama.cpp engine factory, for `Embedder.availability()` and `Embedder.create()`. */
+export declare function llamaEmbeddings(options?: LlamaEmbeddingsOptions): EmbeddingEngineFactory;

package/lib/types/llama.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/pool.d.ts

@@ -0,0 +1,15 @@
+export interface PoolResult<T> {
+    /** One slot per text; a slot is empty when its text was never embedded. */
+    vectors: (T | undefined)[];
+    /** The first error a context threw, if any. */
+    failure?: {
+        error: unknown;
+    };
+}
+/**
+ * Every context takes the next text until none is left, so one long text does
+ * not hold up the others. The first failure stops the workers from taking
+ * more, and the call returns only once EVERY worker has settled: the caller
+ * may then dispose the contexts, which is not safe under a running evaluation.
+ */
+export declare function embedAcross<C, T>(contexts: readonly C[], texts: readonly string[], embedOne: (context: C, text: string) => Promise<T>): Promise<PoolResult<T>>;

package/lib/types/vectors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Throws when `vector` is empty, holds a non-finite value, or is all zeros —
+ * a zero vector has no direction, so cosine similarity is undefined for it.
+ */
+export declare function checkVector(vector: ArrayLike<number>): void;
+/** A unit-length copy. Throws on what {@link checkVector} rejects. */
+export declare function normalize(vector: ArrayLike<number>): Float32Array;
+/**
+ * Matryoshka truncation: keep the leading `dimensions` and renormalise. Only
+ * meaningful for a model trained for it; the model's entry lists the sizes.
+ */
+export declare function truncateVector(vector: ArrayLike<number>, dimensions: number): Float32Array;

package/lib/types/vectors.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,114 @@
 {
-  "name": "@gjsify/embeddings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/embeddings",
+    "version": "0.64.26",
+    "description": "Text embeddings in the WebML CG lifecycle shape: an Embedder with availability(), create({ monitor, signal }) and destroy(), checked Float32Array vectors, and a local llama.cpp engine for GGUF models on Node and GJS.",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "type": "module",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./engine": {
+            "types": "./lib/types/engine.d.ts",
+            "default": "./lib/esm/engine.js"
+        },
+        "./llama": {
+            "types": "./lib/types/llama.d.ts",
+            "default": "./lib/esm/llama.js"
+        }
+    },
+    "files": [
+        "lib",
+        "!lib/types/**/*.spec.d.ts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs --external node-llama-cpp,@node-llama-cpp/linux-x64,@node-llama-cpp/linux-x64-vulkan,@node-llama-cpp/linux-arm64,@gjsify/napi",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs --external node-llama-cpp,@node-llama-cpp/linux-x64,@node-llama-cpp/linux-x64-vulkan,@node-llama-cpp/linux-arm64,@gjsify/napi",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs"
+    },
+    "keywords": [
+        "embeddings",
+        "semantic-search",
+        "ai",
+        "gguf",
+        "llama.cpp",
+        "webml"
+    ],
+    "dependencies": {
+        "@gjsify/fs": "^0.64.26",
+        "@gjsify/machine-fit": "^0.64.26",
+        "@gjsify/model-store": "^0.64.26",
+        "@gjsify/path": "^0.64.26",
+        "@gjsify/process": "^0.64.26"
+    },
+    "peerDependencies": {
+        "@gjsify/napi": "^0.64.19",
+        "node-llama-cpp": "^3.22.2",
+        "@node-llama-cpp/linux-arm64": "^3.22.2",
+        "@node-llama-cpp/linux-x64": "^3.22.2",
+        "@node-llama-cpp/linux-x64-vulkan": "^3.22.2"
+    },
+    "peerDependenciesMeta": {
+        "@gjsify/napi": {
+            "optional": true
+        },
+        "node-llama-cpp": {
+            "optional": true
+        },
+        "@node-llama-cpp/linux-arm64": {
+            "optional": true
+        },
+        "@node-llama-cpp/linux-x64": {
+            "optional": true
+        },
+        "@node-llama-cpp/linux-x64-vulkan": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.64.26",
+        "@gjsify/unit": "^0.64.26",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/gjs/embeddings"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/gjs/embeddings#readme",
+    "gjsify": {
+        "tier": 3,
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "partial"
+        },
+        "osNotes": {
+            "darwin": "The llama.cpp engine runs on Node only: the GJS route loads node-llama-cpp's Linux prebuilt binaries.",
+            "win32": "The llama.cpp engine runs on Node only: the GJS route loads node-llama-cpp's Linux prebuilt binaries."
+        },
+        "headless": true
+    }
+}