@agentica/vector-selector 0.20.0

package/src/tools.ts

@@ -0,0 +1,99 @@
+import type { AgenticaContext } from "@agentica/core";
+
+export const Tools = {
+  extract_query: {
+    type: "function",
+    function: {
+      name: "extract_search_query",
+      description: "extract search query from user message\n",
+      parameters: {
+        type: "object",
+        properties: {
+          query_list: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                reason: {
+                  type: "string",
+                  description: "The reason of the query selection.\n\nJust write the reason why you've determined to select this query.",
+                },
+                query: {
+                  type: "string",
+                  description: "the search query",
+                },
+              },
+              required: ["reason", "query"],
+            },
+          },
+        },
+        required: ["query_list"],
+      },
+    },
+  },
+
+  select_functions: {
+    type: "function",
+    function: {
+      name: "select_functions",
+      description: `Select proper API functions to call.
+
+If you A.I. agent has found some proper API functions to call
+from the conversation with user, please select the API functions
+just by calling this function.
+
+When user wants to call a same function multiply, you A.I. agent must
+list up it multiply in the \`functions\` property. Otherwise the user has
+requested to call many different functions, you A.I. agent have to assign
+them all into the \`functions\` property.
+
+Also, if you A.I. agent can't specify a specific function to call due to lack
+of specificity or homogeneity of candidate functions, just assign all of them
+by in the \`functions\` property too. Instead, when you A.I. agent can specify
+a specific function to call, the others would be eliminated.
+
+@example
+\`\`\`json
+[
+  {
+    "reason": "The user wants to call the function multiply.",
+    "function_name": "get_user_info"
+  },
+  {
+    "reason": "The user wants to modify the user info.",
+    "function_name": "modify_user_info"
+  }
+]
+\`\`\`
+`,
+      parameters: {
+        type: "object",
+        properties: {
+          function_list: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                reason: {
+                  type: "string",
+                  description: "The reason of the function selection.\n\nJust write the reason why you've determined to select this function.",
+                },
+                function_name: {
+                  type: "string",
+                  description: "Name of the target function to call.",
+                },
+              },
+              required: ["reason", "function_name"],
+            },
+          },
+        },
+        required: ["function_list"],
+      },
+    },
+  },
+} as const satisfies Record<
+  string,
+  NonNullable<
+    Parameters<AgenticaContext<"chatgpt">["request"]>[1]["tools"]
+  >[number]
+>;

package/src/utils.test.ts

