akm-cli 0.10.261014-beta → 0.10.261016-beta

package/dist/llm/embedders/local.js

@@ -2,9 +2,9 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Local embedder: a BERT-family embedding model run with onnxruntime-node,
- * its text encoded by @huggingface/tokenizers, mean-pooled over the attention
- * mask and L2-normalised.
+ * Local embedder: a BERT-family embedding model run on onnxruntime-node's binding
+ * (`./onnx-runtime.ts`), its text encoded by @huggingface/tokenizers, mean-pooled
+ * over the attention mask and L2-normalised.
  *
  * Encapsulates the model's lifecycle as instance state on a `LocalEmbedder` so
  * tests can construct fresh instances without leaking loaded models across
@@ -13,8 +13,9 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { preloadOnnxRuntimeLibrary } from "../../standalone/onnxruntime-library.js";
+import { toErrorMessage } from "../../core/common.js";
 import { ensureLocalModelFiles } from "./local-model-files.js";
+import { hasLocalEmbeddings, loadOnnxRuntime, noLocalEmbeddingsReason, OnnxTensor } from "./onnx-runtime.js";
 /**
  * Default local model for embeddings.
  * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
@@ -24,10 +25,10 @@ export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
 /** The runtime the local embedder reports once its model has loaded. */
 export const LOCAL_EMBEDDING_RUNTIME = "onnxruntime-node";
 /**
- * The embedding runtime is not usable on this machine. `platform`: onnxruntime-node
- * has no native library for it, so keyword search is all there is. `load`: it has
- * one, which did not load (a missing package or addon, a `noexec` temp or cache
- * directory).
+ * The embedding runtime is not usable on this machine. `platform`: akm offers no
+ * local embeddings here, so keyword search and remote embeddings are what there
+ * is. `load`: it does, and the runtime could not be fetched or did not load (no
+ * network for the fetch, a `noexec` cache directory).
  */
 export class LocalRuntimeUnavailableError extends Error {
     kind;
@@ -55,50 +56,17 @@ const LOCAL_BATCH_SIZE = 32;
 function resolveLocalModelName(overrideModel) {
     return overrideModel || DEFAULT_LOCAL_MODEL;
 }
-/**
- * A standalone binary built for a target with no native library (`none`) must not
- * bundle the package: its addon for that platform does not exist. The bundler
- * drops only the branch a build constant rules out, so the import sits in an
- * `else`, not after the `throw`.
- */
-async function importOnnxRuntime() {
-    if (typeof AKM_STANDALONE_NATIVE_MODULE !== "undefined" && AKM_STANDALONE_NATIVE_MODULE === "./native/none") {
-        throw new Error("no native library is available for this platform");
-    }
-    else {
-        await preloadOnnxRuntimeLibrary();
-        return import("onnxruntime-node");
-    }
-}
-/**
- * Whether onnxruntime-node has a native library for this machine. A standalone
- * binary knows from its build (`none`). The package has one for glibc Linux
- * x64/arm64, Apple-silicon macOS and Windows x64/arm64, and none for musl Linux
- * or Intel macOS.
- */
-function hasNativeLibrary() {
-    if (typeof AKM_STANDALONE_NATIVE_MODULE !== "undefined")
-        return AKM_STANDALONE_NATIVE_MODULE !== "./native/none";
-    if (process.platform === "linux") {
-        const header = process.report?.getReport()?.header;
-        if (!header?.glibcVersionRuntime)
-            return false;
-    }
-    return ["linux-x64", "linux-arm64", "darwin-arm64", "win32-x64", "win32-arm64"].includes(`${process.platform}-${process.arch}`);
-}
-async function loadOnnxRuntime() {
+async function loadRuntime() {
+    if (!hasLocalEmbeddings())
+        throw new LocalRuntimeUnavailableError(noLocalEmbeddingsReason(), "platform");
     try {
-        return await importOnnxRuntime();
+        return await loadOnnxRuntime();
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        const kind = hasNativeLibrary() ? "load" : "platform";
-        // Only the package itself missing calls for a reinstall; a platform it ships no addon for (Intel macOS) fails on
-        // `../bin/napi-v6/<platform>/<arch>/onnxruntime_binding.node` and is reported below.
-        if (kind === "load" && /Cannot find (?:module|package) ['"]onnxruntime-node['"]/.test(msg)) {
-            throw new LocalRuntimeUnavailableError("Semantic search requires onnxruntime-node. Reinstall akm-cli.", kind);
-        }
-        throw new LocalRuntimeUnavailableError(`Failed to load the embedding runtime (onnxruntime-node): ${msg}. Semantic search with the local model is unavailable; keyword search still works.`, kind);
+        const msg = toErrorMessage(error).replace(/\.$/, "");
+        // A `noexec` mount maps nothing executable, so the binding cannot load from the cache there.
+        const mount = /failed to map segment/.test(msg) ? " akm's cache directory must allow executing files." : "";
+        throw new LocalRuntimeUnavailableError(`Failed to load the embedding runtime (onnxruntime-node): ${msg}.${mount} Semantic search with the local model is unavailable; keyword search still works.`, "load");
     }
 }
 /** The mean of one text's token vectors (padding excluded), scaled to unit length. */
@@ -116,17 +84,14 @@ function meanPooled(hidden, offset, tokens, dim) {
     return vector.map((value) => value / Math.sqrt(norm));
 }
 async function loadOnnxPipeline(modelName) {
-    const ort = await loadOnnxRuntime();
+    const ort = await loadRuntime();
     const { Tokenizer } = await import("@huggingface/tokenizers");
     const modelDir = await ensureLocalModelFiles(modelName);
     const readJson = (file) => JSON.parse(fs.readFileSync(path.join(modelDir, file), "utf8"));
     const tokenizerConfig = readJson("tokenizer_config.json");
     const tokenizer = new Tokenizer(readJson("tokenizer.json"), tokenizerConfig);
     const maxLength = typeof tokenizerConfig.model_max_length === "number" ? tokenizerConfig.model_max_length : Number.POSITIVE_INFINITY;
-    const session = await ort.InferenceSession.create(path.join(modelDir, "onnx", "model.onnx"), {
-        executionProviders: ["cpu"],
-        logSeverityLevel: 3,
-    });
+    const session = ort.createSession(path.join(modelDir, "onnx", "model.onnx"));
     return async (texts) => {
         // A text longer than the model's maximum is cut to it. Shorter ones are padded
         // to the longest in the batch; the mask keeps padding out of the pooling.
@@ -142,13 +107,13 @@ async function loadOnnxPipeline(modelName) {
         });
         const dims = [texts.length, length];
         const inputs = {
-            input_ids: new ort.Tensor("int64", ids, dims),
-            attention_mask: new ort.Tensor("int64", mask, dims),
-            token_type_ids: new ort.Tensor("int64", new BigInt64Array(texts.length * length), dims),
+            input_ids: new OnnxTensor("int64", ids, dims),
+            attention_mask: new OnnxTensor("int64", mask, dims),
+            token_type_ids: new OnnxTensor("int64", new BigInt64Array(texts.length * length), dims),
         };
         // Models that take fewer inputs (no token_type_ids) are fed only theirs.
         const feeds = Object.fromEntries(session.inputNames.flatMap((name) => (inputs[name] ? [[name, inputs[name]]] : [])));
-        const outputs = await session.run(feeds);
+        const outputs = session.run(feeds);
         const hidden = (outputs.last_hidden_state ?? outputs.token_embeddings ?? outputs.logits)?.data;
         const dim = hidden.length / (texts.length * length);
         return encoded.map((row, i) => meanPooled(hidden, i * length * dim, row.length, dim));

package/dist/llm/embedders/onnx-runtime.js

@@ -0,0 +1,121 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * ONNX Runtime for the local embedder: onnxruntime-node's N-API binding and the
+ * library it links, kept in akm's cache and loaded from there. `akm setup`
+ * fetches them when local embeddings are chosen, and the first local embedding
+ * fetches them when setup did not.
+ *
+ * akm does not depend on the onnxruntime-node package. Its JavaScript loads the
+ * binding from a path inside the package, which a compiled standalone binary can
+ * only satisfy by writing an embedded copy to the temp directory, and its install
+ * script downloads CUDA providers akm never uses. Here the binding is loaded by
+ * absolute path with the library beside it in the same folder, where the system
+ * loader finds it (`$ORIGIN` on Linux, `@loader_path` on macOS).
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { toErrorMessage } from "../../core/common.js";
+import { fetchNpmPackageFiles, NPM_REGISTRY } from "../../core/npm-package.js";
+import { getCacheDir } from "../../core/paths.js";
+import { info } from "../../core/warn.js";
+/**
+ * The onnxruntime-node release whose binding akm loads, and the only one it supports. akm calls the binding through
+ * the contract between that package's own JavaScript and its addon, which no release documents or promises and which
+ * moves between releases (after 1.24.3, `loadModel` returns a promise and `initOrtOnce` takes a third argument). What
+ * akm relies on: `initOrtOnce(logLevel, Tensor)`; `new InferenceSession()`; `loadModel(path, options)`;
+ * `inputMetadata` and `outputMetadata` (`{ name }[]`); `run(feeds, fetches)`, which reads a tensor as
+ * `{ type, data, dims, location }` and makes each result with `new Tensor(type, data, dims)`. To move it: change this
+ * version, check that contract in the new release's `lib/binding.ts` and `lib/backend.ts`, check the library names in
+ * {@link LIBRARIES}, and run the reference-vector test in `tests/integration/semantic-search-e2e.test.ts`, the gate for
+ * any bump.
+ */
+export const ONNXRUNTIME_VERSION = "1.24.3";
+/**
+ * The platforms akm offers local embeddings on, each with the library the binding links there. Every other platform
+ * has keyword search and remote embeddings. A platform is listed once a real run has verified it; Linux means glibc.
+ */
+const LIBRARIES = {
+    "linux-x64": "libonnxruntime.so.1",
+    "darwin-arm64": `libonnxruntime.${ONNXRUNTIME_VERSION}.dylib`,
+};
+const BINDING = "onnxruntime_binding.node";
+/** This machine as `<platform>-<arch>`, Linux without glibc as `linux-musl-<arch>`. */
+function thisPlatform() {
+    const header = process.report?.getReport()?.header;
+    const musl = process.platform === "linux" && !header?.glibcVersionRuntime;
+    return `${process.platform}${musl ? "-musl" : ""}-${process.arch}`;
+}
+/** Whether akm offers local embeddings on this machine. */
+export function hasLocalEmbeddings() {
+    return thisPlatform() in LIBRARIES;
+}
+/** What a machine without local embeddings is told, wherever it is told. */
+export function noLocalEmbeddingsReason() {
+    return `Local embeddings are not available on ${thisPlatform()}; choose a remote endpoint or keyword search.`;
+}
+/** A tensor as the binding reads one and makes its results. */
+export class OnnxTensor {
+    type;
+    data;
+    dims;
+    location = "cpu";
+    constructor(type, data, dims) {
+        this.type = type;
+        this.data = data;
+        this.dims = dims;
+    }
+}
+/** Fetch the binding and its library into `directory`, naming the package, its URL and the folder when it cannot. */
+async function fetchOnnxRuntime(directory) {
+    const library = LIBRARIES[thisPlatform()];
+    if (!library)
+        throw new Error(noLocalEmbeddingsReason());
+    const source = `bin/napi-v6/${process.platform}/${process.arch}`;
+    try {
+        info(`Fetching ONNX Runtime ${ONNXRUNTIME_VERSION} for local embeddings (about 86 MB, once) into ${directory}.`);
+        // The library first: a binding in the folder means its library is there too.
+        await fetchNpmPackageFiles("onnxruntime-node", ONNXRUNTIME_VERSION, directory, [
+            { member: `package/${source}/${library}`, file: library },
+            { member: `package/${source}/${BINDING}`, file: BINDING },
+        ]);
+        return directory;
+    }
+    catch (error) {
+        throw new Error(`Could not fetch ONNX Runtime ${ONNXRUNTIME_VERSION} for local embeddings: package onnxruntime-node from ${NPM_REGISTRY}/onnxruntime-node/${ONNXRUNTIME_VERSION} into ${directory}: ${toErrorMessage(error)}. ` +
+            `Run \`akm setup --yes\` with network access, or copy ${BINDING} and ${library} from that package's ${source}/ into that folder.`);
+    }
+}
+/**
+ * The binding, loaded and initialised from `<cache>/onnxruntime/<version>-<platform>-<arch>/`, where it and its library
+ * are fetched first when the binding is not there.
+ */
+async function loadBinding() {
+    const directory = path.join(getCacheDir(), "onnxruntime", `${ONNXRUNTIME_VERSION}-${thisPlatform()}`);
+    if (!fs.existsSync(path.join(directory, BINDING)))
+        await fetchOnnxRuntime(directory);
+    const loaded = createRequire(import.meta.url)(path.join(directory, BINDING));
+    // 3: errors only.
+    loaded.initOrtOnce(3, OnnxTensor);
+    return loaded;
+}
+/** Once per process, however many callers ask meanwhile; a failure is not kept, so the next caller tries again. */
+let loading;
+/** The runtime, ready to load models: fetched first when it is not in the cache, then loaded. */
+export async function loadOnnxRuntime() {
+    loading ??= loadBinding().catch((error) => {
+        loading = undefined;
+        throw error;
+    });
+    const loaded = await loading;
+    return {
+        createSession(modelPath) {
+            const session = new loaded.InferenceSession();
+            session.loadModel(modelPath, { executionProviders: ["cpu"], logSeverityLevel: 3 });
+            const outputs = Object.fromEntries(session.outputMetadata.map(({ name }) => [name, null]));
+            return { inputNames: session.inputMetadata.map(({ name }) => name), run: (feeds) => session.run(feeds, outputs) };
+        },
+    };
+}

package/dist/output/renderers.js

@@ -217,8 +217,8 @@ const agentMdRenderer = {
     },
 };
 // ── 4. knowledge-md ──────────────────────────────────────────────────────────
-const KNOWLEDGE_ACTION = "Reference material - read the content below. For a large document, read one section with `akm show <ref>#fragment` " +
-    "(an unmatched #fragment lists the available slugs).";
+const KNOWLEDGE_ACTION = "Reference material - read the content below. For a large document, run `akm show <ref> --detail brief` for its " +
+    "outline (`toc`, no body), then `akm show <ref>#<slug>` for only the sections you need.";
 const knowledgeMdRenderer = {
     name: "knowledge-md",
     buildShowResponse(ctx) {

package/dist/output/shapes/helpers.js

@@ -348,6 +348,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "editHint",
             "description",
             "action",
+            "toc",
             "content",
             "template",
             "prompt",
@@ -381,6 +382,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "action",
         "description",
         "tags",
+        "toc",
         "content",
         "template",
         "prompt",

package/dist/output/text/show-format.js

@@ -59,6 +59,13 @@ export function formatShowPlain(r, detail) {
         if (r.schemaVersion !== undefined)
             lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
     }
+    if (Array.isArray(r.toc) && r.toc.length > 0) {
+        lines.push("");
+        lines.push("toc:");
+        for (const heading of r.toc) {
+            lines.push(`  ${"#".repeat(heading.level)} ${heading.text} (#${heading.slug}, line ${heading.startLine})`);
+        }
+    }
     const links = typeof r.links === "object" && r.links !== null ? r.links : undefined;
     if (links) {
         lines.push("");

package/dist/registry/semver.js

@@ -41,6 +41,18 @@ export function isSemverRange(input) {
 export function maxSatisfying(versions, range) {
     return semver.maxSatisfying(versions, range) ?? undefined;
 }
+/**
+ * Highest of `versions` in semver order, prereleases included (`0.10.1-beta` sorts above `0.9.30`). Invalid entries
+ * are ignored; `undefined` when none is valid. Use this to order known versions, not `maxSatisfying(versions, "*")`,
+ * which skips every prerelease.
+ */
+export function highestVersion(versions) {
+    return semver.rsort(versions.filter((version) => semver.valid(version) !== null))[0];
+}
+/** True when `version` is a valid semver prerelease (`1.2.3-beta`). */
+export function isPrerelease(version) {
+    return semver.valid(version) !== null && semver.prerelease(version) !== null;
+}
 /** True when `version` satisfies `range` (both real semver forms). False for an invalid version or range. */
 export function satisfiesRange(version, range) {
     return semver.satisfies(version, range);