akm-cli 0.5.0 → 0.6.0-rc1

package/dist/embedder.js

@@ -1,184 +1,41 @@
-import path from "node:path";
-import { fetchWithTimeout, isHttpUrl } from "./common";
-import { getCacheDir } from "./paths";
-import { warn } from "./warn";
-// ── Default local model ─────────────────────────────────────────────────────
 /**
- * Default local transformer model for embeddings.
- * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
- * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
+ * Backward-compatible facade for the embedder module.
+ *
+ * The implementation has been split into:
+ * - `./embedders/types`  — `EmbeddingVector`, `Embedder`, `EmbeddingCheckResult`
+ * - `./embedders/local`  — `LocalEmbedder`, `DEFAULT_LOCAL_MODEL`,
+ *                          `isTransformersAvailable`
+ * - `./embedders/remote` — `RemoteEmbedder`, `hasRemoteEndpoint`
+ * - `./embedders/cache`  — LRU `embedCache`, `clearEmbeddingCache`,
+ *                          `embedCacheKey`
+ *
+ * This module wires them together: it picks the right implementation from the
+ * (optional) embedding config, applies the cache layer, and re-exports the
+ * existing public API so call sites (`db-search.ts`, `indexer.ts`, `db.ts`,
+ * `setup.ts`, `semantic-status.ts`, tests) keep working unmodified.
+ *
+ * Tests can construct fresh `LocalEmbedder` / `RemoteEmbedder` instances
+ * directly from their submodules to avoid module-level state pollution.
  */
-export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache";
+import { isTransformersAvailable, LocalEmbedder } from "./embedders/local";
+import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote";
+// ── Re-exports (public API) ─────────────────────────────────────────────────
+export { clearEmbeddingCache } from "./embedders/cache";
+export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local";
+// ── Singleton local embedder ────────────────────────────────────────────────
+// `localEmbedder` is an intentional module-level singleton. The underlying
+// @huggingface/transformers pipeline is expensive to initialise (model download
+// + WASM compilation) and is safe to share across calls because it is
+// stateless once created. Storing it here avoids re-initialising on every
+// embed() call.
+const localEmbedder = new LocalEmbedder();
 /**
- * Return the local model name that will be used for embedding.
- * When `overrideModel` is provided it takes precedence; otherwise
- * the default model is returned.
+ * Reset the cached local embedder pipeline. Used by tests that want a fresh
+ * pipeline construction (e.g. to assert the dtype-fallback retry logic).
  */
