Rename methods

Author: Dan Jones

src/query/agent.test.ts

@@ -114,7 +114,7 @@ it("prepareSearch returns a QueryAgentSearcher", async () => {
     systemPrompt: "test system prompt",
   });
 
-  const searcher = agent.prepareSearch("test query");
+  const searcher = agent.configureSearch("test query");
   expect(searcher).toBeInstanceOf(QueryAgentSearcher);
 });
 
@@ -196,11 +196,11 @@ it("search-only mode success: caches searches and sends on subsequent request",
   }) as jest.Mock;
 
   const agent = new QueryAgent(mockClient);
-  const searcher = agent.prepareSearch("test query", {
+  const searcher = agent.configureSearch("test query", {
     collections: ["test_collection"],
   });
 
-  const first = await searcher.execute({ limit: 2, offset: 0 });
+  const first = await searcher.run({ limit: 2, offset: 0 });
 
   expect(first).toEqual<SearchModeResponse<undefined>>({
     originalQuery: apiSuccess.original_query,
@@ -234,7 +234,7 @@ it("search-only mode success: caches searches and sends on subsequent request",
 
   // First request should have searches: null (generation request)
   expect(capturedBodies[0].searches).toBeNull();
-  const second = await searcher.execute({ limit: 2, offset: 1 });
+  const second = await searcher.run({ limit: 2, offset: 1 });
   // Second request should include the original searches (execution request)
   expect(capturedBodies[1].searches).toEqual(apiSuccess.searches);
   // Response mapping should be the same (because response is mocked)
@@ -266,12 +266,12 @@ it("search-only mode failure propagates QueryAgentError", async () => {
   ) as jest.Mock;
 
   const agent = new QueryAgent(mockClient);
-  const searcher = agent.prepareSearch("test query", {
+  const searcher = agent.configureSearch("test query", {
     collections: ["test_collection"],
   });
 
   try {
-    await searcher.execute({ limit: 2, offset: 0 });
+    await searcher.run({ limit: 2, offset: 0 });
   } catch (err) {
     expect(err).toBeInstanceOf(QueryAgentError);
     expect(err).toMatchObject({

src/query/agent.ts

@@ -188,13 +188,21 @@ export class QueryAgent {
   }
 
   /**
-   * Prepare a searcher for the query agent.
+   * Configure a QueryAgentSearcher for the search-only mode of the query agent.
+   *
+   * This returns a configured QueryAgentSearcher, but does not send any requests or
+   * run the agent. To do that, you should call the `run` method on the searcher.
+   *
+   * This allows you to paginate through a consistent results set, as calling the
+   * `run` method on the searcher multiple times will result in the same underlying
+   * searches being performed each time.
    *
    * @param query - The natural language query string for the agent.
-   * @param options - Additional options for the searcher.
-   * @returns The searcher for the query agent.
+   * @param options - Additional options for configuring the searcher.
+   * @param options.collections - The collections to query. Will override any collections if passed in the constructor.
+   * @returns A configured QueryAgentSearcher for the search-only mode of the query agent.
    */
-  prepareSearch<T = undefined>(
+  configureSearch<T = undefined>(
     query: string,
     { collections }: QueryAgentSearchOnlyOptions = {},
   ): QueryAgentSearcher<T> {

src/query/search.ts

@@ -11,6 +11,12 @@ import {
 /**
  * A configured searcher for the QueryAgent.
  *
+ * This is configured using the `QueryAgent.configureSearch` method, which builds this class
+ * but does not send any requests and run the agent. The configured search can then be run
+ * using the `run` method. You can paginate through the results set by running the `run` method
+ * multiple times on the same searcher instance, but with different `limit` / `offset` values;
+ * this will result in the same underlying searches being performed each time.
+ *
  * Warning:
  * Weaviate Agents - Query Agent is an early stage alpha product.
  * The API is subject to breaking changes. Please ensure you are using the latest version of the client.
@@ -82,9 +88,19 @@ export class QueryAgentSearcher<T> {
     };
   }
 
-  async execute(
-    options: SearchExecutionOptions,
-  ): Promise<SearchModeResponse<T>> {
+  /**
+   * Run the search-only agent with the given limit and offset values.
+   *
+   * Calling this method multiple times on the same QueryAgentSearcher instance will result
+   * in the same underlying searches being performed each time, allowing you to paginate
+   * over a consistent results set.
+   *
+   * @param options - Options for executing the search
+   * @param options.limit - The maximum number of results to return. Defaults to 20 if not specified.
+   * @param options.offset - The offset to start from. If not specified, retrieval begins from the first object.
+   * @returns A SearchModeResponse object containing the results, usage, and underlying searches performed.
+   */
+  async run(options: SearchExecutionOptions): Promise<SearchModeResponse<T>> {
     if (!this.collections || this.collections.length === 0) {
       throw Error("No collections provided to the query agent.");
     }