bluera-knowledge 0.19.6 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.20.0](https://github.com/blueraai/bluera-knowledge/compare/v0.19.7...v0.20.0) (2026-02-01)
+
+
+### Features
+
+* **embeddings:** add query/document prefix support for asymmetric models ([51a1a38](https://github.com/blueraai/bluera-knowledge/commit/51a1a380368a3a077b01e799ab65ff449eed8a46))
+* **embeddings:** add state query and reset methods ([5275e28](https://github.com/blueraai/bluera-knowledge/commit/5275e283cdf4a72e21e44b08fc2075d4fee88aa7))
+* **hooks:** add async execution and improve BK usage reminders ([5576a9f](https://github.com/blueraai/bluera-knowledge/commit/5576a9fdd0d0e9a05193c2b700e600e6756736e4))
+
+
+### Bug Fixes
+
+* **gitignore:** correct pattern ordering for bluera-base ([f9b38c8](https://github.com/blueraai/bluera-knowledge/commit/f9b38c80ee4b4d84330fef43eef2f6f452b78a61))
+
+## [0.19.7](https://github.com/blueraai/bluera-knowledge/compare/v0.19.4...v0.19.7) (2026-01-31)
+
+
+### Features
+
+* **suggest:** present selectable list instead of copy-paste commands ([b8f3de2](https://github.com/blueraai/bluera-knowledge/commit/b8f3de2ab02dfa2dfa0d219bb3785c1491ae3d1a))
+
+
+### Bug Fixes
+
+* **embeddings:** improve reliability and performance ([d37c219](https://github.com/blueraai/bluera-knowledge/commit/d37c2190500f845c6bb7da78b432cf11b272b0f4))
+* **gitignore:** add logs directory to ignored patterns ([ec9faf4](https://github.com/blueraai/bluera-knowledge/commit/ec9faf482e8fc8ba1cbf6619a8c561eb51e35f3c))
+
 ## [0.19.6](https://github.com/blueraai/bluera-knowledge/compare/v0.19.4...v0.19.6) (2026-01-31)
 
 

package/dist/{chunk-JJYYK726.js → chunk-26MBEEKM.js}

@@ -2,7 +2,7 @@ import {
   createLogger,
   summarizePayload,
   truncateForLog
-} from "./chunk-T7MENUKF.js";
+} from "./chunk-PZE2MO7H.js";
 
 // src/crawl/intelligent-crawler.ts
 import { EventEmitter } from "events";
@@ -916,4 +916,4 @@ export {
   getCrawlStrategy,
   IntelligentCrawler
 };
-//# sourceMappingURL=chunk-JJYYK726.js.map
+//# sourceMappingURL=chunk-26MBEEKM.js.map

package/dist/{chunk-VR5EDQTX.js → chunk-OZIVRLZE.js}

@@ -9,7 +9,7 @@ import {
   isRepoStoreDefinition,
   isWebStoreDefinition,
   summarizePayload
-} from "./chunk-T7MENUKF.js";
+} from "./chunk-PZE2MO7H.js";
 
 // src/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -2202,4 +2202,4 @@ export {
   createMCPServer,
   runMCPServer
 };
-//# sourceMappingURL=chunk-VR5EDQTX.js.map
+//# sourceMappingURL=chunk-OZIVRLZE.js.map

package/dist/{chunk-T7MENUKF.js → chunk-PZE2MO7H.js}

@@ -2064,7 +2064,13 @@ var DEFAULT_CONFIG = {
   dataDir: ".bluera/bluera-knowledge/data",
   embedding: {
     model: "Xenova/all-MiniLM-L6-v2",
-    batchSize: 32
+    batchSize: 32,
+    dtype: "fp32",
+    pooling: "mean",
+    normalize: true,
+    queryPrefix: "",
+    docPrefix: "",
+    maxInFlightBatches: 1
   },
   indexing: {
     concurrency: 4,
@@ -3974,7 +3980,7 @@ var SearchService = class {
    * Returns results with raw cosine similarity scores [0-1].
    */
   async vectorSearchRaw(query, stores, limit) {
-    const queryVector = await this.embeddingEngine.embed(query);
+    const queryVector = await this.embeddingEngine.embedQuery(query);
     const results = [];
     for (const storeId of stores) {
       const hits = await this.lanceStore.search(storeId, queryVector, limit);
@@ -5418,23 +5424,71 @@ import { homedir as homedir2 } from "os";
 import { join as join11 } from "path";
 import { pipeline, env } from "@huggingface/transformers";
 env.cacheDir = join11(homedir2(), ".cache", "huggingface-transformers");
+var DEFAULT_EMBEDDING_CONFIG = {
+  model: "Xenova/all-MiniLM-L6-v2",
+  batchSize: 32,
+  dtype: "fp32",
+  pooling: "mean",
+  normalize: true,
+  queryPrefix: "",
+  docPrefix: "",
+  maxInFlightBatches: 1
+};
 var EmbeddingEngine = class {
   extractor = null;
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly -- mutated in embed()
+  initPromise = null;
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly -- mutated in embed() and embedBatch()
   _dimensions = null;
-  modelName;
-  batchSize;
-  constructor(modelName = "Xenova/all-MiniLM-L6-v2", batchSize = 32) {
-    this.modelName = modelName;
-    this.batchSize = batchSize;
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly -- mutated in dispose()
+  disposed = false;
+  config;
+  constructor(config = DEFAULT_EMBEDDING_CONFIG) {
+    this.config = config;
   }
+  /**
+   * Guard against use-after-dispose
+   */
+  assertNotDisposed() {
+    if (this.disposed) {
+      throw new Error("EmbeddingEngine has been disposed");
+    }
+  }
+  /**
+   * Initialize the embedding pipeline (concurrency-safe).
+   * Multiple concurrent calls will share the same initialization promise.
+   */
   async initialize() {
+    this.assertNotDisposed();
     if (this.extractor !== null) return;
-    this.extractor = await pipeline("feature-extraction", this.modelName, {
-      dtype: "fp32"
-    });
+    this.initPromise ??= (async () => {
+      try {
+        this.extractor = await pipeline("feature-extraction", this.config.model, {
+          dtype: this.config.dtype
+        });
+      } catch (error) {
+        this.initPromise = null;
+        throw error;
+      }
+    })();
+    await this.initPromise;
+  }
+  /**
+   * Embed a search query. Applies queryPrefix for asymmetric models.
+   */
+  async embedQuery(text) {
+    return this.embedText(this.config.queryPrefix + text);
   }
-  async embed(text) {
+  /**
+   * Embed a document for indexing. Applies docPrefix for asymmetric models.
+   */
+  async embedDocument(text) {
+    return this.embedText(this.config.docPrefix + text);
+  }
+  /**
+   * Internal: embed text without prefix.
+   */
+  async embedText(text) {
+    this.assertNotDisposed();
     if (this.extractor === null) {
       await this.initialize();
     }
@@ -5442,25 +5496,98 @@ var EmbeddingEngine = class {
       throw new Error("Failed to initialize embedding model");
     }
     const output = await this.extractor(text, {
-      pooling: "mean",
-      normalize: true
+      pooling: this.config.pooling,
+      normalize: this.config.normalize
     });
-    const result = Array.from(output.data);
-    this._dimensions ??= result.length;
-    return result.map((v) => Number(v));
+    const dim = output.dims[output.dims.length - 1] ?? 0;
+    this._dimensions ??= dim;
+    return Float32Array.from(output.data);
   }
+  /**
+   * Embed a batch of documents with optional parallelism.
+   * When maxInFlightBatches > 1, processes multiple batches concurrently.
+   */
   async embedBatch(texts) {
+    this.assertNotDisposed();
+    if (this.extractor === null) {
+      await this.initialize();
+    }
+    if (this.extractor === null) {
+      throw new Error("Failed to initialize embedding model");
+    }
+    const batches = [];
+    for (let i = 0; i < texts.length; i += this.config.batchSize) {
+      batches.push(texts.slice(i, i + this.config.batchSize));
+    }
+    if (batches.length === 0) {
+      return [];
+    }
+    if (this.config.maxInFlightBatches <= 1) {
+      return this.embedBatchesSequential(batches);
+    } else {
+      return this.embedBatchesConcurrent(batches);
+    }
+  }
+  /**
+   * Process batches sequentially (original behavior).
+   */
+  async embedBatchesSequential(batches) {
     const results = [];
-    for (let i = 0; i < texts.length; i += this.batchSize) {
-      const batch = texts.slice(i, i + this.batchSize);
-      const batchResults = await Promise.all(batch.map((text) => this.embed(text)));
+    for (let i = 0; i < batches.length; i++) {
+      const batch = batches[i];
+      if (batch === void 0) continue;
+      const batchResults = await this.processSingleBatch(batch);
       results.push(...batchResults);
-      if (i + this.batchSize < texts.length) {
-        await new Promise((resolve4) => setTimeout(resolve4, 100));
+      if (i < batches.length - 1) {
+        await new Promise((resolve4) => setImmediate(resolve4));
       }
     }
     return results;
   }
+  /**
+   * Process batches with controlled concurrency.
+   */
+  async embedBatchesConcurrent(batches) {
+    const results = new Array(batches.length);
+    let inFlight = 0;
+    const maxConcurrent = this.config.maxInFlightBatches;
+    await Promise.all(
+      batches.map(async (batch, idx) => {
+        while (inFlight >= maxConcurrent) {
+          await new Promise((resolve4) => setImmediate(resolve4));
+        }
+        inFlight++;
+        try {
+          results[idx] = await this.processSingleBatch(batch);
+        } finally {
+          inFlight--;
+        }
+      })
+    );
+    return results.flat();
+  }
+  /**
+   * Process a single batch and return embeddings.
+   */
+  async processSingleBatch(batch) {
+    if (this.extractor === null) {
+      throw new Error("Extractor not initialized");
+    }
+    const prefixedBatch = batch.map((text) => this.config.docPrefix + text);
+    const output = await this.extractor(prefixedBatch, {
+      pooling: this.config.pooling,
+      normalize: this.config.normalize
+    });
+    const dim = output.dims[output.dims.length - 1] ?? 0;
+    const batchResults = [];
+    for (let b = 0; b < batch.length; b++) {
+      const start = b * dim;
+      const end = start + dim;
+      batchResults.push(Float32Array.from(output.data.slice(start, end)));
+    }
+    this._dimensions ??= dim;
+    return batchResults;
+  }
   /**
    * Get cached embedding dimensions. Throws if embed() hasn't been called yet.
    * Use ensureDimensions() if you need to guarantee dimensions are available.
@@ -5471,13 +5598,38 @@ var EmbeddingEngine = class {
     }
     return this._dimensions;
   }
+  /**
+   * Check if the embedding pipeline is initialized.
+   */
+  isInitialized() {
+    return this.extractor !== null;
+  }
+  /**
+   * Check if this engine has been disposed.
+   */
+  isDisposed() {
+    return this.disposed;
+  }
+  /**
+   * Reset the engine to uninitialized state, allowing reuse after disposal.
+   * If currently initialized, disposes the pipeline first.
+   */
+  async reset() {
+    if (this.extractor !== null) {
+      await this.extractor.dispose();
+      this.extractor = null;
+    }
+    this.initPromise = null;
+    this._dimensions = null;
+    this.disposed = false;
+  }
   /**
    * Ensure dimensions are available, initializing the model if needed.
    * Returns the embedding dimensions for the current model.
    */
   async ensureDimensions() {
     if (this._dimensions === null) {
-      await this.embed("");
+      await this.embedText("dimension probe");
     }
     if (this._dimensions === null) {
       throw new Error("Failed to determine embedding dimensions");
@@ -5487,12 +5639,16 @@ var EmbeddingEngine = class {
   /**
    * Dispose the embedding pipeline to free resources.
    * Should be called before process exit to prevent ONNX runtime cleanup issues on macOS.
+   * After disposal, this engine cannot be used again.
    */
   async dispose() {
     if (this.extractor !== null) {
       await this.extractor.dispose();
       this.extractor = null;
     }
+    this.initPromise = null;
+    this._dimensions = null;
+    this.disposed = true;
   }
 };
 
@@ -5689,10 +5845,7 @@ var LazyServiceContainer = class {
   get embeddings() {
     if (this._embeddings === null) {
       logger4.debug("Lazy-initializing EmbeddingEngine");
-      this._embeddings = new EmbeddingEngine(
-        this.appConfig.embedding.model,
-        this.appConfig.embedding.batchSize
-      );
+      this._embeddings = new EmbeddingEngine(this.appConfig.embedding);
     }
     return this._embeddings;
   }
@@ -5795,7 +5948,7 @@ async function createServices(configPath, dataDir, projectRoot) {
   const pythonBridge = new PythonBridge();
   await pythonBridge.start();
   const lance = new LanceStore(resolvedDataDir);
-  const embeddings = new EmbeddingEngine(appConfig.embedding.model, appConfig.embedding.batchSize);
+  const embeddings = new EmbeddingEngine(appConfig.embedding);
   await embeddings.initialize();
   const resolvedProjectRoot = config.resolveProjectRoot();
   const definitionService = new StoreDefinitionService(resolvedProjectRoot);
@@ -5901,4 +6054,4 @@ export {
   createServices,
   destroyServices
 };
-//# sourceMappingURL=chunk-T7MENUKF.js.map
+//# sourceMappingURL=chunk-PZE2MO7H.js.map