index.d.ts 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
  1. import { BaseCallbackConfig, CallbackManagerForRetrieverRun, Callbacks } from "../callbacks/manager.js";
  2. import type { DocumentInterface } from "../documents/document.js";
  3. import { Runnable, type RunnableInterface } from "../runnables/base.js";
  4. import { RunnableConfig } from "../runnables/config.js";
  5. /**
  6. * Input configuration options for initializing a retriever that extends
  7. * the `BaseRetriever` class. This interface provides base properties
  8. * common to all retrievers, allowing customization of callback functions,
  9. * tagging, metadata, and logging verbosity.
  10. *
  11. * Fields:
  12. * - `callbacks` (optional): An array of callback functions that handle various
  13. * events during retrieval, such as logging, error handling, or progress updates.
  14. *
  15. * - `tags` (optional): An array of strings used to add contextual tags to
  16. * retrieval operations, allowing for easier categorization and tracking.
  17. *
  18. * - `metadata` (optional): A record of key-value pairs to store additional
  19. * contextual information for retrieval operations, which can be useful
  20. * for logging or auditing purposes.
  21. *
  22. * - `verbose` (optional): A boolean flag that, if set to `true`, enables
  23. * detailed logging and output during the retrieval process. Defaults to `false`.
  24. */
  25. export interface BaseRetrieverInput {
  26. callbacks?: Callbacks;
  27. tags?: string[];
  28. metadata?: Record<string, unknown>;
  29. verbose?: boolean;
  30. }
  31. /**
  32. * Interface for a base retriever that defines core functionality for
  33. * retrieving relevant documents from a source based on a query.
  34. *
  35. * The `BaseRetrieverInterface` standardizes the `getRelevantDocuments` method,
  36. * enabling retrieval of documents that match the query criteria.
  37. *
  38. * @template Metadata - The type of metadata associated with each document,
  39. * defaulting to `Record<string, any>`.
  40. */
  41. export interface BaseRetrieverInterface<Metadata extends Record<string, any> = Record<string, any>> extends RunnableInterface<string, DocumentInterface<Metadata>[]> {
  42. /**
  43. * Retrieves documents relevant to a given query, allowing optional
  44. * configurations for customization.
  45. *
  46. * @param query - A string representing the query to search for relevant documents.
  47. * @param config - (optional) Configuration options for the retrieval process,
  48. * which may include callbacks and additional context settings.
  49. * @returns A promise that resolves to an array of `DocumentInterface` instances,
  50. * each containing metadata specified by the `Metadata` type parameter.
  51. */
  52. getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
  53. }
  54. /**
  55. * Abstract base class for a document retrieval system, designed to
  56. * process string queries and return the most relevant documents from a source.
  57. *
  58. * `BaseRetriever` provides common properties and methods for derived retrievers,
  59. * such as callbacks, tagging, and verbose logging. Custom retrieval systems
  60. * should extend this class and implement `_getRelevantDocuments` to define
  61. * the specific retrieval logic.
  62. *
  63. * @template Metadata - The type of metadata associated with each document,
  64. * defaulting to `Record<string, any>`.
  65. */
  66. export declare abstract class BaseRetriever<Metadata extends Record<string, any> = Record<string, any>> extends Runnable<string, DocumentInterface<Metadata>[]> implements BaseRetrieverInterface {
  67. /**
  68. * Optional callbacks to handle various events in the retrieval process.
  69. */
  70. callbacks?: Callbacks;
  71. /**
  72. * Tags to label or categorize the retrieval operation.
  73. */
  74. tags?: string[];
  75. /**
  76. * Metadata to provide additional context or information about the retrieval
  77. * operation.
  78. */
  79. metadata?: Record<string, unknown>;
  80. /**
  81. * If set to `true`, enables verbose logging for the retrieval process.
  82. */
  83. verbose?: boolean;
  84. /**
  85. * Constructs a new `BaseRetriever` instance with optional configuration fields.
  86. *
  87. * @param fields - Optional input configuration that can include `callbacks`,
  88. * `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
  89. */
  90. constructor(fields?: BaseRetrieverInput);
  91. /**
  92. * TODO: This should be an abstract method, but we'd like to avoid breaking
  93. * changes to people currently using subclassed custom retrievers.
  94. * Change it on next major release.
  95. */
  96. /**
  97. * Placeholder method for retrieving relevant documents based on a query.
  98. *
  99. * This method is intended to be implemented by subclasses and will be
  100. * converted to an abstract method in the next major release. Currently, it
  101. * throws an error if not implemented, ensuring that custom retrievers define
  102. * the specific retrieval logic.
  103. *
  104. * @param _query - The query string used to search for relevant documents.
  105. * @param _callbacks - (optional) Callback manager for managing callbacks
  106. * during retrieval.
  107. * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
  108. * @throws {Error} Throws an error indicating the method is not implemented.
  109. */
  110. _getRelevantDocuments(_query: string, _callbacks?: CallbackManagerForRetrieverRun): Promise<DocumentInterface<Metadata>[]>;
  111. /**
  112. * Executes a retrieval operation.
  113. *
  114. * @param input - The query string used to search for relevant documents.
  115. * @param options - (optional) Configuration options for the retrieval run,
  116. * which may include callbacks, tags, and metadata.
  117. * @returns A promise that resolves to an array of `DocumentInterface` instances
  118. * representing the most relevant documents to the query.
  119. */
  120. invoke(input: string, options?: RunnableConfig): Promise<DocumentInterface<Metadata>[]>;
  121. /**
  122. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  123. *
  124. * Main method used to retrieve relevant documents. It takes a query
  125. * string and an optional configuration object, and returns a promise that
  126. * resolves to an array of `Document` objects. This method handles the
  127. * retrieval process, including starting and ending callbacks, and error
  128. * handling.
  129. * @param query The query string to retrieve relevant documents for.
  130. * @param config Optional configuration object for the retrieval process.
  131. * @returns A promise that resolves to an array of `Document` objects.
  132. */
  133. getRelevantDocuments(query: string, config?: Callbacks | BaseCallbackConfig): Promise<DocumentInterface<Metadata>[]>;
  134. }