@oortmem/local-models 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @oortmem/local-models
 
-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.
+Embeddings and reranking for Oort on this machine's CPU, through ONNX Runtime. No API keys, no account, and no network after the one-time download.
+
+```sh
+npm install -g oortmem @oortmem/local-models
+oort models pull     # downloads the default models (58 MB) into ~/.oort/models and switches to them
+```
+
+| Role   | Default                 | Size  | Licence    | Upstream                            |
+| ------ | ----------------------- | ----- | ---------- | ----------------------------------- |
+| embed  | `bge-small-en-v1.5`     | 34 MB | MIT        | BAAI/bge-small-en-v1.5              |
+| rerank | `ms-marco-minilm-l6-v2` | 23 MB | Apache-2.0 | cross-encoder/ms-marco-MiniLM-L6-v2 |
+
+Larger multilingual models (`qwen3-embedding-0.6b`, `bge-reranker-v2-m3`, about 600 MB each) are available with `oort models pull <id>`; they take about a second to load, so they suit `oort mcp` better than per-prompt hooks.
+
+Every file is pinned to a Hugging Face commit and its SHA-256, checked before it is kept. Models are never downloaded during a hook or a recall, only by `oort models pull` or `oort setup`.
+
+```ts
+import { localEmbedder, localReranker } from '@oortmem/local-models';
+
+const embed = localEmbedder({ home: '/path/to/.oort', dimension: 512 });
+const rerank = localReranker({ home: '/path/to/.oort' });
+```
+
+Runtime dependencies: [onnxruntime-node](https://github.com/microsoft/onnxruntime) (MIT) and [@huggingface/tokenizers](https://github.com/huggingface/tokenizers.js) (Apache-2.0).
+
+Part of [Oort](https://github.com/oortmem/oort), open-source memory for AI agents. See the [main README](https://github.com/oortmem/oort#readme) for how the pieces fit. Apache-2.0.

package/dist/catalog.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The models Oort can run locally. Each file is pinned to a Hugging Face commit and a SHA-256,
+ * so a pull is reproducible and a tampered or truncated download is refused.
+ *
+ * The defaults are small on purpose: every Claude Code hook is a new process, so a model is
+ * loaded from disk once per prompt. Measured on an Apple M1 Max (single thread, CPU time):
+ * bge-small loads in about 110 ms (22 ms from the optimised cache) and embeds a query in 6 ms;
+ * the MiniLM reranker loads in about 60 ms (13 ms cached) and scores 16 short documents in
+ * 110 ms. The large models load in 0.8 to 1 s, need over 1 GB of RAM, and suit the long-lived
+ * `oort mcp` server rather than per-prompt hooks.
+ */
+export type ModelRole = 'embed' | 'rerank';
+/** One file of a model: where it comes from in the repo, and what it must hash to. */
+export interface ModelFile {
+    /** The local file name inside the model's directory. */
+    name: 'model.onnx' | 'tokenizer.json' | 'tokenizer_config.json';
+    /** Path inside the Hugging Face repository. */
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+interface BaseSpec {
+    /** The id `embed.model` / `rerank.model` names, and the directory under `~/.oort/models`. */
+    id: string;
+    role: ModelRole;
+    /** One line for `oort models`. */
+    label: string;
+    /** `small` loads fast enough for hooks; `large` is for the long-lived MCP server. */
+    size: 'small' | 'large';
+    /** The ONNX conversion that is downloaded, pinned to a commit. */
+    source: {
+        repo: string;
+        revision: string;
+    };
+    /** The original model the conversion was made from. */
+    upstream: string;
+    /** SPDX id of the model weights' licence (all allow commercial use). */
+    licence: string;
+    files: readonly ModelFile[];
+    /** Longest input in tokens, special tokens included. */
+    maxTokens: number;
+}
+export interface EmbedModelSpec extends BaseSpec {
+    role: 'embed';
+    /** The width of the model's own embedding. */
+    nativeDimension: number;
+    /** `cls`: the first token; `mean`: masked mean; `last`: the last real token. */
+    pooling: 'cls' | 'mean' | 'last';
+    /** Trained with Matryoshka loss, so a prefix of the embedding is itself an embedding. */
+    matryoshka: boolean;
+    queryPrefix: string;
+    documentPrefix: string;
+    /** A decoder export that takes (empty) past key/value inputs. */
+    kvCache?: {
+        layers: number;
+        heads: number;
+        headDim: number;
+    };
+}
+export interface RerankModelSpec extends BaseSpec {
+    role: 'rerank';
+    /**
+     * The score is `sigmoid(scale * logit + shift)`. MS MARCO cross-encoders emit uncalibrated
+     * logits (unrelated pairs sit near -10); this maps them onto the 0 to 1 range that
+     * `recall.minRerankScore` (0.35) was set for. Provisional until calibrated on the eval.
+     */
+    calibration: {
+        scale: number;
+        shift: number;
+    };
+}
+export type ModelSpec = EmbedModelSpec | RerankModelSpec;
+export declare const MODELS: readonly ModelSpec[];
+export declare const DEFAULT_EMBED_MODEL = "bge-small-en-v1.5";
+export declare const DEFAULT_RERANK_MODEL = "ms-marco-minilm-l6-v2";
+/** The catalog entry for `id`, or undefined. */
+export declare function findModel(id: string): ModelSpec | undefined;
+/** Total download size of `spec` in bytes. */
+export declare function downloadBytes(spec: ModelSpec): number;
+export {};

package/dist/catalog.js

@@ -0,0 +1,165 @@
+/**
+ * The models Oort can run locally. Each file is pinned to a Hugging Face commit and a SHA-256,
+ * so a pull is reproducible and a tampered or truncated download is refused.
+ *
+ * The defaults are small on purpose: every Claude Code hook is a new process, so a model is
+ * loaded from disk once per prompt. Measured on an Apple M1 Max (single thread, CPU time):
+ * bge-small loads in about 110 ms (22 ms from the optimised cache) and embeds a query in 6 ms;
+ * the MiniLM reranker loads in about 60 ms (13 ms cached) and scores 16 short documents in
+ * 110 ms. The large models load in 0.8 to 1 s, need over 1 GB of RAM, and suit the long-lived
+ * `oort mcp` server rather than per-prompt hooks.
+ */
+const HF_TOKENIZER_JSON_BERT_UNCASED = {
+    name: 'tokenizer.json',
+    path: 'tokenizer.json',
+    bytes: 711_396,
+    sha256: 'd241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66',
+};
+export const MODELS = [
+    {
+        id: 'bge-small-en-v1.5',
+        role: 'embed',
+        label: 'BGE small, English (int8, 34 MB)',
+        size: 'small',
+        source: {
+            repo: 'Xenova/bge-small-en-v1.5',
+            revision: 'ea104dacec62c0de699686887e3f920caeb4f3e3',
+        },
+        upstream: 'BAAI/bge-small-en-v1.5',
+        licence: 'MIT',
+        files: [
+            {
+                name: 'model.onnx',
+                path: 'onnx/model_int8.onnx',
+                bytes: 33_760_831,
+                sha256: 'bf64d05457cb391fa88d045faf5927a15ea36d96228ddf23ea970087afdc1197',
+            },
+            HF_TOKENIZER_JSON_BERT_UNCASED,
+            {
+                name: 'tokenizer_config.json',
+                path: 'tokenizer_config.json',
+                bytes: 366,
+                sha256: '9261e7d79b44c8195c1cada2b453e55b00aeb81e907a6664974b4d7776172ab3',
+            },
+        ],
+        maxTokens: 512,
+        nativeDimension: 384,
+        pooling: 'cls',
+        matryoshka: false,
+        queryPrefix: 'Represent this sentence for searching relevant passages: ',
+        documentPrefix: '',
+    },
+    {
+        id: 'ms-marco-minilm-l6-v2',
+        role: 'rerank',
+        label: 'MS MARCO MiniLM-L6 cross-encoder, English (int8, 23 MB)',
+        size: 'small',
+        source: {
+            repo: 'Xenova/ms-marco-MiniLM-L-6-v2',
+            revision: 'a09144355adeed5f58c8ed011d209bf8ee5a1fec',
+        },
+        upstream: 'cross-encoder/ms-marco-MiniLM-L6-v2',
+        licence: 'Apache-2.0',
+        files: [
+            {
+                name: 'model.onnx',
+                path: 'onnx/model_int8.onnx',
+                bytes: 23_012_404,
+                sha256: 'a13ec391ca99f49886694e12d3e800521f36d4267d7d448c34421c541a2baf50',
+            },
+            HF_TOKENIZER_JSON_BERT_UNCASED,
+            {
+                name: 'tokenizer_config.json',
+                path: 'tokenizer_config.json',
+                bytes: 1_242,
+                sha256: '0b29c7bfc889e53b36d9dd3e686dd4300f6525110eaa98c76a5dafceb2029f53',
+            },
+        ],
+        maxTokens: 512,
+        calibration: { scale: 0.5, shift: 2.4 },
+    },
+    {
+        id: 'qwen3-embedding-0.6b',
+        role: 'embed',
+        label: 'Qwen3 Embedding 0.6B, multilingual (int8, 614 MB; slow to load, for oort mcp)',
+        size: 'large',
+        source: {
+            repo: 'onnx-community/Qwen3-Embedding-0.6B-ONNX',
+            revision: 'c25a394dd583836952667c12f008335071b3f43d',
+        },
+        upstream: 'Qwen/Qwen3-Embedding-0.6B',
+        licence: 'Apache-2.0',
+        files: [
+            {
+                name: 'model.onnx',
+                path: 'onnx/model_int8.onnx',
+                bytes: 613_527_539,
+                sha256: '6d0ea863f78b4a84afa3c7fcba1ec341572b5e28121aef77b7092b1dfdf679c7',
+            },
+            {
+                name: 'tokenizer.json',
+                path: 'tokenizer.json',
+                bytes: 11_423_705,
+                sha256: 'def76fb086971c7867b829c23a26261e38d9d74e02139253b38aeb9df8b4b50a',
+            },
+            {
+                name: 'tokenizer_config.json',
+                path: 'tokenizer_config.json',
+                bytes: 9_731,
+                sha256: '977648852447cb6587327ff3205b0a84cf2fc9f05621d6c8e88a497caafab2e1',
+            },
+        ],
+        maxTokens: 1024,
+        nativeDimension: 1024,
+        pooling: 'last',
+        matryoshka: true,
+        queryPrefix: 'Instruct: Given a question about a software project, retrieve the note that answers it\nQuery:',
+        documentPrefix: '',
+        kvCache: { layers: 28, heads: 8, headDim: 128 },
+    },
+    {
+        id: 'bge-reranker-v2-m3',
+        role: 'rerank',
+        label: 'BGE reranker v2 m3, multilingual (int8, 571 MB; slow, for oort mcp)',
+        size: 'large',
+        source: {
+            repo: 'onnx-community/bge-reranker-v2-m3-ONNX',
+            revision: '6f5ff65298512715a1e669753bc754d2bc8f367b',
+        },
+        upstream: 'BAAI/bge-reranker-v2-m3',
+        licence: 'Apache-2.0',
+        files: [
+            {
+                name: 'model.onnx',
+                path: 'onnx/model_int8.onnx',
+                bytes: 570_727_094,
+                sha256: '912fc1215c2dbff6499700534bd8d31253af01573861abbfc43afd1fab6cce5d',
+            },
+            {
+                name: 'tokenizer.json',
+                path: 'tokenizer.json',
+                bytes: 17_082_900,
+                sha256: '8bf8afbfd11306bd872018c53bfdf2e160a56f8edbcf49933324404791c148d3',
+            },
+            {
+                name: 'tokenizer_config.json',
+                path: 'tokenizer_config.json',
+                bytes: 1_203,
+                sha256: 'b87c8703482b0300d3da30e201519aa641f6a450f5eb5bf1e624afbf70c74d80',
+            },
+        ],
+        maxTokens: 512,
+        calibration: { scale: 1, shift: 0 },
+    },
+];
+export const DEFAULT_EMBED_MODEL = 'bge-small-en-v1.5';
+export const DEFAULT_RERANK_MODEL = 'ms-marco-minilm-l6-v2';
+/** The catalog entry for `id`, or undefined. */
+export function findModel(id) {
+    return MODELS.find((m) => m.id === id);
+}
+/** Total download size of `spec` in bytes. */
+export function downloadBytes(spec) {
+    return spec.files.reduce((n, f) => n + f.bytes, 0);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/embed.d.ts

@@ -0,0 +1,32 @@
+import type { Embedder } from '@oortmem/core';
+import { type EmbedModelSpec } from './catalog.js';
+import { type Runtime } from './runtime.js';
+export interface LocalEmbedderOptions {
+    /** `$OORT_HOME`; models live in `<home>/models/<id>`. */
+    home: string;
+    /** Catalog id, default `bge-small-en-v1.5`. */
+    model?: string;
+    /**
+     * The store's dimension. A narrower model is zero-padded to it (cosine similarity is
+     * unchanged); a wider Matryoshka model is truncated to it; a wider plain model is refused.
+     */
+    dimension: number;
+    /** Default: ONNX Runtime. */
+    runtime?: Runtime;
+    threads?: number;
+    /** Texts per forward pass (default 16). */
+    batchSize?: number;
+    /** A model outside the catalog (tests, experiments); used when its id is `model`. */
+    spec?: EmbedModelSpec;
+}
+export interface LocalEmbedder extends Embedder {
+    readonly model: string;
+    /** Loads the model now instead of on the first `embed` (a warm process can preload). */
+    load(): Promise<void>;
+}
+/**
+ * Embeddings on this machine's CPU. Nothing is loaded until the first `embed` (or `load`):
+ * constructing one only checks that the model was pulled, so a hook whose lexical search
+ * answers on its own pays nothing. Vectors are unit length, then int8 with a per-vector scale.
+ */
+export declare function localEmbedder(opts: LocalEmbedderOptions): LocalEmbedder;

package/dist/embed.js

@@ -0,0 +1,78 @@
+import { DEFAULT_EMBED_MODEL } from './catalog.js';
+import { clipChars, clipTokens, normalize, quantize, toBatch } from './encode.js';
+import { LocalModelError, readyModel } from './errors.js';
+import { lazyLoad, onnxRuntime } from './runtime.js';
+/**
+ * Embeddings on this machine's CPU. Nothing is loaded until the first `embed` (or `load`):
+ * constructing one only checks that the model was pulled, so a hook whose lexical search
+ * answers on its own pays nothing. Vectors are unit length, then int8 with a per-vector scale.
+ */
+export function localEmbedder(opts) {
+    const id = opts.model ?? DEFAULT_EMBED_MODEL;
+    const { spec: s, dir } = readyModel(opts.home, 'embed', id, opts.spec);
+    const spec = s;
+    const { dimension } = opts;
+    if (spec.nativeDimension > dimension && !spec.matryoshka) {
+        throw new LocalModelError('dimension', `local model ${id} has ${spec.nativeDimension} dimensions and cannot be truncated to the store's ${dimension}.`);
+    }
+    const keep = Math.min(spec.nativeDimension, dimension);
+    const runtime = opts.runtime ?? onnxRuntime();
+    const batchSize = opts.batchSize ?? 16;
+    const load = lazyLoad(runtime, dir, opts.threads);
+    async function forward(m, texts) {
+        const encodings = texts.map((t) => clipTokens(m.tokenizer.encode(clipChars(t, spec.maxTokens)), spec.maxTokens));
+        const batch = toBatch(encodings, m.session.inputNames, spec.kvCache);
+        const out = (await m.session.run(batch.feeds, ['last_hidden_state']))['last_hidden_state'];
+        if (out === undefined || out.dims.length !== 3) {
+            throw new Error(`local model ${id}: unexpected output shape`);
+        }
+        const hidden = out.dims[2];
+        if (hidden !== spec.nativeDimension) {
+            throw new Error(`local model ${id}: output has ${hidden} dimensions, expected ${spec.nativeDimension}`);
+        }
+        const L = batch.length;
+        const d = out.data;
+        return batch.lengths.map((len, i) => {
+            const v = new Float32Array(hidden);
+            const row = (j) => (i * L + j) * hidden;
+            if (spec.pooling === 'cls')
+                v.set(d.subarray(row(0), row(0) + hidden));
+            else if (spec.pooling === 'last')
+                v.set(d.subarray(row(len - 1), row(len - 1) + hidden));
+            else {
+                for (let j = 0; j < len; j++) {
+                    const at = row(j);
+                    for (let h = 0; h < hidden; h++)
+                        v[h] = v[h] + d[at + h];
+                }
+                for (let h = 0; h < hidden; h++)
+                    v[h] = v[h] / len;
+            }
+            // Matryoshka: normalise the prefix; a narrow model is padded with zeros after it.
+            const prefix = normalize(v.slice(0, keep));
+            const full = new Float32Array(dimension);
+            full.set(prefix);
+            return quantize(full);
+        });
+    }
+    return {
+        dimension,
+        model: id,
+        async load() {
+            await load();
+        },
+        async embed(texts, kind) {
+            if (texts.length === 0)
+                return [];
+            const m = await load();
+            const prefix = kind === 'query' ? spec.queryPrefix : spec.documentPrefix;
+            const out = [];
+            for (let i = 0; i < texts.length; i += batchSize) {
+                const chunk = texts.slice(i, i + batchSize).map((t) => prefix + t);
+                out.push(...(await forward(m, chunk)));
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=embed.js.map

package/dist/encode.d.ts

@@ -0,0 +1,31 @@
+import type { Encoding, Feed } from './runtime.js';
+/** Roughly four characters per token: text past this many characters cannot fit anyway. */
+export declare function clipChars(text: string, maxTokens: number): string;
+/**
+ * At most `maxTokens` tokens. The tail is cut but the final special token (`[SEP]`, `</s>`,
+ * `<|endoftext|>`) is kept, so a cross-encoder pair loses the end of its document, never the
+ * structure, and last-token pooling still reads the end-of-text token.
+ */
+export declare function clipTokens(e: Encoding, maxTokens: number): Encoding;
+export interface Batch {
+    feeds: Record<string, Feed>;
+    /** Padded sequence length. */
+    length: number;
+    /** Real (unpadded) length of each row. */
+    lengths: number[];
+}
+/**
+ * Right-padded int64 inputs for the names the session declares: `input_ids`, `attention_mask`,
+ * and when declared `token_type_ids` and `position_ids`; a decoder export also gets empty past
+ * key/value tensors.
+ */
+export declare function toBatch(encodings: Encoding[], inputNames: readonly string[], kvCache?: {
+    layers: number;
+    heads: number;
+    headDim: number;
+}): Batch;
+/** Float vector to int8 with a per-vector scale (cosine similarity is scale-free). */
+export declare function quantize(v: Float32Array): Int8Array;
+/** In place: unit length (a zero vector stays zero). */
+export declare function normalize(v: Float32Array): Float32Array;
+export declare const sigmoid: (x: number) => number;

package/dist/encode.js

@@ -0,0 +1,91 @@
+/** Roughly four characters per token: text past this many characters cannot fit anyway. */
+export function clipChars(text, maxTokens) {
+    const max = maxTokens * 6;
+    return text.length > max ? text.slice(0, max) : text;
+}
+/**
+ * At most `maxTokens` tokens. The tail is cut but the final special token (`[SEP]`, `</s>`,
+ * `<|endoftext|>`) is kept, so a cross-encoder pair loses the end of its document, never the
+ * structure, and last-token pooling still reads the end-of-text token.
+ */
+export function clipTokens(e, maxTokens) {
+    if (e.ids.length <= maxTokens)
+        return e;
+    const last = e.ids.length - 1;
+    const out = { ids: [...e.ids.slice(0, maxTokens - 1), e.ids[last]] };
+    if (e.token_type_ids !== undefined) {
+        const tt = e.token_type_ids;
+        out.token_type_ids = [...tt.slice(0, maxTokens - 1), tt[last] ?? 0];
+    }
+    return out;
+}
+/**
+ * Right-padded int64 inputs for the names the session declares: `input_ids`, `attention_mask`,
+ * and when declared `token_type_ids` and `position_ids`; a decoder export also gets empty past
+ * key/value tensors.
+ */
+export function toBatch(encodings, inputNames, kvCache) {
+    const n = encodings.length;
+    const length = Math.max(1, ...encodings.map((e) => e.ids.length));
+    const ids = new BigInt64Array(n * length);
+    const mask = new BigInt64Array(n * length);
+    const types = new BigInt64Array(n * length);
+    const positions = new BigInt64Array(n * length);
+    encodings.forEach((e, i) => {
+        for (let j = 0; j < e.ids.length; j++) {
+            const at = i * length + j;
+            ids[at] = BigInt(e.ids[j]);
+            mask[at] = 1n;
+            types[at] = BigInt(e.token_type_ids?.[j] ?? 0);
+            positions[at] = BigInt(j);
+        }
+    });
+    const dims = [n, length];
+    const feeds = {
+        input_ids: { type: 'int64', data: ids, dims },
+        attention_mask: { type: 'int64', data: mask, dims },
+    };
+    if (inputNames.includes('token_type_ids'))
+        feeds['token_type_ids'] = { type: 'int64', data: types, dims };
+    if (inputNames.includes('position_ids'))
+        feeds['position_ids'] = { type: 'int64', data: positions, dims };
+    if (kvCache !== undefined) {
+        const empty = [n, kvCache.heads, 0, kvCache.headDim];
+        for (let l = 0; l < kvCache.layers; l++) {
+            for (const kv of ['key', 'value']) {
+                feeds[`past_key_values.${l}.${kv}`] = {
+                    type: 'float32',
+                    data: new Float32Array(0),
+                    dims: empty,
+                };
+            }
+        }
+    }
+    return { feeds, length, lengths: encodings.map((e) => e.ids.length) };
+}
+/** Float vector to int8 with a per-vector scale (cosine similarity is scale-free). */
+export function quantize(v) {
+    let max = 0;
+    for (const x of v)
+        max = Math.max(max, Math.abs(x));
+    const out = new Int8Array(v.length);
+    if (max === 0)
+        return out;
+    const s = 127 / max;
+    for (let i = 0; i < v.length; i++)
+        out[i] = Math.round(v[i] * s);
+    return out;
+}
+/** In place: unit length (a zero vector stays zero). */
+export function normalize(v) {
+    let s = 0;
+    for (const x of v)
+        s += x * x;
+    const n = Math.sqrt(s);
+    if (n > 0)
+        for (let i = 0; i < v.length; i++)
+            v[i] = v[i] / n;
+    return v;
+}
+export const sigmoid = (x) => 1 / (1 + Math.exp(-x));
+//# sourceMappingURL=encode.js.map

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import { type ModelRole, type ModelSpec } from './catalog.js';
+export type LocalModelErrorKind = 'unknown-model' | 'wrong-role' | 'not-ready' | 'dimension';
+/** A local model that cannot be used as configured; the message names the fix. */
+export declare class LocalModelError extends Error {
+    readonly kind: LocalModelErrorKind;
+    constructor(kind: LocalModelErrorKind, message: string);
+}
+/** The spec for `id` in `role`, pulled and complete, or a `LocalModelError` saying how to fix it. */
+export declare function readyModel(home: string, role: ModelRole, id: string, custom?: ModelSpec): {
+    spec: ModelSpec;
+    dir: string;
+};

package/dist/errors.js

@@ -0,0 +1,34 @@
+import { findModel, MODELS } from './catalog.js';
+import { modelDir, modelState } from './files.js';
+/** A local model that cannot be used as configured; the message names the fix. */
+export class LocalModelError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'LocalModelError';
+    }
+}
+const STATE_FIX = {
+    missing: 'is not downloaded',
+    incomplete: 'is incompletely downloaded',
+    outdated: 'was downloaded for another version of Oort',
+};
+/** The spec for `id` in `role`, pulled and complete, or a `LocalModelError` saying how to fix it. */
+export function readyModel(home, role, id, custom) {
+    const spec = custom?.id === id ? custom : findModel(id);
+    const key = role === 'embed' ? 'embed.model' : 'rerank.model';
+    if (spec === undefined) {
+        const ids = MODELS.filter((m) => m.role === role).map((m) => m.id);
+        throw new LocalModelError('unknown-model', `${key} "${id}" is not a local model; use one of ${ids.join(', ')} (oort models).`);
+    }
+    if (spec.role !== role) {
+        throw new LocalModelError('wrong-role', `${key} "${id}" is a ${spec.role} model.`);
+    }
+    const state = modelState(home, spec);
+    if (state !== 'ready') {
+        throw new LocalModelError('not-ready', `local model ${id} ${STATE_FIX[state]}; run \`oort models pull ${id}\`.`);
+    }
+    return { spec, dir: modelDir(home, id) };
+}
+//# sourceMappingURL=errors.js.map

package/dist/files.d.ts

@@ -0,0 +1,64 @@
+import type { ModelFile, ModelSpec } from './catalog.js';
+/** Written last by a successful pull: the model is complete and its checksums matched. */
+export declare const MANIFEST = "oort-model.json";
+/** Where model files are fetched from; `OORT_MODELS_URL` points `oort models pull` at a mirror. */
+export declare const HF_BASE_URL = "https://huggingface.co";
+export interface Manifest {
+    id: string;
+    revision: string;
+    files: {
+        name: string;
+        bytes: number;
+        sha256: string;
+    }[];
+    pulledAt: string;
+}
+/** `$OORT_HOME/models`. */
+export declare function modelsRoot(home: string): string;
+export declare function modelDir(home: string, id: string): string;
+/**
+ * - `ready`: pulled, the manifest matches the catalog, every file has its size.
+ * - `missing`: never pulled (or removed).
+ * - `incomplete`: a pull did not finish, or a file is gone or has the wrong size.
+ * - `outdated`: pulled for another revision or checksum than this version of Oort pins.
+ */
+export type ModelState = 'ready' | 'missing' | 'incomplete' | 'outdated';
+/**
+ * Cheap check (a manifest read and a stat per file, no hashing), safe on every hook. A full
+ * re-hash is `verifyModel`.
+ */
+export declare function modelState(home: string, spec: ModelSpec): ModelState;
+/** Re-hashes every file of a pulled model; lists each file that does not match its pin. */
+export declare function verifyModel(home: string, spec: ModelSpec): Promise<{
+    ok: boolean;
+    bad: string[];
+}>;
+/** A download that does not hash to its pin (or has the wrong size): nothing is kept. */
+export declare class ChecksumError extends Error {
+    readonly model: string;
+    readonly file: string;
+    constructor(model: string, file: string, detail: string);
+}
+export interface PullOptions {
+    /** Default: the global fetch. Only `pullModel` touches the network. */
+    fetch?: typeof fetch;
+    /** Default `HF_BASE_URL`. */
+    baseUrl?: string;
+    /** Called as bytes arrive, per file. */
+    onProgress?: (p: {
+        file: string;
+        received: number;
+        total: number;
+    }) => void;
+}
+export declare function fileUrl(spec: ModelSpec, f: ModelFile, baseUrl?: string): string;
+/**
+ * Downloads every file of `spec` into `$OORT_HOME/models/<id>` (owner-only), verifying each
+ * against its pinned size and SHA-256 before it is moved into place, then writes the manifest.
+ * A file already present with the right hash is kept, so an interrupted pull resumes. On any
+ * failure the manifest is absent, so the model stays unusable rather than half-trusted.
+ * Returns the number of bytes downloaded.
+ */
+export declare function pullModel(home: string, spec: ModelSpec, opts?: PullOptions): Promise<number>;
+/** Deletes a model's directory (files, manifest, optimised cache). True when it existed. */
+export declare function removeModel(home: string, id: string): boolean;

package/dist/files.js

@@ -0,0 +1,167 @@
+import { createHash, randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ensurePrivateDir, writePrivateFile } from '@oortmem/core';
+/** Written last by a successful pull: the model is complete and its checksums matched. */
+export const MANIFEST = 'oort-model.json';
+/** Where model files are fetched from; `OORT_MODELS_URL` points `oort models pull` at a mirror. */
+export const HF_BASE_URL = 'https://huggingface.co';
+/** `$OORT_HOME/models`. */
+export function modelsRoot(home) {
+    return path.join(home, 'models');
+}
+export function modelDir(home, id) {
+    return path.join(modelsRoot(home), id);
+}
+function readManifest(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, MANIFEST), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Cheap check (a manifest read and a stat per file, no hashing), safe on every hook. A full
+ * re-hash is `verifyModel`.
+ */
+export function modelState(home, spec) {
+    const dir = modelDir(home, spec.id);
+    if (!fs.existsSync(dir))
+        return 'missing';
+    const manifest = readManifest(dir);
+    if (manifest === undefined)
+        return 'incomplete';
+    const pinned = spec.files.every((f) => manifest.files.some((m) => m.name === f.name && m.sha256 === f.sha256 && m.bytes === f.bytes));
+    if (manifest.revision !== spec.source.revision || !pinned)
+        return 'outdated';
+    for (const f of spec.files) {
+        let size;
+        try {
+            size = fs.statSync(path.join(dir, f.name)).size;
+        }
+        catch {
+            return 'incomplete';
+        }
+        if (size !== f.bytes)
+            return 'incomplete';
+    }
+    return 'ready';
+}
+async function sha256Of(file) {
+    const hash = createHash('sha256');
+    for await (const chunk of fs.createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+/** Re-hashes every file of a pulled model; lists each file that does not match its pin. */
+export async function verifyModel(home, spec) {
+    const dir = modelDir(home, spec.id);
+    const bad = [];
+    for (const f of spec.files) {
+        const file = path.join(dir, f.name);
+        if (!fs.existsSync(file) || (await sha256Of(file)) !== f.sha256)
+            bad.push(f.name);
+    }
+    return { ok: bad.length === 0, bad };
+}
+/** A download that does not hash to its pin (or has the wrong size): nothing is kept. */
+export class ChecksumError extends Error {
+    model;
+    file;
+    constructor(model, file, detail) {
+        super(`${model}: ${file} failed verification (${detail}); nothing was kept`);
+        this.model = model;
+        this.file = file;
+        this.name = 'ChecksumError';
+    }
+}
+export function fileUrl(spec, f, baseUrl = HF_BASE_URL) {
+    const root = baseUrl.replace(/\/+$/, '');
+    return `${root}/${spec.source.repo}/resolve/${spec.source.revision}/${f.path}`;
+}
+async function download(spec, f, dest, opts) {
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const res = await doFetch(fileUrl(spec, f, opts.baseUrl), { redirect: 'follow' });
+    if (!res.ok || res.body === null) {
+        void res.body?.cancel().catch(() => undefined);
+        throw new Error(`${spec.id}: ${f.name} download failed (HTTP ${res.status})`);
+    }
+    const part = `${dest}.${process.pid}-${randomBytes(4).toString('hex')}.part`;
+    const hash = createHash('sha256');
+    let received = 0;
+    const fd = fs.openSync(part, 'wx', 0o600);
+    try {
+        try {
+            for await (const chunk of res.body) {
+                received += chunk.byteLength;
+                if (received > f.bytes) {
+                    throw new ChecksumError(spec.id, f.name, `more than the expected ${f.bytes} bytes`);
+                }
+                hash.update(chunk);
+                fs.writeSync(fd, chunk);
+                opts.onProgress?.({ file: f.name, received, total: f.bytes });
+            }
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (received !== f.bytes) {
+            throw new ChecksumError(spec.id, f.name, `${received} bytes, expected ${f.bytes}`);
+        }
+        const digest = hash.digest('hex');
+        if (digest !== f.sha256)
+            throw new ChecksumError(spec.id, f.name, 'SHA-256 mismatch');
+        fs.renameSync(part, dest);
+    }
+    catch (e) {
+        fs.rmSync(part, { force: true });
+        throw e;
+    }
+}
+/**
+ * Downloads every file of `spec` into `$OORT_HOME/models/<id>` (owner-only), verifying each
+ * against its pinned size and SHA-256 before it is moved into place, then writes the manifest.
+ * A file already present with the right hash is kept, so an interrupted pull resumes. On any
+ * failure the manifest is absent, so the model stays unusable rather than half-trusted.
+ * Returns the number of bytes downloaded.
+ */
+export async function pullModel(home, spec, opts = {}) {
+    const dir = modelDir(home, spec.id);
+    ensurePrivateDir(modelsRoot(home));
+    ensurePrivateDir(dir);
+    fs.rmSync(path.join(dir, MANIFEST), { force: true });
+    let downloaded = 0;
+    for (const f of spec.files) {
+        const dest = path.join(dir, f.name);
+        if (fs.existsSync(dest) &&
+            fs.statSync(dest).size === f.bytes &&
+            (await sha256Of(dest)) === f.sha256) {
+            continue;
+        }
+        fs.rmSync(dest, { force: true });
+        await download(spec, f, dest, opts);
+        downloaded += f.bytes;
+    }
+    const manifest = {
+        id: spec.id,
+        revision: spec.source.revision,
+        files: spec.files.map((f) => ({ name: f.name, bytes: f.bytes, sha256: f.sha256 })),
+        pulledAt: new Date().toISOString(),
+    };
+    writePrivateFile(path.join(dir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+    return downloaded;
+}
+/** Deletes a model's directory (files, manifest, optimised cache). True when it existed. */
+export function removeModel(home, id) {
+    if (id === '' || path.basename(id) !== id || id.startsWith('.')) {
+        throw new Error(`not a model id: ${JSON.stringify(id)}`);
+    }
+    const dir = modelDir(home, id);
+    if (!fs.existsSync(dir))
+        return false;
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+//# sourceMappingURL=files.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_EMBED_MODEL, DEFAULT_RERANK_MODEL, MODELS, downloadBytes, findModel, type EmbedModelSpec, type ModelFile, type ModelRole, type ModelSpec, type RerankModelSpec, } from './catalog.js';
+export { ChecksumError, HF_BASE_URL, MANIFEST, fileUrl, modelDir, modelState, modelsRoot, pullModel, removeModel, verifyModel, type ModelState, type PullOptions, } from './files.js';
+export { LocalModelError, readyModel, type LocalModelErrorKind } from './errors.js';
+export { localEmbedder, type LocalEmbedder, type LocalEmbedderOptions } from './embed.js';
+export { localReranker, type LocalReranker, type LocalRerankerOptions } from './rerank.js';
+export { defaultThreads, onnxRuntime, type Encoding, type Feed, type LoadedModel, type Output, type Runtime, type Session, type TextTokenizer, } from './runtime.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { DEFAULT_EMBED_MODEL, DEFAULT_RERANK_MODEL, MODELS, downloadBytes, findModel, } from './catalog.js';
+export { ChecksumError, HF_BASE_URL, MANIFEST, fileUrl, modelDir, modelState, modelsRoot, pullModel, removeModel, verifyModel, } from './files.js';
+export { LocalModelError, readyModel } from './errors.js';
+export { localEmbedder } from './embed.js';
+export { localReranker } from './rerank.js';
+export { defaultThreads, onnxRuntime, } from './runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/rerank.d.ts

@@ -0,0 +1,26 @@
+import type { Reranker } from '@oortmem/core';
+import { type RerankModelSpec } from './catalog.js';
+import { type Runtime } from './runtime.js';
+export interface LocalRerankerOptions {
+    /** `$OORT_HOME`; models live in `<home>/models/<id>`. */
+    home: string;
+    /** Catalog id, default `ms-marco-minilm-l6-v2`. */
+    model?: string;
+    /** Default: ONNX Runtime. */
+    runtime?: Runtime;
+    threads?: number;
+    /** Pairs per forward pass (default 16). */
+    batchSize?: number;
+    /** A model outside the catalog (tests, experiments); used when its id is `model`. */
+    spec?: RerankModelSpec;
+}
+export interface LocalReranker extends Reranker {
+    readonly model: string;
+    /** Loads the model now instead of on the first `rerank`. */
+    load(): Promise<void>;
+}
+/**
+ * A cross-encoder on this machine's CPU: each (query, document) pair is scored jointly, and the
+ * logit is mapped to 0..1 by the model's calibration. Loaded on the first `rerank`.
+ */
+export declare function localReranker(opts: LocalRerankerOptions): LocalReranker;

package/dist/rerank.js

@@ -0,0 +1,48 @@
+import { DEFAULT_RERANK_MODEL } from './catalog.js';
+import { clipChars, clipTokens, sigmoid, toBatch } from './encode.js';
+import { readyModel } from './errors.js';
+import { lazyLoad, onnxRuntime } from './runtime.js';
+/**
+ * A cross-encoder on this machine's CPU: each (query, document) pair is scored jointly, and the
+ * logit is mapped to 0..1 by the model's calibration. Loaded on the first `rerank`.
+ */
+export function localReranker(opts) {
+    const id = opts.model ?? DEFAULT_RERANK_MODEL;
+    const { spec: s, dir } = readyModel(opts.home, 'rerank', id, opts.spec);
+    const spec = s;
+    const load = lazyLoad(opts.runtime ?? onnxRuntime(), dir, opts.threads);
+    const batchSize = opts.batchSize ?? 16;
+    const { scale, shift } = spec.calibration;
+    return {
+        model: id,
+        async load() {
+            await load();
+        },
+        async rerank(query, docs, topK) {
+            if (docs.length === 0)
+                return [];
+            const m = await load();
+            const q = clipChars(query, spec.maxTokens / 4);
+            const scores = [];
+            for (let i = 0; i < docs.length; i += batchSize) {
+                const encodings = docs
+                    .slice(i, i + batchSize)
+                    .map((d) => clipTokens(m.tokenizer.encode(q, clipChars(d.text, spec.maxTokens)), spec.maxTokens));
+                const batch = toBatch(encodings, m.session.inputNames);
+                const out = (await m.session.run(batch.feeds, ['logits']))['logits'];
+                if (out === undefined || out.dims[0] !== encodings.length) {
+                    throw new Error(`local model ${id}: unexpected output shape`);
+                }
+                const per = out.dims[1] ?? 1;
+                for (let j = 0; j < encodings.length; j++) {
+                    scores.push(sigmoid(scale * out.data[j * per] + shift));
+                }
+            }
+            return docs
+                .map((d, i) => ({ id: d.id, score: scores[i] }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, Math.max(0, topK));
+        },
+    };
+}
+//# sourceMappingURL=rerank.js.map

package/dist/runtime.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The seam between Oort's pooling and scoring code and the inference runtime. The default is
+ * ONNX Runtime (onnxruntime-node) with Hugging Face's pure-JS tokenizers, both imported on
+ * first use only; tests inject a fake.
+ */
+export interface Feed {
+    type: 'int64' | 'float32';
+    data: BigInt64Array | Float32Array;
+    dims: number[];
+}
+export interface Output {
+    data: Float32Array;
+    dims: readonly number[];
+}
+export interface Session {
+    readonly inputNames: readonly string[];
+    run(feeds: Record<string, Feed>, outputs: readonly string[]): Promise<Record<string, Output>>;
+}
+export interface Encoding {
+    ids: number[];
+    token_type_ids?: number[];
+}
+export interface TextTokenizer {
+    /** Special tokens included; `pair` is the second segment of a cross-encoder input. */
+    encode(text: string, pair?: string): Encoding;
+}
+export interface LoadedModel {
+    session: Session;
+    tokenizer: TextTokenizer;
+}
+export interface Runtime {
+    /** Loads the model in `dir` (`model.onnx` plus tokenizer files), preferring the optimised cache. */
+    load(dir: string, opts?: {
+        threads?: number;
+    }): Promise<LoadedModel>;
+    /**
+     * Writes the optimised cache beside `model.onnx` (graph optimisations already applied, so a
+     * later load skips them: about 5x faster for the default models). Run once after a pull.
+     */
+    optimize?(dir: string): Promise<void>;
+}
+/** Intra-op threads: up to 4. Small batches gain little beyond that, and hooks share the CPU. */
+export declare function defaultThreads(): number;
+export declare function onnxRuntime(): Runtime;
+/**
+ * Loads `dir` on the first call and shares the result; a failed load is retried on the next
+ * call rather than remembered.
+ */
+export declare function lazyLoad(runtime: Runtime, dir: string, threads: number | undefined): () => Promise<LoadedModel>;

package/dist/runtime.js

@@ -0,0 +1,116 @@
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Intra-op threads: up to 4. Small batches gain little beyond that, and hooks share the CPU. */
+export function defaultThreads() {
+    return Math.max(1, Math.min(4, os.availableParallelism()));
+}
+/** The cache file name carries the runtime version: a runtime upgrade never loads a stale one. */
+function cacheFile(dir, ort) {
+    const v = ort.env.versions.node ?? ort.env.versions.common;
+    return path.join(dir, `model.ort-${v}.opt.onnx`);
+}
+async function loadTokenizer(dir) {
+    const { Tokenizer } = await import('@huggingface/tokenizers');
+    const read = (name) => JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+    const t = new Tokenizer(read('tokenizer.json'), read('tokenizer_config.json'));
+    return {
+        encode(text, pair) {
+            const e = t.encode(text, { text_pair: pair ?? null, return_token_type_ids: true });
+            return { ids: e.ids, token_type_ids: e.token_type_ids };
+        },
+    };
+}
+function wrap(ort, s) {
+    return {
+        inputNames: s.inputNames,
+        async run(feeds, outputs) {
+            const tensors = {};
+            for (const [name, f] of Object.entries(feeds)) {
+                tensors[name] = new ort.Tensor(f.type, f.data, f.dims);
+            }
+            const out = await s.run(tensors, outputs);
+            const result = {};
+            for (const name of outputs) {
+                const t = out[name];
+                if (t === undefined || !(t.data instanceof Float32Array)) {
+                    throw new Error(`local model: output ${name} is missing or not float32`);
+                }
+                result[name] = { data: t.data, dims: t.dims };
+            }
+            return result;
+        },
+    };
+}
+export function onnxRuntime() {
+    let ortP;
+    const ort = () => (ortP ??= import('onnxruntime-node'));
+    // Warnings (unused initialisers and the like) would land on a hook's stderr.
+    const quiet = { logSeverityLevel: 3 };
+    return {
+        async load(dir, opts = {}) {
+            const o = await ort();
+            const tokenizer = loadTokenizer(dir);
+            const threads = { intraOpNumThreads: opts.threads ?? defaultThreads(), interOpNumThreads: 1 };
+            const cached = cacheFile(dir, o);
+            let session;
+            if (fs.existsSync(cached)) {
+                try {
+                    session = await o.InferenceSession.create(cached, {
+                        ...quiet,
+                        ...threads,
+                        graphOptimizationLevel: 'disabled',
+                    });
+                }
+                catch {
+                    session = undefined; // a damaged cache: the original model still loads
+                }
+            }
+            session ??= await o.InferenceSession.create(path.join(dir, 'model.onnx'), {
+                ...quiet,
+                ...threads,
+                graphOptimizationLevel: 'all',
+            });
+            return { session: wrap(o, session), tokenizer: await tokenizer };
+        },
+        async optimize(dir) {
+            const o = await ort();
+            const dest = cacheFile(dir, o);
+            const tmp = `${dest}.${process.pid}-${randomBytes(4).toString('hex')}.tmp`;
+            try {
+                // `extended`, not `all`: the `all` level adds CPU-specific layout transforms.
+                const s = await o.InferenceSession.create(path.join(dir, 'model.onnx'), {
+                    ...quiet,
+                    graphOptimizationLevel: 'extended',
+                    optimizedModelFilePath: tmp,
+                });
+                await s.release();
+                fs.chmodSync(tmp, 0o600);
+                fs.renameSync(tmp, dest);
+            }
+            finally {
+                fs.rmSync(tmp, { force: true });
+            }
+        },
+    };
+}
+/**
+ * Loads `dir` on the first call and shares the result; a failed load is retried on the next
+ * call rather than remembered.
+ */
+export function lazyLoad(runtime, dir, threads) {
+    let loaded;
+    return () => {
+        if (loaded === undefined) {
+            const p = runtime.load(dir, threads === undefined ? {} : { threads });
+            p.catch(() => {
+                if (loaded === p)
+                    loaded = undefined;
+            });
+            loaded = p;
+        }
+        return loaded;
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@oortmem/local-models",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Oort embeddings and reranking on this machine's CPU (ONNX Runtime): no API keys, no account.",
+  "keywords": [
+    "oort",
+    "agent-memory",
+    "ai-agents",
+    "llm-memory",
+    "embeddings",
+    "reranker",
+    "onnx",
+    "offline"
+  ],
+  "homepage": "https://oortcloud.dev",
+  "bugs": {
+    "url": "https://github.com/oortmem/oort/issues",
+    "email": "hello@oortcloud.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oortmem/oort.git",
+    "directory": "packages/local-models"
+  },
+  "license": "Apache-2.0",
+  "author": "Oort <hello@oortcloud.dev>",
+  "type": "module",
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@huggingface/tokenizers": "0.2.0",
+    "@oortmem/core": "0.4.0",
+    "onnxruntime-node": "1.31.1"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
+  }
 }