-function getLocalModelName(overrideModel) {
-    return overrideModel || DEFAULT_LOCAL_MODEL;
-}
-const LOCAL_EMBEDDER_DTYPE = "fp32";
-const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
-// Cache the promise itself (not the resolved result) so concurrent calls share
-// the same initialisation work and never download the model twice.
-// The cache is keyed by model name so switching models gets a fresh pipeline.
-let localEmbedderPromise;
-let localEmbedderModelName;
-async function getLocalEmbedder(modelName) {
-    const resolvedModel = getLocalModelName(modelName);
-    // If the cached pipeline was created for a different model, discard it.
-    if (localEmbedderPromise && localEmbedderModelName !== resolvedModel) {
-        localEmbedderPromise = undefined;
-        localEmbedderModelName = undefined;
-    }
-    if (!localEmbedderPromise) {
-        localEmbedderModelName = resolvedModel;
-        localEmbedderPromise = (async () => {
-            // Ensure HuggingFace model cache lives in a stable location outside
-            // node_modules so it survives package reinstalls.
-            if (!process.env.HF_HOME) {
-                process.env.HF_HOME = path.join(getCacheDir(), "models");
-            }
-            let pipeline;
-            try {
-                const mod = await import("@huggingface/transformers");
-                pipeline = mod.pipeline;
-            }
-            catch (importError) {
-                const msg = importError instanceof Error ? importError.message : String(importError);
-                if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
-                    throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
-                }
-                throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
-            }
-            const pipelineFn = pipeline;
-            return createLocalPipeline(pipelineFn, resolvedModel);
-        })();
-        // HI-13: Clear the cached promise on failure so the next call retries
-        // instead of permanently rejecting every subsequent call with the same error.
-        localEmbedderPromise.catch(() => {
-            localEmbedderPromise = undefined;
-            localEmbedderModelName = undefined;
-        });
-    }
-    return localEmbedderPromise;
-}
-async function createLocalPipeline(pipelineFn, modelName) {
-    try {
-        return await pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_DTYPE });
-    }
-    catch (error) {
-        if (!shouldRetryWithoutExplicitDtype(error)) {
-            throw error;
-        }
-        warn('Local embedding model "%s" rejected explicit dtype "%s"; retrying with explicit fallback dtype "%s".', modelName, LOCAL_EMBEDDER_DTYPE, LOCAL_EMBEDDER_FALLBACK_DTYPE);
-        return pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_FALLBACK_DTYPE });
-    }
-}
-function shouldRetryWithoutExplicitDtype(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return /dtype|fp32|precision|quant/i.test(message);
-}
 export function resetLocalEmbedder() {
-    localEmbedderPromise = undefined;
-    localEmbedderModelName = undefined;
-}
-async function embedLocal(text, modelName) {
-    const model = await getLocalEmbedder(modelName);
-    const result = await model(text, { pooling: "mean", normalize: true });
-    return Array.from(result.data);
-}
-// ── Vector normalization ─────────────────────────────────────────────────────
-/**
- * L2-normalize a vector to unit length.
- * Required for remote embeddings because the scoring pipeline's L2-to-cosine
- * conversion formula (1 - distance^2/2) is only correct for unit vectors.
- * The local embedder already normalizes via `normalize: true`.
- */
-function l2Normalize(vec) {
-    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
-    if (norm === 0)
-        return vec;
-    return vec.map((v) => v / norm);
-}
-// ── OpenAI-compatible remote embedder ───────────────────────────────────────
-function normalizeEmbeddingEndpoint(endpoint) {
-    let parsed;
-    try {
-        parsed = new URL(endpoint);
-    }
-    catch {
-        return endpoint;
-    }
-    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
-    if (normalizedPath.endsWith("/embeddings")) {
-        return parsed.toString();
-    }
-    parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
-    return parsed.toString();
-}
-function embeddingEndpointPathHint(endpoint) {
-    const normalizedEndpoint = normalizeEmbeddingEndpoint(endpoint);
-    if (normalizedEndpoint !== endpoint) {
-        return ` Check that your endpoint includes the full embeddings path (for example "${normalizedEndpoint}", not just "${endpoint}").`;
-    }
-    return "";
-}
-async function embedRemote(text, config) {
-    const headers = { "Content-Type": "application/json" };
-    if (config.apiKey) {
-        headers.Authorization = `Bearer ${config.apiKey}`;
-    }
-    const body = {
-        input: text,
-        model: config.model,
-    };
-    if (config.dimension) {
-        body.dimensions = config.dimension;
-    }
-    const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-    });
-    if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        throw new Error(`Embedding request failed (${response.status}): ${body}`);
-    }
-    const json = (await response.json());
-    if (!json.data?.[0]?.embedding) {
-        throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(config.endpoint)}`);
-    }
-    return l2Normalize(json.data[0].embedding);
-}
-// ── Helpers ──────────────────────────────────────────────────────────────────
-/** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
-function hasRemoteEndpoint(config) {
-    return isHttpUrl(config.endpoint);
-}
-// ── LRU embedding cache ─────────────────────────────────────────────────────
-// Caches query embeddings to avoid redundant computation for repeated queries.
-// Uses a simple Map with LRU eviction (delete + re-insert to move to end).
-const EMBED_CACHE_MAX = 100;
-const embedCache = new Map();
-/**
- * Build a cache key from query text and optional config.
- * Different endpoints/models should not share cached embeddings.
- * apiKey deliberately excluded: same endpoint+model produce identical embeddings regardless of auth
- */
-function embedCacheKey(text, config) {
-    if (!config)
-        return `local::${text}`;
-    const endpoint = config.endpoint || "";
-    const model = config.model || config.localModel || "";
-    return `${endpoint}:${model}:${text}`;
-}
-/**
- * Clear the embedding cache. Call when the embedding model changes
- * or when you want to force fresh embeddings.
- */
-export function clearEmbeddingCache() {
-    embedCache.clear();
+    localEmbedder.reset();
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
@@ -192,129 +49,48 @@ export function clearEmbeddingCache() {
  */
 export async function embed(text, embeddingConfig) {
     const key = embedCacheKey(text, embeddingConfig);
-    // Check cache first
-    const cached = embedCache.get(key);
-    if (cached) {
-        // Move to end (most recently used) for LRU ordering
-        embedCache.delete(key);
-        embedCache.set(key, cached);
+    const cached = getCachedEmbedding(key);
+    if (cached)
         return cached;
-    }
-    // Compute the embedding
     const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
-        ? await embedRemote(text, embeddingConfig)
-        : await embedLocal(text, embeddingConfig?.localModel);
-    // Evict oldest entry if at capacity
-    if (embedCache.size >= EMBED_CACHE_MAX) {
-        const oldest = embedCache.keys().next().value;
-        if (oldest !== undefined) {
-            embedCache.delete(oldest);
-        }
-    }
-    embedCache.set(key, result);
+        ? await new RemoteEmbedder(embeddingConfig).embed(text)
+        : await localEmbedder.embedWithModel(text, embeddingConfig?.localModel);
+    setCachedEmbedding(key, result);
     return result;
 }
-// ── Batch embedding ─────────────────────────────────────────────────────────
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for local transformer pipeline.
+ * Falls back to sequential embedding for the local transformer pipeline.
  */
 export async function embedBatch(texts, embeddingConfig) {
     if (texts.length === 0)
         return [];
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
-        return embedRemoteBatch(texts, embeddingConfig);
+        return new RemoteEmbedder(embeddingConfig).embedBatch(texts);
     }
     // Local transformer: process sequentially (pipeline handles one at a time)
     const localModel = embeddingConfig?.localModel;
     const results = [];
     for (const text of texts) {
-        results.push(await embedLocal(text, localModel));
-    }
-    return results;
-}
-async function embedRemoteBatch(texts, config) {
-    const BATCH_SIZE = 100;
-    const results = [];
-    const headers = { "Content-Type": "application/json" };
-    if (config.apiKey) {
-        headers.Authorization = `Bearer ${config.apiKey}`;
-    }
-    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
-        const batch = texts.slice(i, i + BATCH_SIZE);
-        const body = {
-            input: batch,
-            model: config.model,
-        };
-        if (config.dimension) {
-            body.dimensions = config.dimension;
-        }
-        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
-            method: "POST",
-            headers,
-            body: JSON.stringify(body),
-        });
-        if (!response.ok) {
-            const respBody = await response.text().catch(() => "");
-            throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
-        }
-        const json = (await response.json());
-        if (!json.data || json.data.length !== batch.length) {
-            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(config.endpoint)}`);
-        }
-        // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
-        const sorted = [...json.data].sort((a, b) => a.index - b.index);
-        for (const [idx, d] of sorted.entries()) {
-            if (!Array.isArray(d.embedding)) {
-                throw new Error(`Unexpected embedding at batch index ${idx}: missing or invalid`);
-            }
-            results.push(l2Normalize(d.embedding));
-        }
+        results.push(await localEmbedder.embedWithModel(text, localModel));
     }
     return results;
 }
 // ── Similarity ──────────────────────────────────────────────────────────────
