index.js 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127
  1. import { CallbackManager, parseCallbackConfigArg, } from "../callbacks/manager.js";
  2. import { Runnable } from "../runnables/base.js";
  3. import { ensureConfig } from "../runnables/config.js";
  4. /**
  5. * Abstract base class for a document retrieval system, designed to
  6. * process string queries and return the most relevant documents from a source.
  7. *
  8. * `BaseRetriever` provides common properties and methods for derived retrievers,
  9. * such as callbacks, tagging, and verbose logging. Custom retrieval systems
  10. * should extend this class and implement `_getRelevantDocuments` to define
  11. * the specific retrieval logic.
  12. *
  13. * @template Metadata - The type of metadata associated with each document,
  14. * defaulting to `Record<string, any>`.
  15. */
  16. export class BaseRetriever extends Runnable {
  17. /**
  18. * Constructs a new `BaseRetriever` instance with optional configuration fields.
  19. *
  20. * @param fields - Optional input configuration that can include `callbacks`,
  21. * `tags`, `metadata`, and `verbose` settings for custom retriever behavior.
  22. */
  23. constructor(fields) {
  24. super(fields);
  25. /**
  26. * Optional callbacks to handle various events in the retrieval process.
  27. */
  28. Object.defineProperty(this, "callbacks", {
  29. enumerable: true,
  30. configurable: true,
  31. writable: true,
  32. value: void 0
  33. });
  34. /**
  35. * Tags to label or categorize the retrieval operation.
  36. */
  37. Object.defineProperty(this, "tags", {
  38. enumerable: true,
  39. configurable: true,
  40. writable: true,
  41. value: void 0
  42. });
  43. /**
  44. * Metadata to provide additional context or information about the retrieval
  45. * operation.
  46. */
  47. Object.defineProperty(this, "metadata", {
  48. enumerable: true,
  49. configurable: true,
  50. writable: true,
  51. value: void 0
  52. });
  53. /**
  54. * If set to `true`, enables verbose logging for the retrieval process.
  55. */
  56. Object.defineProperty(this, "verbose", {
  57. enumerable: true,
  58. configurable: true,
  59. writable: true,
  60. value: void 0
  61. });
  62. this.callbacks = fields?.callbacks;
  63. this.tags = fields?.tags ?? [];
  64. this.metadata = fields?.metadata ?? {};
  65. this.verbose = fields?.verbose ?? false;
  66. }
  67. /**
  68. * TODO: This should be an abstract method, but we'd like to avoid breaking
  69. * changes to people currently using subclassed custom retrievers.
  70. * Change it on next major release.
  71. */
  72. /**
  73. * Placeholder method for retrieving relevant documents based on a query.
  74. *
  75. * This method is intended to be implemented by subclasses and will be
  76. * converted to an abstract method in the next major release. Currently, it
  77. * throws an error if not implemented, ensuring that custom retrievers define
  78. * the specific retrieval logic.
  79. *
  80. * @param _query - The query string used to search for relevant documents.
  81. * @param _callbacks - (optional) Callback manager for managing callbacks
  82. * during retrieval.
  83. * @returns A promise resolving to an array of `DocumentInterface` instances relevant to the query.
  84. * @throws {Error} Throws an error indicating the method is not implemented.
  85. */
  86. _getRelevantDocuments(_query, _callbacks) {
  87. throw new Error("Not implemented!");
  88. }
  89. /**
  90. * Executes a retrieval operation.
  91. *
  92. * @param input - The query string used to search for relevant documents.
  93. * @param options - (optional) Configuration options for the retrieval run,
  94. * which may include callbacks, tags, and metadata.
  95. * @returns A promise that resolves to an array of `DocumentInterface` instances
  96. * representing the most relevant documents to the query.
  97. */
  98. async invoke(input, options) {
  99. return this.getRelevantDocuments(input, ensureConfig(options));
  100. }
  101. /**
  102. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  103. *
  104. * Main method used to retrieve relevant documents. It takes a query
  105. * string and an optional configuration object, and returns a promise that
  106. * resolves to an array of `Document` objects. This method handles the
  107. * retrieval process, including starting and ending callbacks, and error
  108. * handling.
  109. * @param query The query string to retrieve relevant documents for.
  110. * @param config Optional configuration object for the retrieval process.
  111. * @returns A promise that resolves to an array of `Document` objects.
  112. */
  113. async getRelevantDocuments(query, config) {
  114. const parsedConfig = ensureConfig(parseCallbackConfigArg(config));
  115. const callbackManager_ = await CallbackManager.configure(parsedConfig.callbacks, this.callbacks, parsedConfig.tags, this.tags, parsedConfig.metadata, this.metadata, { verbose: this.verbose });
  116. const runManager = await callbackManager_?.handleRetrieverStart(this.toJSON(), query, parsedConfig.runId, undefined, undefined, undefined, parsedConfig.runName);
  117. try {
  118. const results = await this._getRelevantDocuments(query, runManager);
  119. await runManager?.handleRetrieverEnd(results);
  120. return results;
  121. }
  122. catch (error) {
  123. await runManager?.handleRetrieverError(error);
  124. throw error;
  125. }
  126. }
  127. }