@framers/agentos 0.1.120 → 0.1.121

package/dist/rag/migration/types.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Types for the universal vector store migration engine.
+ * @module rag/migration/types
+ *
+ * Defines the interfaces for streaming data between any pair of
+ * vector store backends (SQLite, Postgres, Qdrant). The migration
+ * engine reads batches from an IMigrationSource and writes them
+ * to an IMigrationTarget, never loading the entire dataset into memory.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rag/migration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rag/migration/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/rag/multimodal/MultimodalIndexer.d.ts

@@ -39,6 +39,7 @@ import type { IEmbeddingManager } from '../IEmbeddingManager.js';
 import type { IVectorStore } from '../IVectorStore.js';
 import type { ImageIndexOptions, ImageIndexResult, AudioIndexOptions, AudioIndexResult, MultimodalSearchOptions, MultimodalSearchResult, IVisionProvider, ISpeechToTextProvider, MultimodalIndexerConfig } from './types.js';
 import type { VisionPipeline } from '../../core/vision/VisionPipeline.js';
+import type { HydeRetriever } from '../HydeRetriever.js';
 /**
  * Indexes non-text content (images, audio) into the vector store by
  * generating text descriptions and embeddings.
@@ -103,6 +104,16 @@ export declare class MultimodalIndexer {
     private readonly _sttProvider?;
     /** Resolved configuration. */
     private readonly _config;