-export function cosineSimilarity(a, b) {
-    if (a.length !== b.length) {
-        // MD-4: Return 0 on dimension mismatch rather than silently computing on a
-        // truncated view, which would produce meaningless similarity scores.
-        warn("cosineSimilarity: vector dimension mismatch (%d vs %d) — re-index recommended", a.length, b.length);
-        return 0;
-    }
-    const len = a.length;
-    if (len === 0)
-        return 0;
-    let dot = 0, magA = 0, magB = 0;
-    for (let i = 0; i < len; i++) {
-        dot += a[i] * b[i];
-        magA += a[i] * a[i];
-        magB += b[i] * b[i];
-    }
-    const denom = Math.sqrt(magA) * Math.sqrt(magB);
-    return denom === 0 ? 0 : dot / denom;
-}
+// `cosineSimilarity` was moved to `./embedders/types.ts` so importers
+// (notably `db.ts`) can pull the math function without dragging in this
+// facade and its `@huggingface/transformers` import chain. Re-export
+// preserves the existing public API.
+export { cosineSimilarity } from "./embedders/types";
 // ── Availability check ──────────────────────────────────────────────────────
-/**
- * Check whether the `@huggingface/transformers` package can be imported.
- * Returns `true` if it can, `false` otherwise.
- */
-export async function isTransformersAvailable() {
-    try {
-        await import("@huggingface/transformers");
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         try {
-            await embedRemote("test", embeddingConfig);
+            await new RemoteEmbedder(embeddingConfig).embed("test");
             return { available: true };
         }
         catch (err) {
@@ -326,7 +102,7 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
         }
     }
     // Check if the package is importable before attempting the model download.
-    if (!(await isTransformersAvailable())) {
+    if (!isTransformersAvailable()) {
         return {
             available: false,
             reason: "missing-package",
@@ -334,7 +110,7 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
         };
     }
     try {
-        await getLocalEmbedder(embeddingConfig?.localModel);
+        await localEmbedder.getPipeline(embeddingConfig?.localModel);
         return { available: true };
     }
     catch (err) {

package/dist/embedders/cache.js

@@ -0,0 +1,47 @@
+/**
+ * LRU embedding cache shared by the embedder facade.
+ *
+ * Caches query embeddings to avoid redundant computation for repeated
+ * queries. Uses a simple Map with LRU eviction (delete + re-insert to move
+ * an entry to the most-recently-used end).
+ */
+const EMBED_CACHE_MAX = 100;
+const embedCache = new Map();
+/**
+ * Build a cache key from query text and optional config.
+ * Different endpoints/models should not share cached embeddings.
+ * apiKey deliberately excluded: same endpoint+model produce identical embeddings regardless of auth.
+ */
+export function embedCacheKey(text, config) {
+    if (!config)
+        return `local::${text}`;
+    const endpoint = config.endpoint || "";
+    const model = config.model || config.localModel || "";
+    return `${endpoint}:${model}:${text}`;
+}
+export function getCachedEmbedding(key) {
+    const cached = embedCache.get(key);
+    if (cached === undefined)
+        return undefined;
+    // Move to end (most recently used) for LRU ordering
+    embedCache.delete(key);
+    embedCache.set(key, cached);
+    return cached;
+}
+export function setCachedEmbedding(key, value) {
+    // Evict oldest entry if at capacity
+    if (embedCache.size >= EMBED_CACHE_MAX) {
+        const oldest = embedCache.keys().next().value;
+        if (oldest !== undefined) {
+            embedCache.delete(oldest);
+        }
+    }
+    embedCache.set(key, value);
+}
+/**
+ * Clear the embedding cache. Call when the embedding model changes
+ * or when you want to force fresh embeddings.
+ */
+export function clearEmbeddingCache() {
+    embedCache.clear();
+}

package/dist/embedders/local.js

@@ -0,0 +1,152 @@
+/**
+ * Local @huggingface/transformers embedder.
+ *
+ * Encapsulates the transformer pipeline lifecycle as instance state on a
+ * `LocalEmbedder` so tests can construct fresh instances without leaking
+ * pipelines across tests. The facade in `../embedder.ts` keeps a single
+ * shared instance for the production code path.
+ */
+import path from "node:path";
+import { getCacheDir } from "../paths";
+import { warn } from "../warn";
+/**
+ * Default local transformer model for embeddings.
+ * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
+ * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
+ */
+export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+const LOCAL_EMBEDDER_DTYPE = "fp32";
+const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Return the local model name that will be used for embedding.
+ * When `overrideModel` is provided it takes precedence; otherwise
+ * the default model is returned.
+ */
+function resolveLocalModelName(overrideModel) {
+    return overrideModel || DEFAULT_LOCAL_MODEL;
+}
+export class LocalEmbedder {
+    defaultModel;
+    /**
+     * Cache the *promise* (not the resolved result) so concurrent calls share
+     * the same initialisation work and never download the model twice. Keyed
+     * by model name so switching models gets a fresh pipeline.
+     */
+    pipelinePromise;
+    pipelineModelName;
+    constructor(defaultModel) {
+        this.defaultModel = defaultModel;
+    }
+    /** Reset the cached pipeline (used by tests and by `resetLocalEmbedder()`). */
+    reset() {
+        this.pipelinePromise = undefined;
+        this.pipelineModelName = undefined;
+    }
+    async embed(text) {
+        return this.embedWithModel(text, this.defaultModel);
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.embedWithModel(text, this.defaultModel));
+        }
+        return results;
+    }
+    /** Embed using a model name override (used by the facade for per-call model overrides). */
+    async embedWithModel(text, modelName) {
+        const pipeline = await this.getPipeline(modelName);
+        const result = await pipeline(text, { pooling: "mean", normalize: true });
+        return Array.from(result.data);
+    }
+    /**
+     * Eagerly load (or return the cached) underlying pipeline. Used by
+     * availability checks that want to surface model-download failures
+     * without performing a real embed call.
+     */
+    async getPipeline(modelName) {
+        const resolvedModel = resolveLocalModelName(modelName);
+        if (this.pipelinePromise && this.pipelineModelName !== resolvedModel) {
+            this.pipelinePromise = undefined;
+            this.pipelineModelName = undefined;
+        }
+        if (!this.pipelinePromise) {
+            this.pipelineModelName = resolvedModel;
+            this.pipelinePromise = (async () => {
+                // Ensure HuggingFace model cache lives in a stable location outside
+                // node_modules so it survives package reinstalls.
+                if (!process.env.HF_HOME) {
+                    process.env.HF_HOME = path.join(getCacheDir(), "models");
+                }
+                let pipeline;
+                try {
+                    const mod = await import("@huggingface/transformers");
+                    pipeline = mod.pipeline;
+                }
+                catch (importError) {
+                    const msg = importError instanceof Error ? importError.message : String(importError);
+                    if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
+                        throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
+                    }
+                    throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
+                }
+                const pipelineFn = pipeline;
+                return createLocalPipeline(pipelineFn, resolvedModel);
+            })();
+            // HI-13: Clear the cached promise on failure so the next call retries
+            // instead of permanently rejecting every subsequent call with the same error.
+            this.pipelinePromise.catch(() => {
+                this.pipelinePromise = undefined;
+                this.pipelineModelName = undefined;
+            });
+        }
+        return this.pipelinePromise;
+    }
+}
+async function createLocalPipeline(pipelineFn, modelName) {
+    try {
+        return await pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_DTYPE });
+    }
+    catch (error) {
+        if (!shouldRetryWithoutExplicitDtype(error)) {
+            throw error;
+        }
+        warn('Local embedding model "%s" rejected explicit dtype "%s"; retrying with explicit fallback dtype "%s".', modelName, LOCAL_EMBEDDER_DTYPE, LOCAL_EMBEDDER_FALLBACK_DTYPE);
+        return pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_FALLBACK_DTYPE });
+    }
+}
+function shouldRetryWithoutExplicitDtype(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /dtype|fp32|precision|quant/i.test(message);
+}
+/**
+ * Check whether the `@huggingface/transformers` package can be resolved.
+ * Uses `Bun.resolveSync` so we never load the module (which would trigger
+ * heavy WASM/model side-effects) just to test availability.
+ *
+ * Falls back to `require.resolve` when `Bun.resolveSync` is unavailable
+ * (e.g. running under Node), so the function still works in mixed runtimes.
+ */
+export function isTransformersAvailable() {
+    try {
+        if (typeof Bun !== "undefined" && typeof Bun.resolveSync === "function") {
+            Bun.resolveSync("@huggingface/transformers", import.meta.dir);
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    try {
+        const req = globalThis.require;
+        if (req && typeof req.resolve === "function") {
+            req.resolve("@huggingface/transformers");
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}