@@ -0,0 +1,185 @@
+import { getRetry, groupByArray } from "./utils";
+
+describe("getRetry", () => {
+  it("should throw error when count is less than 1", () => {
+    // @ts-expect-error getRetry should throw error when count is not more than 0
+    expect(() => getRetry(0)).toThrow("count should be greater than 0");
+  });
+
+  it("should retry the function specified number of times", async () => {
+    const mockFn = vi.fn().mockImplementation(async () => {
+      if (mockFn.mock.calls.length === 1) {
+        throw new Error("Failed");
+      }
+      return "success";
+    });
+
+    const retryFn = getRetry(3);
+    const result = await retryFn(mockFn);
+
+    expect(result).toBe("success");
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("should throw the last error when all retries fail", async () => {
+    const error = new Error("Failed");
+    const mockFn = vi.fn().mockRejectedValue(error);
+
+    const retryFn = getRetry(3);
+    await expect(retryFn(mockFn)).rejects.toThrow(error);
+    expect(mockFn).toHaveBeenCalledTimes(3);
+  });
+
+  it("should handle noop functions", async () => {
+    const mockFn = vi.fn().mockResolvedValue(undefined);
+    const retryFn = getRetry(3);
+
+    const result = await retryFn(mockFn);
+    expect(result).toBeUndefined();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("should handle non-async functions", async () => {
+    const mockFn: () => string = vi.fn()
+      .mockImplementationOnce(() => { throw new Error("Failed"); })
+      .mockImplementationOnce(() => "success");
+
+    const retryFn = getRetry(3);
+    const result = await retryFn(async () => mockFn());
+
+    expect(result).toBe("success");
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("should stop retrying after successful attempt", async () => {
+    const mockFn = vi.fn()
+      .mockRejectedValueOnce(new Error("Failed"))
+      .mockResolvedValueOnce("success");
+
+    const retryFn = getRetry(5);
+    const result = await retryFn(mockFn);
+
+    expect(result).toBe("success");
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("should handle different types of errors", async () => {
+    const retryFn = getRetry(3);
+
+    await expect(retryFn(async () => {
+      throw new TypeError("Type error");
+    })).rejects.toThrow(TypeError);
+
+    await expect(retryFn(async () => {
+      throw new RangeError("Range error");
+    })).rejects.toThrow(RangeError);
+  });
+
+  it("should handle null and undefined return values", async () => {
+    const retryFn = getRetry(2);
+
+    const nullFn = async () => null;
+    const undefinedFn = async () => undefined;
+
+    expect(await retryFn(nullFn)).toBeNull();
+    expect(await retryFn(undefinedFn)).toBeUndefined();
+  });
+
+  it("should handle floating point calculations", async () => {
+    let attempts = 0;
+    const fn = async () => {
+      attempts++;
+      if (attempts < 2) {
+        throw new Error("Failed");
+      }
+      return 3.14159;
+    };
+
+    const retryFn = getRetry(3);
+    const result = await retryFn(fn);
+    expect(result).toBeCloseTo(3.14159);
+    expect(attempts).toBe(2);
+  });
+
+  it("should handle mathematical operations with floating points", async () => {
+    let attempts = 0;
+    const fn = async () => {
+      attempts++;
+      if (attempts < 2) {
+        throw new Error("Failed");
+      }
+      return 0.1 + 0.2; // Known floating point precision issue
+    };
+
+    const retryFn = getRetry(3);
+    const result = await retryFn(fn);
+    expect(result).toBeCloseTo(0.3);
+    expect(attempts).toBe(2);
+  });
+
+  it("should handle very small floating point numbers", async () => {
+    const retryFn = getRetry(2);
+    const fn = async () => 0.0000001;
+
+    const result = await retryFn(fn);
+    expect(result).toBeCloseTo(0.0000001);
+  });
+
+  it("should handle very large floating point numbers", async () => {
+    const retryFn = getRetry(2);
+    const fn = async () => 1e20;
+
+    const result = await retryFn(fn);
+    expect(result).toBe(1e20);
+  });
+});
+
+describe("groupByArray", () => {
+  it("should group array into chunks of specified size", () => {
+    const array = [1, 2, 3, 4, 5, 6];
+    const result = groupByArray(array, 2);
+    expect(result).toEqual([[1, 2], [3, 4], [5, 6]]);
+  });
+
+  it("should handle array with length not divisible by count", () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = groupByArray(array, 2);
+    expect(result).toEqual([[1, 2], [3, 4], [5]]);
+  });
+
+  it("should return empty array when input array is empty", () => {
+    const result = groupByArray([], 2);
+    expect(result).toEqual([]);
+  });
+
+  it("should handle count larger than array length", () => {
+    const array = [1];
+    const result = groupByArray(array, 2);
+    expect(result).toEqual([[1]]);
+  });
+
+  it("should throw error when count is less than 1", () => {
+    const array = [1, 2, 3, 4, 5];
+    // @ts-expect-error groupByArray should throw error when count is not more than 0
+    expect(() => groupByArray(array, 0)).toThrow("count should be greater than 0");
+  });
+
+  it("should handle array with different data types", () => {
+    const mixedArray = [1, "two", { three: 3 }, [4], true, null, undefined];
+    const result = groupByArray(mixedArray, 2);
+    expect(result).toEqual([
+      [1, "two"],
+      [{ three: 3 }, [4]],
+      [true, null],
+      [undefined],
+    ]);
+  });
+
+  it("should handle very large arrays", () => {
+    const largeArray = Array.from({ length: 1000 }, (_, i) => i);
+    const result = groupByArray(largeArray, 100);
+    expect(result.length).toBe(10);
+    expect(result[0]?.length).toBe(100);
+    expect(result[9]?.length).toBe(100);
+  });
+});

package/src/utils.ts

@@ -0,0 +1,105 @@
+import type { GreaterThan, Integer } from "type-fest";
+
+/** type function to check if a number is greater than 0 */
+type GreaterThanZeroInteger<T extends number> = GreaterThan<Integer<T>, 0> extends true ? T : never;
+
+/**
+ * This function is used to get a retry function.
+ *
+ * It will throw an error if the count is not a number,
+ * or if the count is not a finite number,
+ * or if the count is not an integer,
+ * or if the count is less than 1.
+ *
+ * @param count - The number of times to retry the function.
+ * @returns A retry function.
+ * @throws {TypeError} If the count is not a number, or if the count is not a finite number, or if the count is not an integer, or if the count is less than 1.
+ * @throws {Error} If the function fails to return a value after the specified number of retries.
+ */
+export function getRetry<TCount extends number>(count: GreaterThanZeroInteger<TCount>) {
+  if (count < 1) {
+    throw new Error("count should be greater than 0");
+  }
+
+  return async <T>(fn: () => Promise<T>) => {
+    let lastError: unknown = null;
+
+    for (let i = 0; i < count; i++) {
+      try {
+        return await fn();
+      }
+      catch (e: unknown) {
+        lastError = e;
+        if (i === count - 1) {
+          throw e;
+        }
+      }
+    }
+    // count should be greater than 0.
+    throw lastError;
+  };
+}
+
+/**
+ * This function is used to group an array into a 2-dimensional array.
+ *
+ * It will throw an error if the count is not a number,
+ * or if the count is not a finite number,
+ * or if the count is not an integer,
+ * or if the count is less than 1.
+ *
+ * @param array - The array to group.
+ * @param count - The number of elements in each group.
+ * @returns A 2-dimensional array.
+ */
+export function groupByArray<T, TCount extends number>(array: T[], count: GreaterThanZeroInteger<TCount>): T[][] {
+  if (count < 1) {
+    throw new Error("count should be greater than 0");
+  }
+
+  if (array.length === 0) {
+    return [];
+  }
+
+  if (array.length < count) {
+    return [array];
+  }
+
+  const grouped = [];
+  for (let i = 0; i < array.length; i += count) {
+    grouped.push(array.slice(i, i + count));
+  }
+  return grouped;
+}
+
+/**
+ * Removes duplicates from an array.
+ * You can specify which value to compare using a property selector function.
+ *
+ * @param array - Array to remove duplicates from
+ * @param selector - Function that selects the value to compare
+ * @returns New array with duplicates removed
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { id: 1, name: 'John' },
+ *   { id: 2, name: 'Jane' },
+ *   { id: 1, name: 'John' }
+ * ];
+ *
+ * const uniqueUsers = uniqBy(users, user => user.id);
+ * // Result: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+ * ```
+ */
+export function uniqBy<T, K>(array: T[], selector: (item: T) => K): T[] {
+  const seen = new Set<K>();
+  return array.filter((item) => {
+    const key = selector(item);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}