+    /**
+     * Optional HyDE retriever for hypothesis-driven multimodal search.
+     *
+     * When set, the `search()` method can accept `hyde: { enabled: true }`
+     * in its options to embed a hypothetical answer instead of the raw query,
+     * improving recall for exploratory or vague queries.
+     *
+     * @see HydeRetriever
+     */
+    private _hydeRetriever?;
     /**
      * Create a new multimodal indexer.
      *
@@ -146,6 +157,30 @@ export declare class MultimodalIndexer {
         sttProvider?: ISpeechToTextProvider;
         config?: MultimodalIndexerConfig;
     });
+    /**
+     * Attach a HyDE retriever to enable hypothesis-driven multimodal search.
+     *
+     * Once set, pass `hyde: { enabled: true }` in the `search()` options to
+     * activate HyDE for that query. The retriever generates a hypothetical
+     * answer using an LLM, then embeds that answer instead of the raw query
+     * text, which typically yields better recall for exploratory queries.
+     *
+     * @param retriever - A pre-configured HydeRetriever instance.
+     *
+     * @example
+     * ```typescript
+     * indexer.setHydeRetriever(new HydeRetriever({
+     *   llmCaller: myLlmCaller,
+     *   embeddingManager: myEmbeddingManager,
+     *   config: { enabled: true },
+     * }));
+     *
+     * const results = await indexer.search('cats on a beach', {
+     *   hyde: { enabled: true },
+     * });
+     * ```
+     */
+    setHydeRetriever(retriever: HydeRetriever): void;
     /**
      * Index an image by generating a text description via vision LLM,
      * then embedding and storing the description.

package/dist/rag/multimodal/MultimodalIndexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MultimodalIndexer.d.ts","sourceRoot":"","sources":["../../../src/rag/multimodal/MultimodalIndexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,yBAAyB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAiC,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAEV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAuB1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,iBAAiB;IAK5B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;IAEtD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IAEnD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAwB;IAEtD,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAM5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;gBACS,IAAI,EAAE;QAChB,gBAAgB,EAAE,iBAAiB,CAAC;QACpC,WAAW,EAAE,YAAY,CAAC;QAC1B,cAAc,CAAC,EAAE,eAAe,CAAC;QACjC,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,MAAM,CAAC,EAAE,uBAAuB,CAAC;KAClC;IAuCD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwEpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+DpE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAsD9F;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,kBAAkB,CAChB,aAAa,CAAC,EAAE,OAAO,wCAAwC,EAAE,uBAAuB,EACxF,OAAO,CAAC,EAAE,OAAO,6BAA6B,EAAE,uBAAuB,GACtE,OAAO,6BAA6B,EAAE,sBAAsB;CAQhE"}
+{"version":3,"file":"MultimodalIndexer.d.ts","sourceRoot":"","sources":["../../../src/rag/multimodal/MultimodalIndexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,yBAAyB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAiC,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAEV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAuBzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,iBAAiB;IAK5B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;IAEtD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IAEnD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAwB;IAEtD,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc,CAAC,CAAgB;IAMvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;gBACS,IAAI,EAAE;QAChB,gBAAgB,EAAE,iBAAiB,CAAC;QACpC,WAAW,EAAE,YAAY,CAAC;QAC1B,cAAc,CAAC,EAAE,eAAe,CAAC;QACjC,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,MAAM,CAAC,EAAE,uBAAuB,CAAC;KAClC;IAuCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAQhD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwEpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+DpE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IA4F9F;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,kBAAkB,CAChB,aAAa,CAAC,EAAE,OAAO,wCAAwC,EAAE,uBAAuB,EACxF,OAAO,CAAC,EAAE,OAAO,6BAA6B,EAAE,uBAAuB,GACtE,OAAO,6BAA6B,EAAE,sBAAsB;CAQhE"}

package/dist/rag/multimodal/MultimodalIndexer.js

@@ -169,6 +169,35 @@ export class MultimodalIndexer {
         };
     }
     // -------------------------------------------------------------------------
+    // HyDE configuration
+    // -------------------------------------------------------------------------
+    /**
+     * Attach a HyDE retriever to enable hypothesis-driven multimodal search.
+     *
+     * Once set, pass `hyde: { enabled: true }` in the `search()` options to
+     * activate HyDE for that query. The retriever generates a hypothetical
+     * answer using an LLM, then embeds that answer instead of the raw query
+     * text, which typically yields better recall for exploratory queries.
+     *
+     * @param retriever - A pre-configured HydeRetriever instance.
+     *
+     * @example
+     * ```typescript
+     * indexer.setHydeRetriever(new HydeRetriever({
+     *   llmCaller: myLlmCaller,
+     *   embeddingManager: myEmbeddingManager,
+     *   config: { enabled: true },
+     * }));
+     *
+     * const results = await indexer.search('cats on a beach', {
+     *   hyde: { enabled: true },
+     * });
+     * ```
+     */
+    setHydeRetriever(retriever) {
+        this._hydeRetriever = retriever;
+    }
+    // -------------------------------------------------------------------------
     // Image indexing
     // -------------------------------------------------------------------------
     /**
@@ -340,7 +369,43 @@ export class MultimodalIndexer {
     async search(query, opts) {
         const topK = opts?.topK ?? 5;
         const collection = opts?.collection ?? this._config.defaultCollection;
-        // Step 1: Embed the query text
+        // Step 1: Determine query embedding
+        //
+        // When HyDE is enabled and a HydeRetriever is available, we delegate
+        // the full retrieve cycle to the retriever. This generates a hypothetical
+        // answer, embeds it, and searches the vector store in one shot — including
+        // adaptive threshold stepping for better recall.
+        //
+        // Otherwise we fall back to the standard direct-embedding path.
+        if (opts?.hyde?.enabled && this._hydeRetriever) {
+            const hydeResult = await this._hydeRetriever.retrieve({
+                query,
+                vectorStore: this._vectorStore,
+                collectionName: collection,
+                hypothesis: opts.hyde.hypothesis,
+                queryOptions: {
+                    topK,
+                    includeMetadata: true,
+                    includeTextContent: true,
+                    // Modality filter is applied via metadata filter
+                    ...(opts.modalities && opts.modalities.length > 0
+                        ? {
+                            filter: opts.modalities.length === 1
+                                ? { modality: opts.modalities[0] }
+                                : { modality: { $in: opts.modalities } },
+                        }
+                        : {}),
+                },
+            });
+            return hydeResult.queryResult.documents.map((doc) => ({
+                id: doc.id,
+                content: doc.textContent ?? '',
+                score: doc.similarityScore,
+                modality: doc.metadata?.modality ?? 'text',
+                metadata: doc.metadata,
+            }));
+        }
+        // Standard path: embed the raw query text directly.
         const embeddingRequest = {
             texts: [query],
         };

package/dist/rag/multimodal/MultimodalIndexer.js.map

@@ -1 +1 @@
-{"version":3,"file":"MultimodalIndexer.js","sourceRoot":"","sources":["../../../src/rag/multimodal/MultimodalIndexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiBzC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,sDAAsD;AACtD,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,gCAAgC,GACpC,2DAA2D;IAC3D,iEAAiE;IACjE,2DAA2D,CAAC;AAE9D,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,OAAO,iBAAiB;IA0B5B,4EAA4E;IAC5E,cAAc;IACd,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,YAAY,IAOX;QACC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC/C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QAErC,uEAAuE;QACvE,yEAAyE;QACzE,uEAAuE;QACvE,yCAAyC;QACzC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,gEAAgE;YAChE,4EAA4E;YAC5E,MAAM,EACJ,sBAAsB;YACtB,iEAAiE;cAClE,GAAG,OAAO,CAAC,uDAAuD,CAAC,CAAC;YACrE,IAAI,CAAC,eAAe,GAAG,IAAI,sBAAsB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACzE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,OAAO,GAAG;YACb,iBAAiB,EAAE,IAAI,CAAC,MAAM,EAAE,iBAAiB,IAAI,kBAAkB;YACvE,sBAAsB,EACpB,IAAI,CAAC,MAAM,EAAE,sBAAsB,IAAI,gCAAgC;SAC1E,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,iBAAiB;IACjB,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,UAAU,CAAC,IAAuB;QACtC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,yEAAyE;gBACvE,2CAA2C,CAC9C,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,4CAA4C;QAC5C,IAAI,QAAgB,CAAC;QACrB,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC7C,mEAAmE;YACnE,oEAAoE;YACpE,sBAAsB;YACtB,QAAQ,GAAG,yBAAyB,MAAM,EAAE,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,CAAC;QAED,iDAAiD;QACjD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAEvE,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;QAED,uDAAuD;QACvD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QACrE,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAE3B,MAAM,gBAAgB,GAAqB;YACzC,KAAK,EAAE,CAAC,WAAW,CAAC;SACrB,CAAC;QACF,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QAE5F,IACE,CAAC,iBAAiB,CAAC,UAAU;YAC7B,iBAAiB,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YACzC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,sFAAsF,CACvF,CAAC;QACJ,CAAC;QAED,6DAA6D;QAC7D,MAAM,QAAQ,GAAkC;YAC9C,QAAQ,EAAE,OAAwB;YAClC,GAAI,IAAI,CAAC,QAAsD;SAChE,CAAC;QAEF,MAAM,QAAQ,GAAmB;YAC/B,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;YAC1C,WAAW,EAAE,WAAW;YACxB,QAAQ;SACT,CAAC;QAEF,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAEvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,iBAAiB;IACjB,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,UAAU,CAAC,IAAuB;QACtC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,sEAAsE;gBACpE,yCAAyC,CAC5C,CAAC;QACJ,CAAC;QAED,mCAAmC;QACnC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEjF,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAChF,CAAC;QAED,sDAAsD;QACtD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QACrE,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAE3B,MAAM,gBAAgB,GAAqB;YACzC,KAAK,EAAE,CAAC,UAAU,CAAC;SACpB,CAAC;QACF,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QAE5F,IACE,CAAC,iBAAiB,CAAC,UAAU;YAC7B,iBAAiB,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YACzC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;QACJ,CAAC;QAED,6DAA6D;QAC7D,MAAM,QAAQ,GAAkC;YAC9C,QAAQ,EAAE,OAAwB;YAClC,GAAI,IAAI,CAAC,QAAsD;SAChE,CAAC;QAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAyB,CAAC;QACrD,CAAC;QAED,MAAM,QAAQ,GAAmB;YAC/B,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;YAC1C,WAAW,EAAE,UAAU;YACvB,QAAQ;SACT,CAAC;QAEF,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAEvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU;SACX,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,qBAAqB;IACrB,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,IAA8B;QACxD,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC;QAC7B,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAEtE,+BAA+B;QAC/B,MAAM,gBAAgB,GAAqB;YACzC,KAAK,EAAE,CAAC,KAAK,CAAC;SACf,CAAC;QACF,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QAE5F,IACE,CAAC,iBAAiB,CAAC,UAAU;YAC7B,iBAAiB,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YACzC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;QACJ,CAAC;QAED,MAAM,cAAc,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAEvD,wDAAwD;QACxD,oEAAoE;QACpE,iEAAiE;QACjE,MAAM,MAAM,GACV,IAAI,EAAE,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YAC5C,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;gBAC5B,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;gBAClC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE;YAC1C,CAAC,CAAC,SAAS,CAAC;QAEhB,iCAAiC;QACjC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE;YAC5E,IAAI;YACJ,MAAM,EAAE,MAAa;YACrB,eAAe,EAAE,IAAI;YACrB,kBAAkB,EAAE,IAAI;SACzB,CAAC,CAAC;QAEH,gEAAgE;QAChE,OAAO,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACzC,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,OAAO,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;YAC9B,KAAK,EAAE,GAAG,CAAC,eAAe;YAC1B,QAAQ,EAAG,GAAG,CAAC,QAAQ,EAAE,QAA4B,IAAI,MAAM;YAC/D,QAAQ,EAAE,GAAG,CAAC,QAA+C;SAC9D,CAAC,CAAC,CAAC;IACN,CAAC;IAED,4EAA4E;IAC5E,wBAAwB;IACxB,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,kBAAkB,CAChB,aAAwF,EACxF,OAAuE;QAEvE,gEAAgE;QAChE,4EAA4E;QAC5E,uEAAuE;QACvE,iEAAiE;QACjE,MAAM,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAAC;QAC1E,OAAO,IAAI,sBAAsB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;CACF"}
+{"version":3,"file":"MultimodalIndexer.js","sourceRoot":"","sources":["../../../src/rag/multimodal/MultimodalIndexer.ts"],"names":[],"mappings":"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"}

package/dist/rag/multimodal/types.d.ts

@@ -152,6 +152,30 @@ export interface MultimodalSearchOptions {
      * @default 'multimodal'
      */
     collection?: string;
