index.cjs 5.6 KB

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