@langchain/core 0.3.72 → 1.0.0-alpha.2

package/dist/retrievers/index.d.ts

@@ -1,7 +1,10 @@
+import { DocumentInterface } from "../documents/document.js";
 import { BaseCallbackConfig, CallbackManagerForRetrieverRun, Callbacks } from "../callbacks/manager.js";
-import type { DocumentInterface } from "../documents/document.js";
-import { Runnable, type RunnableInterface } from "../runnables/base.js";
-import { RunnableConfig } from "../runnables/config.js";
+import { RunnableConfig, RunnableInterface } from "../runnables/types.js";
+import { Runnable } from "../runnables/base.js";
+
+//#region src/retrievers/index.d.ts
+
 /**
  * Input configuration options for initializing a retriever that extends
  * the `BaseRetriever` class. This interface provides base properties
@@ -22,11 +25,11 @@ import { RunnableConfig } from "../runnables/config.js";
  * - `verbose` (optional): A boolean flag that, if set to `true`, enables
  *   detailed logging and output during the retrieval process. Defaults to `false`.
  */
-export interface BaseRetrieverInput {
-    callbacks?: Callbacks;
-    tags?: string[];
-    metadata?: Record<string, unknown>;
-    verbose?: boolean;
+interface BaseRetrieverInput {
+  callbacks?: Callbacks;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  verbose?: boolean;
 }
 /**
  * Interface for a base retriever that defines core functionality for
@@ -38,18 +41,20 @@ export interface BaseRetrieverInput {
  * @template Metadata - The type of metadata associated with each document,
  *                      defaulting to `Record<string, any>`.
  */
-export interface BaseRetrieverInterface<Metadata extends Record<string, any> = Record<string, any>> extends RunnableInterface<string, DocumentInterface<Metadata>[]> {
-    /**
-     * Retrieves documents relevant to a given query, allowing optional
-     * configurations for customization.
-     *
-     * @param query - A string representing the query to search for relevant documents.
-     * @param config - (optional) Configuration options for the retrieval process,
-     *                 which may include callbacks and additional context settings.
-     * @returns A promise that resolves to an array of `DocumentInterface` instances,
-     *          each containing metadata specified by the `Metadata` type parameter.
-     */
-    getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
+interface BaseRetrieverInterface<
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+Metadata extends Record<string, any> = Record<string, any>> extends RunnableInterface<string, DocumentInterface<Metadata>[]> {
+  /**
+   * Retrieves documents relevant to a given query, allowing optional
+   * configurations for customization.
+   *
+   * @param query - A string representing the query to search for relevant documents.
+   * @param config - (optional) Configuration options for the retrieval process,
+   *                 which may include callbacks and additional context settings.
+   * @returns A promise that resolves to an array of `DocumentInterface` instances,
+   *          each containing metadata specified by the `Metadata` type parameter.
+   */
+  getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
 }
 /**
  * Abstract base class for a document retrieval system, designed to
@@ -63,72 +68,77 @@ export interface BaseRetrieverInterface<Metadata extends Record<string, any> = R
  * @template Metadata - The type of metadata associated with each document,
  *                      defaulting to `Record<string, any>`.
  */
-export declare abstract class BaseRetriever<Metadata extends Record<string, any> = Record<string, any>> extends Runnable<string, DocumentInterface<Metadata>[]> implements BaseRetrieverInterface {
-    /**
-     * Optional callbacks to handle various events in the retrieval process.
-     */
-    callbacks?: Callbacks;
-    /**
-     * Tags to label or categorize the retrieval operation.
-     */
-    tags?: string[];
-    /**
-     * Metadata to provide additional context or information about the retrieval
-     * operation.
-     */
-    metadata?: Record<string, unknown>;
-    /**
-     * If set to `true`, enables verbose logging for the retrieval process.
-     */
-    verbose?: boolean;
-    /**
-     * Constructs a new `BaseRetriever` instance with optional configuration fields.
-     *
-     * @param fields - Optional input configuration that can include `callbacks`,
-     *                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
-     */
-    constructor(fields?: BaseRetrieverInput);
-    /**
-     * TODO: This should be an abstract method, but we'd like to avoid breaking
-     * changes to people currently using subclassed custom retrievers.
-     * Change it on next major release.
-     */
-    /**
-     * Placeholder method for retrieving relevant documents based on a query.
-     *
-     * This method is intended to be implemented by subclasses and will be
-     * converted to an abstract method in the next major release. Currently, it
-     * throws an error if not implemented, ensuring that custom retrievers define
-     * the specific retrieval logic.
-     *
-     * @param _query - The query string used to search for relevant documents.
-     * @param _callbacks - (optional) Callback manager for managing callbacks
-     *                     during retrieval.
-     * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
-     * @throws {Error} Throws an error indicating the method is not implemented.
-     */
-    _getRelevantDocuments(_query: string, _callbacks?: CallbackManagerForRetrieverRun): Promise<DocumentInterface<Metadata>[]>;
-    /**
-     * Executes a retrieval operation.
-     *
-     * @param input - The query string used to search for relevant documents.
-     * @param options - (optional) Configuration options for the retrieval run,
-     *                  which may include callbacks, tags, and metadata.
-     * @returns A promise that resolves to an array of `DocumentInterface` instances
-     *          representing the most relevant documents to the query.
-     */
-    invoke(input: string, options?: RunnableConfig): Promise<DocumentInterface<Metadata>[]>;
-    /**
-     * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
-     *
-     * Main method used to retrieve relevant documents. It takes a query
-     * string and an optional configuration object, and returns a promise that
-     * resolves to an array of `Document` objects. This method handles the
-     * retrieval process, including starting and ending callbacks, and error
-     * handling.
-     * @param query The query string to retrieve relevant documents for.
-     * @param config Optional configuration object for the retrieval process.
-     * @returns A promise that resolves to an array of `Document` objects.
-     */
-    getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
+declare abstract class BaseRetriever<
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+Metadata extends Record<string, any> = Record<string, any>> extends Runnable<string, DocumentInterface<Metadata>[]> implements BaseRetrieverInterface {
+  /**
+   * Optional callbacks to handle various events in the retrieval process.
+   */
+  callbacks?: Callbacks;
+  /**
+   * Tags to label or categorize the retrieval operation.
+   */
+  tags?: string[];
+  /**
+   * Metadata to provide additional context or information about the retrieval
+   * operation.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * If set to `true`, enables verbose logging for the retrieval process.
+   */
+  verbose?: boolean;
+  /**
+   * Constructs a new `BaseRetriever` instance with optional configuration fields.
+   *
+   * @param fields - Optional input configuration that can include `callbacks`,
+   *                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
+   */
+  constructor(fields?: BaseRetrieverInput);
+  /**
+   * TODO: This should be an abstract method, but we'd like to avoid breaking
+   * changes to people currently using subclassed custom retrievers.
+   * Change it on next major release.
+   */
+  /**
+   * Placeholder method for retrieving relevant documents based on a query.
+   *
+   * This method is intended to be implemented by subclasses and will be
+   * converted to an abstract method in the next major release. Currently, it
+   * throws an error if not implemented, ensuring that custom retrievers define
+   * the specific retrieval logic.
+   *
+   * @param _query - The query string used to search for relevant documents.
+   * @param _callbacks - (optional) Callback manager for managing callbacks
+   *                     during retrieval.
+   * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
+   * @throws {Error} Throws an error indicating the method is not implemented.
+   */
+  _getRelevantDocuments(_query: string, _callbacks?: CallbackManagerForRetrieverRun): Promise<DocumentInterface<Metadata>[]>;
+  /**
+   * Executes a retrieval operation.
+   *
+   * @param input - The query string used to search for relevant documents.
+   * @param options - (optional) Configuration options for the retrieval run,
+   *                  which may include callbacks, tags, and metadata.
+   * @returns A promise that resolves to an array of `DocumentInterface` instances
+   *          representing the most relevant documents to the query.
+   */
+  invoke(input: string, options?: RunnableConfig): Promise<DocumentInterface<Metadata>[]>;
+  /**
+   * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
+   *
+   * Main method used to retrieve relevant documents. It takes a query
+   * string and an optional configuration object, and returns a promise that
+   * resolves to an array of `Document` objects. This method handles the
+   * retrieval process, including starting and ending callbacks, and error
+   * handling.
+   * @param query The query string to retrieve relevant documents for.
+   * @param config Optional configuration object for the retrieval process.
+   * @returns A promise that resolves to an array of `Document` objects.
+   */
+  getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
 }
+//#endregion
+export { BaseRetriever, BaseRetrieverInput, BaseRetrieverInterface };
+//# sourceMappingURL=index.d.ts.map

package/dist/retrievers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["BaseCallbackConfig","CallbackManagerForRetrieverRun","Callbacks","DocumentInterface","Runnable","RunnableInterface","RunnableConfig","BaseRetrieverInput","Record","BaseRetrieverInterface","Metadata","Promise","BaseRetriever"],"sources":["../../src/retrievers/index.d.ts"],"sourcesContent":["import { BaseCallbackConfig, CallbackManagerForRetrieverRun, Callbacks } from \"../callbacks/manager.js\";\nimport type { DocumentInterface } from \"../documents/document.js\";\nimport { Runnable, type RunnableInterface } from \"../runnables/base.js\";\nimport { RunnableConfig } from \"../runnables/config.js\";\n/**\n * Input configuration options for initializing a retriever that extends\n * the `BaseRetriever` class. This interface provides base properties\n * common to all retrievers, allowing customization of callback functions,\n * tagging, metadata, and logging verbosity.\n *\n * Fields:\n * - `callbacks` (optional): An array of callback functions that handle various\n *   events during retrieval, such as logging, error handling, or progress updates.\n *\n * - `tags` (optional): An array of strings used to add contextual tags to\n *   retrieval operations, allowing for easier categorization and tracking.\n *\n * - `metadata` (optional): A record of key-value pairs to store additional\n *   contextual information for retrieval operations, which can be useful\n *   for logging or auditing purposes.\n *\n * - `verbose` (optional): A boolean flag that, if set to `true`, enables\n *   detailed logging and output during the retrieval process. Defaults to `false`.\n */\nexport interface BaseRetrieverInput {\n    callbacks?: Callbacks;\n    tags?: string[];\n    metadata?: Record<string, unknown>;\n    verbose?: boolean;\n}\n/**\n * Interface for a base retriever that defines core functionality for\n * retrieving relevant documents from a source based on a query.\n *\n * The `BaseRetrieverInterface` standardizes the `getRelevantDocuments` method,\n * enabling retrieval of documents that match the query criteria.\n *\n * @template Metadata - The type of metadata associated with each document,\n *                      defaulting to `Record<string, any>`.\n */\nexport interface BaseRetrieverInterface<\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nMetadata extends Record<string, any> = Record<string, any>> extends RunnableInterface<string, DocumentInterface<Metadata>[]> {\n    /**\n     * Retrieves documents relevant to a given query, allowing optional\n     * configurations for customization.\n     *\n     * @param query - A string representing the query to search for relevant documents.\n     * @param config - (optional) Configuration options for the retrieval process,\n     *                 which may include callbacks and additional context settings.\n     * @returns A promise that resolves to an array of `DocumentInterface` instances,\n     *          each containing metadata specified by the `Metadata` type parameter.\n     */\n    getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;\n}\n/**\n * Abstract base class for a document retrieval system, designed to\n * process string queries and return the most relevant documents from a source.\n *\n * `BaseRetriever` provides common properties and methods for derived retrievers,\n * such as callbacks, tagging, and verbose logging. Custom retrieval systems\n * should extend this class and implement `_getRelevantDocuments` to define\n * the specific retrieval logic.\n *\n * @template Metadata - The type of metadata associated with each document,\n *                      defaulting to `Record<string, any>`.\n */\nexport declare abstract class BaseRetriever<\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nMetadata extends Record<string, any> = Record<string, any>> extends Runnable<string, DocumentInterface<Metadata>[]> implements BaseRetrieverInterface {\n    /**\n     * Optional callbacks to handle various events in the retrieval process.\n     */\n    callbacks?: Callbacks;\n    /**\n     * Tags to label or categorize the retrieval operation.\n     */\n    tags?: string[];\n    /**\n     * Metadata to provide additional context or information about the retrieval\n     * operation.\n     */\n    metadata?: Record<string, unknown>;\n    /**\n     * If set to `true`, enables verbose logging for the retrieval process.\n     */\n    verbose?: boolean;\n    /**\n     * Constructs a new `BaseRetriever` instance with optional configuration fields.\n     *\n     * @param fields - Optional input configuration that can include `callbacks`,\n     *                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.\n     */\n    constructor(fields?: BaseRetrieverInput);\n    /**\n     * TODO: This should be an abstract method, but we'd like to avoid breaking\n     * changes to people currently using subclassed custom retrievers.\n     * Change it on next major release.\n     */\n    /**\n     * Placeholder method for retrieving relevant documents based on a query.\n     *\n     * This method is intended to be implemented by subclasses and will be\n     * converted to an abstract method in the next major release. Currently, it\n     * throws an error if not implemented, ensuring that custom retrievers define\n     * the specific retrieval logic.\n     *\n     * @param _query - The query string used to search for relevant documents.\n     * @param _callbacks - (optional) Callback manager for managing callbacks\n     *                     during retrieval.\n     * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.\n     * @throws {Error} Throws an error indicating the method is not implemented.\n     */\n    _getRelevantDocuments(_query: string, _callbacks?: CallbackManagerForRetrieverRun): Promise<DocumentInterface<Metadata>[]>;\n    /**\n     * Executes a retrieval operation.\n     *\n     * @param input - The query string used to search for relevant documents.\n     * @param options - (optional) Configuration options for the retrieval run,\n     *                  which may include callbacks, tags, and metadata.\n     * @returns A promise that resolves to an array of `DocumentInterface` instances\n     *          representing the most relevant documents to the query.\n     */\n    invoke(input: string, options?: RunnableConfig): Promise<DocumentInterface<Metadata>[]>;\n    /**\n     * @deprecated Use .invoke() instead. Will be removed in 0.3.0.\n     *\n     * Main method used to retrieve relevant documents. It takes a query\n     * string and an optional configuration object, and returns a promise that\n     * resolves to an array of `Document` objects. This method handles the\n     * retrieval process, including starting and ending callbacks, and error\n     * handling.\n     * @param query The query string to retrieve relevant documents for.\n     * @param config Optional configuration object for the retrieval process.\n     * @returns A promise that resolves to an array of `Document` objects.\n     */\n    getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;\n}\n"],"mappings":";;;;;;;;;AAwBA;;;;AAGqB;AAarB;;;;;;;;;;;;AAEqF;AAyBvDY,UA3CbL,kBAAAA,CA2C0B;EAAA,SAAA,CAAA,EA1C3BL,SA0C2B;EAAA,IAE1BM,CAAAA,EAAAA,MAAAA,EAAAA;EAAM,QAAgBA,CAAAA,EA1CxBA,MA0CwBA,CAAAA,MAAAA,EAAAA,OAAAA,CAAAA;EAAM,OAA0DE,CAAAA,EAAAA,OAAAA;;;;;;;;;;;;AAsDlDC,UAnFpCF,sBAmFoCE;;iBAjFpCH,MA8F4CR,CAAAA,MAAAA,EAAAA,GAAAA,CAAAA,GA9FtBQ,MA8FsBR,CAAAA,MAAAA,EAAAA,GAAAA,CAAAA,CAAAA,SA9FOK,iBA8FPL,CAAAA,MAAAA,EA9FiCG,iBA8FjCH,CA9FmDU,QA8FnDV,CAAAA,EAAAA,CAAAA,CAAAA;EAAkB;;;;;AAnEsE;;;;;+CAhBpGE,YAAYF,qBAAqBW,QAAQR,kBAAkBO;;;;;;;;;;;;;;uBAc9EE;;iBAEbJ,sBAAsBA,6BAA6BJ,iBAAiBD,kBAAkBO,wBAAwBD;;;;cAI/GP;;;;;;;;;aASDM;;;;;;;;;;;uBAWUD;;;;;;;;;;;;;;;;;;;;qDAoB8BN,iCAAiCU,QAAQR,kBAAkBO;;;;;;;;;;kCAU9EJ,iBAAiBK,QAAQR,kBAAkBO;;;;;;;;;;;;;+CAa9BR,YAAYF,qBAAqBW,QAAQR,kBAAkBO"}

package/dist/retrievers/index.js

@@ -1,127 +1,115 @@
-import { CallbackManager, parseCallbackConfigArg, } from "../callbacks/manager.js";
-import { Runnable } from "../runnables/base.js";
+import { __export } from "../_virtual/rolldown_runtime.js";
+import { CallbackManager, parseCallbackConfigArg } from "../callbacks/manager.js";
 import { ensureConfig } from "../runnables/config.js";
+import { Runnable } from "../runnables/base.js";
+
+//#region src/retrievers/index.ts
+var retrievers_exports = {};
+__export(retrievers_exports, { BaseRetriever: () => BaseRetriever });
 /**
- * Abstract base class for a document retrieval system, designed to
- * process string queries and return the most relevant documents from a source.
- *
- * `BaseRetriever` provides common properties and methods for derived retrievers,
- * such as callbacks, tagging, and verbose logging. Custom retrieval systems
- * should extend this class and implement `_getRelevantDocuments` to define
- * the specific retrieval logic.
- *
- * @template Metadata - The type of metadata associated with each document,
- *                      defaulting to `Record<string, any>`.
- */
-export class BaseRetriever extends Runnable {
-    /**
-     * Constructs a new `BaseRetriever` instance with optional configuration fields.
-     *
-     * @param fields - Optional input configuration that can include `callbacks`,
-     *                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
-     */
-    constructor(fields) {
-        super(fields);
-        /**
-         * Optional callbacks to handle various events in the retrieval process.
-         */
-        Object.defineProperty(this, "callbacks", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Tags to label or categorize the retrieval operation.
-         */
-        Object.defineProperty(this, "tags", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Metadata to provide additional context or information about the retrieval
-         * operation.
-         */
-        Object.defineProperty(this, "metadata", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * If set to `true`, enables verbose logging for the retrieval process.
-         */
-        Object.defineProperty(this, "verbose", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.callbacks = fields?.callbacks;
-        this.tags = fields?.tags ?? [];
-        this.metadata = fields?.metadata ?? {};
-        this.verbose = fields?.verbose ?? false;
-    }
-    /**
-     * TODO: This should be an abstract method, but we'd like to avoid breaking
-     * changes to people currently using subclassed custom retrievers.
-     * Change it on next major release.
-     */
-    /**
-     * Placeholder method for retrieving relevant documents based on a query.
-     *
-     * This method is intended to be implemented by subclasses and will be
-     * converted to an abstract method in the next major release. Currently, it
-     * throws an error if not implemented, ensuring that custom retrievers define
-     * the specific retrieval logic.
-     *
-     * @param _query - The query string used to search for relevant documents.
-     * @param _callbacks - (optional) Callback manager for managing callbacks
-     *                     during retrieval.
-     * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
-     * @throws {Error} Throws an error indicating the method is not implemented.
-     */
-    _getRelevantDocuments(_query, _callbacks) {
-        throw new Error("Not implemented!");
-    }
-    /**
-     * Executes a retrieval operation.
-     *
-     * @param input - The query string used to search for relevant documents.
-     * @param options - (optional) Configuration options for the retrieval run,
-     *                  which may include callbacks, tags, and metadata.
-     * @returns A promise that resolves to an array of `DocumentInterface` instances
-     *          representing the most relevant documents to the query.
-     */
-    async invoke(input, options) {
-        return this.getRelevantDocuments(input, ensureConfig(options));
-    }
-    /**
-     * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
-     *
-     * Main method used to retrieve relevant documents. It takes a query
-     * string and an optional configuration object, and returns a promise that
-     * resolves to an array of `Document` objects. This method handles the
-     * retrieval process, including starting and ending callbacks, and error
-     * handling.
-     * @param query The query string to retrieve relevant documents for.
-     * @param config Optional configuration object for the retrieval process.
-     * @returns A promise that resolves to an array of `Document` objects.
-     */
-    async getRelevantDocuments(query, config) {
-        const parsedConfig = ensureConfig(parseCallbackConfigArg(config));
-        const callbackManager_ = await CallbackManager.configure(parsedConfig.callbacks, this.callbacks, parsedConfig.tags, this.tags, parsedConfig.metadata, this.metadata, { verbose: this.verbose });
-        const runManager = await callbackManager_?.handleRetrieverStart(this.toJSON(), query, parsedConfig.runId, undefined, undefined, undefined, parsedConfig.runName);
-        try {
-            const results = await this._getRelevantDocuments(query, runManager);
-            await runManager?.handleRetrieverEnd(results);
-            return results;
-        }
-        catch (error) {
-            await runManager?.handleRetrieverError(error);
-            throw error;
-        }
-    }
-}
+* Abstract base class for a document retrieval system, designed to
+* process string queries and return the most relevant documents from a source.
+*
+* `BaseRetriever` provides common properties and methods for derived retrievers,
+* such as callbacks, tagging, and verbose logging. Custom retrieval systems
+* should extend this class and implement `_getRelevantDocuments` to define
+* the specific retrieval logic.
+*
+* @template Metadata - The type of metadata associated with each document,
+*                      defaulting to `Record<string, any>`.
+*/
+var BaseRetriever = class extends Runnable {
+	/**
+	* Optional callbacks to handle various events in the retrieval process.
+	*/
+	callbacks;
+	/**
+	* Tags to label or categorize the retrieval operation.
+	*/
+	tags;
+	/**
+	* Metadata to provide additional context or information about the retrieval
+	* operation.
+	*/
+	metadata;
+	/**
+	* If set to `true`, enables verbose logging for the retrieval process.
+	*/
+	verbose;
+	/**
+	* Constructs a new `BaseRetriever` instance with optional configuration fields.
+	*
+	* @param fields - Optional input configuration that can include `callbacks`,
+	*                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
+	*/
+	constructor(fields) {
+		super(fields);
+		this.callbacks = fields?.callbacks;
+		this.tags = fields?.tags ?? [];
+		this.metadata = fields?.metadata ?? {};
+		this.verbose = fields?.verbose ?? false;
+	}
+	/**
+	* TODO: This should be an abstract method, but we'd like to avoid breaking
+	* changes to people currently using subclassed custom retrievers.
+	* Change it on next major release.
+	*/
+	/**
+	* Placeholder method for retrieving relevant documents based on a query.
+	*
+	* This method is intended to be implemented by subclasses and will be
+	* converted to an abstract method in the next major release. Currently, it
+	* throws an error if not implemented, ensuring that custom retrievers define
+	* the specific retrieval logic.
+	*
+	* @param _query - The query string used to search for relevant documents.
+	* @param _callbacks - (optional) Callback manager for managing callbacks
+	*                     during retrieval.
+	* @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
+	* @throws {Error} Throws an error indicating the method is not implemented.
+	*/
+	_getRelevantDocuments(_query, _callbacks) {
+		throw new Error("Not implemented!");
+	}
+	/**
+	* Executes a retrieval operation.
+	*
+	* @param input - The query string used to search for relevant documents.
+	* @param options - (optional) Configuration options for the retrieval run,
+	*                  which may include callbacks, tags, and metadata.
+	* @returns A promise that resolves to an array of `DocumentInterface` instances
+	*          representing the most relevant documents to the query.
+	*/
+	async invoke(input, options) {
+		return this.getRelevantDocuments(input, ensureConfig(options));
+	}
+	/**
+	* @deprecated Use .invoke() instead. Will be removed in 0.3.0.
+	*
+	* Main method used to retrieve relevant documents. It takes a query
+	* string and an optional configuration object, and returns a promise that
+	* resolves to an array of `Document` objects. This method handles the
+	* retrieval process, including starting and ending callbacks, and error
+	* handling.
+	* @param query The query string to retrieve relevant documents for.
+	* @param config Optional configuration object for the retrieval process.
+	* @returns A promise that resolves to an array of `Document` objects.
+	*/
+	async getRelevantDocuments(query, config) {
+		const parsedConfig = ensureConfig(parseCallbackConfigArg(config));
+		const callbackManager_ = await CallbackManager.configure(parsedConfig.callbacks, this.callbacks, parsedConfig.tags, this.tags, parsedConfig.metadata, this.metadata, { verbose: this.verbose });
+		const runManager = await callbackManager_?.handleRetrieverStart(this.toJSON(), query, parsedConfig.runId, void 0, void 0, void 0, parsedConfig.runName);
+		try {
+			const results = await this._getRelevantDocuments(query, runManager);
+			await runManager?.handleRetrieverEnd(results);
+			return results;
+		} catch (error) {
+			await runManager?.handleRetrieverError(error);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+export { BaseRetriever, retrievers_exports };
+//# sourceMappingURL=index.js.map

package/dist/retrievers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["fields?: BaseRetrieverInput","_query: string","_callbacks?: CallbackManagerForRetrieverRun","input: string","options?: RunnableConfig","query: string","config?: Callbacks | BaseCallbackConfig"],"sources":["../../src/retrievers/index.ts"],"sourcesContent":["import {\n  BaseCallbackConfig,\n  CallbackManager,\n  CallbackManagerForRetrieverRun,\n  Callbacks,\n  parseCallbackConfigArg,\n} from \"../callbacks/manager.js\";\nimport type { DocumentInterface } from \"../documents/document.js\";\nimport { Runnable, type RunnableInterface } from \"../runnables/base.js\";\nimport { RunnableConfig, ensureConfig } from \"../runnables/config.js\";\n\n/**\n * Input configuration options for initializing a retriever that extends\n * the `BaseRetriever` class. This interface provides base properties\n * common to all retrievers, allowing customization of callback functions,\n * tagging, metadata, and logging verbosity.\n *\n * Fields:\n * - `callbacks` (optional): An array of callback functions that handle various\n *   events during retrieval, such as logging, error handling, or progress updates.\n *\n * - `tags` (optional): An array of strings used to add contextual tags to\n *   retrieval operations, allowing for easier categorization and tracking.\n *\n * - `metadata` (optional): A record of key-value pairs to store additional\n *   contextual information for retrieval operations, which can be useful\n *   for logging or auditing purposes.\n *\n * - `verbose` (optional): A boolean flag that, if set to `true`, enables\n *   detailed logging and output during the retrieval process. Defaults to `false`.\n */\nexport interface BaseRetrieverInput {\n  callbacks?: Callbacks;\n  tags?: string[];\n  metadata?: Record<string, unknown>;\n  verbose?: boolean;\n}\n\n/**\n * Interface for a base retriever that defines core functionality for\n * retrieving relevant documents from a source based on a query.\n *\n * The `BaseRetrieverInterface` standardizes the `getRelevantDocuments` method,\n * enabling retrieval of documents that match the query criteria.\n *\n * @template Metadata - The type of metadata associated with each document,\n *                      defaulting to `Record<string, any>`.\n */\nexport interface BaseRetrieverInterface<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  Metadata extends Record<string, any> = Record<string, any>\n> extends RunnableInterface<string, DocumentInterface<Metadata>[]> {\n  /**\n   * Retrieves documents relevant to a given query, allowing optional\n   * configurations for customization.\n   *\n   * @param query - A string representing the query to search for relevant documents.\n   * @param config - (optional) Configuration options for the retrieval process,\n   *                 which may include callbacks and additional context settings.\n   * @returns A promise that resolves to an array of `DocumentInterface` instances,\n   *          each containing metadata specified by the `Metadata` type parameter.\n   */\n  getRelevantDocuments(\n    query: string,\n    config?: Callbacks | BaseCallbackConfig\n  ): Promise<DocumentInterface<Metadata>[]>;\n}\n\n/**\n * Abstract base class for a document retrieval system, designed to\n * process string queries and return the most relevant documents from a source.\n *\n * `BaseRetriever` provides common properties and methods for derived retrievers,\n * such as callbacks, tagging, and verbose logging. Custom retrieval systems\n * should extend this class and implement `_getRelevantDocuments` to define\n * the specific retrieval logic.\n *\n * @template Metadata - The type of metadata associated with each document,\n *                      defaulting to `Record<string, any>`.\n */\nexport abstract class BaseRetriever<\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    Metadata extends Record<string, any> = Record<string, any>\n  >\n  extends Runnable<string, DocumentInterface<Metadata>[]>\n  implements BaseRetrieverInterface\n{\n  /**\n   * Optional callbacks to handle various events in the retrieval process.\n   */\n  callbacks?: Callbacks;\n\n  /**\n   * Tags to label or categorize the retrieval operation.\n   */\n  tags?: string[];\n\n  /**\n   * Metadata to provide additional context or information about the retrieval\n   * operation.\n   */\n  metadata?: Record<string, unknown>;\n\n  /**\n   * If set to `true`, enables verbose logging for the retrieval process.\n   */\n  verbose?: boolean;\n\n  /**\n   * Constructs a new `BaseRetriever` instance with optional configuration fields.\n   *\n   * @param fields - Optional input configuration that can include `callbacks`,\n   *                 `tags`, `metadata`, and `verbose` settings for custom retriever behavior.\n   */\n  constructor(fields?: BaseRetrieverInput) {\n    super(fields);\n    this.callbacks = fields?.callbacks;\n    this.tags = fields?.tags ?? [];\n    this.metadata = fields?.metadata ?? {};\n    this.verbose = fields?.verbose ?? false;\n  }\n\n  /**\n   * TODO: This should be an abstract method, but we'd like to avoid breaking\n   * changes to people currently using subclassed custom retrievers.\n   * Change it on next major release.\n   */\n  /**\n   * Placeholder method for retrieving relevant documents based on a query.\n   *\n   * This method is intended to be implemented by subclasses and will be\n   * converted to an abstract method in the next major release. Currently, it\n   * throws an error if not implemented, ensuring that custom retrievers define\n   * the specific retrieval logic.\n   *\n   * @param _query - The query string used to search for relevant documents.\n   * @param _callbacks - (optional) Callback manager for managing callbacks\n   *                     during retrieval.\n   * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.\n   * @throws {Error} Throws an error indicating the method is not implemented.\n   */\n  _getRelevantDocuments(\n    _query: string,\n    _callbacks?: CallbackManagerForRetrieverRun\n  ): Promise<DocumentInterface<Metadata>[]> {\n    throw new Error(\"Not implemented!\");\n  }\n\n  /**\n   * Executes a retrieval operation.\n   *\n   * @param input - The query string used to search for relevant documents.\n   * @param options - (optional) Configuration options for the retrieval run,\n   *                  which may include callbacks, tags, and metadata.\n   * @returns A promise that resolves to an array of `DocumentInterface` instances\n   *          representing the most relevant documents to the query.\n   */\n  async invoke(\n    input: string,\n    options?: RunnableConfig\n  ): Promise<DocumentInterface<Metadata>[]> {\n    return this.getRelevantDocuments(input, ensureConfig(options));\n  }\n\n  /**\n   * @deprecated Use .invoke() instead. Will be removed in 0.3.0.\n   *\n   * Main method used to retrieve relevant documents. It takes a query\n   * string and an optional configuration object, and returns a promise that\n   * resolves to an array of `Document` objects. This method handles the\n   * retrieval process, including starting and ending callbacks, and error\n   * handling.\n   * @param query The query string to retrieve relevant documents for.\n   * @param config Optional configuration object for the retrieval process.\n   * @returns A promise that resolves to an array of `Document` objects.\n   */\n  async getRelevantDocuments(\n    query: string,\n    config?: Callbacks | BaseCallbackConfig\n  ): Promise<DocumentInterface<Metadata>[]> {\n    const parsedConfig = ensureConfig(parseCallbackConfigArg(config));\n    const callbackManager_ = await CallbackManager.configure(\n      parsedConfig.callbacks,\n      this.callbacks,\n      parsedConfig.tags,\n      this.tags,\n      parsedConfig.metadata,\n      this.metadata,\n      { verbose: this.verbose }\n    );\n    const runManager = await callbackManager_?.handleRetrieverStart(\n      this.toJSON(),\n      query,\n      parsedConfig.runId,\n      undefined,\n      undefined,\n      undefined,\n      parsedConfig.runName\n    );\n    try {\n      const results = await this._getRelevantDocuments(query, runManager);\n      await runManager?.handleRetrieverEnd(results);\n      return results;\n    } catch (error) {\n      await runManager?.handleRetrieverError(error);\n      throw error;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgFA,IAAsB,gBAAtB,cAIU,SAEV;;;;CAIE;;;;CAKA;;;;;CAMA;;;;CAKA;;;;;;;CAQA,YAAYA,QAA6B;EACvC,MAAM,OAAO;EACb,KAAK,YAAY,QAAQ;EACzB,KAAK,OAAO,QAAQ,QAAQ,CAAE;EAC9B,KAAK,WAAW,QAAQ,YAAY,CAAE;EACtC,KAAK,UAAU,QAAQ,WAAW;CACnC;;;;;;;;;;;;;;;;;;;;CAqBD,sBACEC,QACAC,YACwC;AACxC,QAAM,IAAI,MAAM;CACjB;;;;;;;;;;CAWD,MAAM,OACJC,OACAC,SACwC;AACxC,SAAO,KAAK,qBAAqB,OAAO,aAAa,QAAQ,CAAC;CAC/D;;;;;;;;;;;;;CAcD,MAAM,qBACJC,OACAC,QACwC;EACxC,MAAM,eAAe,aAAa,uBAAuB,OAAO,CAAC;EACjE,MAAM,mBAAmB,MAAM,gBAAgB,UAC7C,aAAa,WACb,KAAK,WACL,aAAa,MACb,KAAK,MACL,aAAa,UACb,KAAK,UACL,EAAE,SAAS,KAAK,QAAS,EAC1B;EACD,MAAM,aAAa,MAAM,kBAAkB,qBACzC,KAAK,QAAQ,EACb,OACA,aAAa,OACb,QACA,QACA,QACA,aAAa,QACd;AACD,MAAI;GACF,MAAM,UAAU,MAAM,KAAK,sBAAsB,OAAO,WAAW;GACnE,MAAM,YAAY,mBAAmB,QAAQ;AAC7C,UAAO;EACR,SAAQ,OAAO;GACd,MAAM,YAAY,qBAAqB,MAAM;AAC7C,SAAM;EACP;CACF;AACF"}