+    /**
+     * HyDE (Hypothetical Document Embedding) configuration for this search.
+     *
+     * When enabled, a hypothetical answer is generated from the query via LLM
+     * and embedded instead of the raw query. This produces embeddings that are
+     * semantically closer to stored document representations, improving recall
+     * for vague or exploratory queries.
+     *
+     * Requires a `HydeRetriever` to be set on the indexer via
+     * {@link MultimodalIndexer.setHydeRetriever}.
+     *
+     * @example
+     * ```typescript
+     * const results = await indexer.search('architecture diagram', {
+     *   hyde: { enabled: true },
+     * });
+     * ```
+     */
+    hyde?: {
+        /** Whether to use HyDE for this search. @default false */
+        enabled?: boolean;
+        /** Pre-generated hypothesis text (skips the LLM call). */
+        hypothesis?: string;
+    };
 }
 /**
  * A single result from a multimodal search query.

package/dist/rag/multimodal/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/multimodal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAMzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/multimodal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAMzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,EAAE;QACL,0DAA0D;QAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0DAA0D;QAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC"}

package/dist/rag/raptor/RaptorTree.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview RAPTOR — Recursive Abstractive Processing for Tree-Organized Retrieval.
+ *
+ * Based on: Sarthi et al. 2024 "RAPTOR: Recursive Abstractive Processing for
+ * Tree-Organized Retrieval"
+ *
+ * Builds a hierarchical summary tree over document chunks:
+ * - **Layer 0**: Original chunks (leaf nodes)
+ * - **Layer 1**: Summaries of 5-10 related chunks (cluster -> summarize)
+ * - **Layer 2**: Summaries of layer 1 summaries
+ * - **Layer N**: Single corpus-level summary (root)
+ *
+ * At retrieval time, ALL layers are searched simultaneously. This enables:
+ * - Detail queries -> match leaf chunks (layer 0)
+ * - Theme queries -> match cluster summaries (layer 1-2)
+ * - "Big picture" queries -> match high-level summaries (layer N)
+ *
+ * The tree construction pipeline:
+ * 1. **Cluster** similar chunks using k-means on embeddings
+ * 2. **Summarize** each cluster using an LLM with chain-of-thought reasoning
+ * 3. **Embed** each summary
+ * 4. **Store** summaries in the vector store with layer metadata
+ * 5. **Repeat** — treat summaries as new chunks, cluster and summarize again
+ *
+ * @module agentos/rag/raptor/RaptorTree
+ * @see RetrievalAugmentor for integration with the RAG pipeline
+ */
+import type { IEmbeddingManager } from '../IEmbeddingManager.js';
+import type { IVectorStore } from '../IVectorStore.js';
+/**
+ * Configuration for the RAPTOR tree.
+ *
+ * @interface RaptorTreeConfig
+ */
+export interface RaptorTreeConfig {
+    /**
+     * LLM caller for generating summaries.
+     * Takes a prompt string and returns the LLM completion.
+     *
+     * @param {string} prompt - The full prompt including chain-of-thought instructions.
+     * @returns {Promise<string>} The generated summary text.
+     */
+    llmCaller: (prompt: string) => Promise<string>;
+    /** Embedding manager for generating embeddings for clustering and storage. */
+    embeddingManager: IEmbeddingManager;
+    /** Vector store for persisting all layers of the tree. */
+    vectorStore: IVectorStore;
+    /** Collection name in the vector store. Default: 'raptor-tree'. */
+    collectionName?: string;
+    /** Number of chunks per cluster. Default: 8. */
+    clusterSize?: number;
+    /** Maximum tree depth (layers above leaf). Default: 4. */
+    maxDepth?: number;
+    /** Minimum number of chunks required to form a new summary layer. Default: 3. */
+    minChunksForLayer?: number;
+}
+/**
+ * Input chunk for building the RAPTOR tree.
+ *
+ * @interface RaptorInputChunk
+ */
+export interface RaptorInputChunk {
+    /** Unique chunk identifier. */
+    id: string;
+    /** Chunk text content. */
+    text: string;
+    /** Optional metadata to preserve in the tree. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Statistics about the constructed RAPTOR tree.
+ *
+ * @interface RaptorTreeStats
+ */
+export interface RaptorTreeStats {
+    /** Total number of layers (0 = leaf only, 1 = one summary layer, etc.). */
+    totalLayers: number;
+    /** Number of nodes (chunks + summaries) per layer. */
+    nodesPerLayer: Record<number, number>;
+    /** Total nodes across all layers. */
+    totalNodes: number;
+    /** Total number of clusters created. */
+    totalClusters: number;
+    /** Time taken to build the tree (ms). */
+    buildTimeMs: number;
+}
+/**
+ * A single RAPTOR search result with layer information.
+ *
+ * @interface RaptorResult
+ */
+export interface RaptorResult {
+    /** Document/chunk identifier. */
+    id: string;
+    /** Text content. */
+    text: string;
+    /** Similarity score from vector search. */
+    score: number;
+    /** Layer in the RAPTOR tree (0 = leaf, higher = more abstract). */
+    layer: number;
+    /** Whether this is a summary node or an original leaf chunk. */
+    isSummary: boolean;
+    /** Optional metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * RAPTOR — Recursive Abstractive Processing for Tree-Organized Retrieval.
+ *
+ * Builds a hierarchical summary tree over document chunks, enabling retrieval
+ * at multiple levels of abstraction. Leaf nodes contain original chunks while
+ * higher layers contain progressively more abstract summaries.
+ *
+ * @example Building and searching a RAPTOR tree
+ * ```typescript
+ * const raptor = new RaptorTree({
+ *   llmCaller: async (prompt) => {
+ *     const response = await openai.chat.completions.create({
+ *       model: 'gpt-4o-mini',
+ *       messages: [{ role: 'user', content: prompt }],
+ *     });
+ *     return response.choices[0].message.content ?? '';
+ *   },
+ *   embeddingManager: myEmbeddingManager,
+ *   vectorStore: myVectorStore,
+ *   clusterSize: 8,
+ *   maxDepth: 3,
+ * });
+ *
+ * // Build tree from 100 document chunks
+ * const stats = await raptor.build(chunks);
+ * console.log(`Built ${stats.totalLayers} layers with ${stats.totalNodes} total nodes`);
+ *
+ * // Search all layers simultaneously
+ * const results = await raptor.search('What are the main themes?', 10);
+ * for (const r of results) {
+ *   console.log(`[Layer ${r.layer}] ${r.id}: ${r.score.toFixed(3)} — ${r.text.slice(0, 80)}...`);
+ * }
+ * ```
+ */
+export declare class RaptorTree {
+    /** LLM caller for summarization. */
+    private llmCaller;
+    /** Embedding manager for generating embeddings. */
+    private embeddingManager;
+    /** Vector store for persisting tree nodes. */
+    private vectorStore;
+    /** Collection name in the vector store. */
+    private collectionName;
+    /** Number of chunks per cluster. */
+    private clusterSize;
+    /** Maximum tree depth. */
+    private maxDepth;
+    /** Minimum chunks to form a new layer. */
+    private minChunksForLayer;
+    /** Cached statistics from the last build. */
+    private stats;
+    /**
+     * Creates a new RaptorTree.
+     *
+     * @param {RaptorTreeConfig} config - Configuration including LLM caller,
+     *   embedding manager, vector store, and clustering parameters.
+     *
+     * @example
+     * ```typescript
+     * const raptor = new RaptorTree({
+     *   llmCaller: myLlm,
+     *   embeddingManager: myEmbeddings,
+     *   vectorStore: myStore,
+     *   clusterSize: 8,
+     *   maxDepth: 4,
+     * });
+     * ```
+     */
+    constructor(config: RaptorTreeConfig);
+    /**
+     * Builds the RAPTOR tree from a set of leaf chunks.
+     *
+     * Pipeline for each layer:
+     * 1. Embed all current-layer chunks
+     * 2. Cluster similar chunks using k-means
+     * 3. Summarize each cluster using the LLM with chain-of-thought
+     * 4. Embed summaries and store in vector store with layer metadata
+     * 5. Treat summaries as the next layer's input and repeat
+     *
+     * Stops when:
+     * - Fewer than `minChunksForLayer` summaries were produced
+     * - Maximum depth is reached
+     * - Only one cluster remains (root summary)
+     *
+     * @param {RaptorInputChunk[]} chunks - Leaf chunks to build the tree from.
+     * @returns {Promise<RaptorTreeStats>} Statistics about the constructed tree.
+     * @throws {Error} If embedding or storage fails critically.
+     *
+     * @example
+     * ```typescript
+     * const chunks = documents.map((doc, i) => ({
+     *   id: `chunk-${i}`,
+     *   text: doc.content,
+     *   metadata: { source: doc.source },
+     * }));
+     * const stats = await raptor.build(chunks);
+     * console.log(`Tree has ${stats.totalLayers} layers`);
+     * ```
+     */
+    build(chunks: RaptorInputChunk[]): Promise<RaptorTreeStats>;
+    /**
+     * Searches ALL layers of the RAPTOR tree simultaneously.
+     *
+     * This is the key advantage of RAPTOR: a detail query will match leaf
+     * chunks, while a thematic query will match higher-layer summaries.
+     * Both types of results are returned together, sorted by relevance.
+     *
+     * @param {string} query - The search query.
+     * @param {number} [topK=10] - Maximum number of results across all layers.
+     * @returns {Promise<RaptorResult[]>} Results from all layers, sorted by score.
+     * @throws {Error} If embedding or vector search fails.
+     *
+     * @example
+     * ```typescript
+     * const results = await raptor.search('authentication architecture', 10);
+     * // May return:
+     * // - Layer 0 chunks about specific auth implementations
+     * // - Layer 1 summaries about auth patterns
+     * // - Layer 2 high-level summary about security architecture
+     * ```
+     */
+    search(query: string, topK?: number): Promise<RaptorResult[]>;
+    /**
+     * Returns statistics about the last tree build.
+     *
+     * @returns {RaptorTreeStats} Tree statistics including layer counts, node counts,
+     *   cluster counts, and build time.
+     *
+     * @example
+     * ```typescript
+     * const stats = raptor.getStats();
+     * console.log(`Layers: ${stats.totalLayers}, Nodes: ${stats.totalNodes}`);
+     * ```
+     */
+    getStats(): RaptorTreeStats;
+    /**
+     * Generates a summary of a cluster of documents using chain-of-thought reasoning.
+     *
+     * The prompt instructs the LLM to:
+     * 1. Identify key themes across the documents
+     * 2. Consider what information would be lost in summarization
+     * 3. Note relationships between documents
+     * 4. Write a comprehensive summary preserving the most important information
+     *
+     * @param {string[]} texts - Texts in the cluster to summarize.
+     * @param {number} layer - Current layer index (for context in the prompt).
+     * @param {number} clusterIndex - Cluster index within the layer.
+     * @returns {Promise<string>} The generated summary.
+     */
+    private summarizeCluster;
+    /**
+     * Stores chunks/summaries in the vector store with layer metadata.
+     *
+     * Generates embeddings for all texts, then upserts them into the vector
+     * store with metadata indicating their layer and summary status.
+     *
+     * @param {RaptorInputChunk[]} chunks - Chunks to store.
+     * @param {number} layer - Layer index in the RAPTOR tree.
+     * @param {boolean} isSummary - Whether these are summary nodes.
+     */
+    private storeChunks;
+}
+//# sourceMappingURL=RaptorTree.d.ts.map

package/dist/rag/raptor/RaptorTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RaptorTree.d.ts","sourceRoot":"","sources":["../../../src/rag/raptor/RaptorTree.ts"],"names":[],"mappings":"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"}