@livekit/agents 0.7.9 → 1.0.0-next.0

package/dist/llm/tool_context.js

@@ -0,0 +1,80 @@
+import { ZodObject, ZodType, z } from "zod";
+const TOOL_SYMBOL = Symbol("tool");
+const FUNCTION_TOOL_SYMBOL = Symbol("function_tool");
+const PROVIDER_DEFINED_TOOL_SYMBOL = Symbol("provider_defined_tool");
+const TOOL_ERROR_SYMBOL = Symbol("tool_error");
+const HANDOFF_SYMBOL = Symbol("handoff");
+class ToolError extends Error {
+  constructor(message) {
+    super(message);
+    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {
+      value: true
+    });
+  }
+}
+function handoff(options) {
+  return {
+    agent: options.agent,
+    returns: options.returns,
+    [HANDOFF_SYMBOL]: true
+  };
+}
+function tool(tool2) {
+  if (tool2.execute !== void 0) {
+    const parameters = tool2.parameters ?? z.object({});
+    if (parameters instanceof ZodType && parameters._def.typeName !== "ZodObject") {
+      throw new Error("Tool parameters must be a Zod object schema (z.object(...))");
+    }
+    if (!(parameters instanceof ZodObject) && !(typeof parameters === "object")) {
+      throw new Error("Tool parameters must be a Zod object schema or a raw JSON schema");
+    }
+    return {
+      type: "function",
+      description: tool2.description,
+      parameters,
+      execute: tool2.execute,
+      [TOOL_SYMBOL]: true,
+      [FUNCTION_TOOL_SYMBOL]: true
+    };
+  }
+  if (tool2.config !== void 0 && tool2.id !== void 0) {
+    return {
+      type: "provider-defined",
+      id: tool2.id,
+      config: tool2.config,
+      [TOOL_SYMBOL]: true,
+      [PROVIDER_DEFINED_TOOL_SYMBOL]: true
+    };
+  }
+  throw new Error("Invalid tool");
+}
+function isTool(tool2) {
+  return tool2 && tool2[TOOL_SYMBOL] === true;
+}
+function isFunctionTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isFunctionTool2 = tool2[FUNCTION_TOOL_SYMBOL] === true;
+  return isTool2 && isFunctionTool2;
+}
+function isProviderDefinedTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isProviderDefinedTool2 = tool2[PROVIDER_DEFINED_TOOL_SYMBOL] === true;
+  return isTool2 && isProviderDefinedTool2;
+}
+function isToolError(error) {
+  return error && error[TOOL_ERROR_SYMBOL] === true;
+}
+function isAgentHandoff(handoff2) {
+  return handoff2 && handoff2[HANDOFF_SYMBOL] === true;
+}
+export {
+  ToolError,
+  handoff,
+  isAgentHandoff,
+  isFunctionTool,
+  isProviderDefinedTool,
+  isTool,
+  isToolError,
+  tool
+};
+//# sourceMappingURL=tool_context.js.map

package/dist/llm/tool_context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/tool_context.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JSONSchema7 } from 'json-schema';\nimport { ZodObject, ZodType, z } from 'zod';\nimport type { Agent } from '../voice/agent.js';\nimport type { RunContext, UnknownUserData } from '../voice/run_context.js';\n\n// heavily inspired by Vercel AI's `tool()`:\n// https://github.com/vercel/ai/blob/3b0983b/packages/ai/core/tool/tool.ts\n\nconst TOOL_SYMBOL = Symbol('tool');\nconst FUNCTION_TOOL_SYMBOL = Symbol('function_tool');\nconst PROVIDER_DEFINED_TOOL_SYMBOL = Symbol('provider_defined_tool');\nconst TOOL_ERROR_SYMBOL = Symbol('tool_error');\nconst HANDOFF_SYMBOL = Symbol('handoff');\n\nexport type JSONValue = null | string | number | boolean | JSONObject | JSONArray;\n\nexport type JSONArray = JSONValue[];\n\nexport type JSONObject = {\n  [key: string]: JSONValue;\n};\n\n// TODO(AJS-111): support Zod cross-version compatibility, raw JSON schema, both strict and non-strict versions\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ToolInputSchema<T extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;\n\nexport type ToolType = 'function' | 'provider-defined';\n\nexport type ToolChoice =\n  | 'auto'\n  | 'none'\n  | 'required'\n  | {\n      type: 'function';\n      function: {\n        name: string;\n      };\n    };\n\nexport class ToolError extends Error {\n  constructor(message: string) {\n    super(message);\n\n    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {\n      value: true,\n    });\n  }\n}\n\nexport interface AgentHandoff {\n  /**\n   * The agent to handoff to.\n   */\n  agent: Agent;\n\n  /**\n   * The return value of the tool.\n   */\n  returns?: any; // eslint-disable-line @typescript-eslint/no-explicit-any\n\n  [HANDOFF_SYMBOL]: true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function handoff(options: { agent: Agent; returns?: any }): AgentHandoff {\n  return {\n    agent: options.agent,\n    returns: options.returns,\n    [HANDOFF_SYMBOL]: true,\n  };\n}\n\nexport interface ToolOptions<UserData = UnknownUserData> {\n  /**\n   * RunContext for the current agent session.\n   */\n  ctx: RunContext<UserData>;\n\n  /**\n   * The ID of the tool call.\n   */\n  toolCallId: string;\n\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\nexport type ToolExecuteFunction<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> = (args: Parameters, opts: ToolOptions<UserData>) => Promise<Result>;\n\nexport interface Tool {\n  /**\n   * The type of the tool.\n   * @internal Either user-defined core tool or provider-defined tool.\n   */\n  type: ToolType;\n\n  [TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools\nexport interface ProviderDefinedTool extends Tool {\n  type: 'provider-defined';\n\n  /**\n   * The ID of the tool.\n   */\n  id: string;\n\n  /**\n   * The configuration of the tool.\n   */\n  config: Record<string, unknown>;\n\n  [PROVIDER_DEFINED_TOOL_SYMBOL]: true;\n}\n\nexport interface FunctionTool<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> extends Tool {\n  type: 'function';\n\n  /**\n   * The description of the tool. Will be used by the language model to decide whether to use the tool.\n   */\n  description: string;\n\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  parameters: ToolInputSchema<Parameters>;\n\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * It also carries context about current session, user-defined data, and the tool call id, etc.\n   */\n  execute: ToolExecuteFunction<Parameters, UserData, Result>;\n\n  [FUNCTION_TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools in the future)\nexport type ToolContext<UserData = UnknownUserData> = {\n  [name: string]: FunctionTool<any, UserData, any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n};\n\n/**\n * Create a function tool.\n *\n * @param description - The description of the tool.\n * @param parameters - The schema of the input that the tool expects. If not provided, defaults to z.object({}).\n * @param execute - The function that is called with the arguments from the tool call and produces a result.\n */\nexport function tool<\n  Parameters extends JSONObject = Record<string, never>,\n  UserData = UnknownUserData,\n  Result = unknown,\n>({\n  description,\n  parameters,\n  execute,\n}: {\n  description: string;\n  parameters?: ToolInputSchema<Parameters>;\n  execute: ToolExecuteFunction<Parameters, UserData, Result>;\n}): FunctionTool<Parameters, UserData, Result>;\n\n/**\n * Create a provider-defined tool.\n *\n * @param id - The ID of the tool.\n * @param config - The configuration of the tool.\n */\nexport function tool({\n  id,\n  config,\n}: {\n  id: string;\n  config: Record<string, unknown>;\n}): ProviderDefinedTool;\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function tool(tool: any): any {\n  if (tool.execute !== undefined) {\n    // Default parameters to z.object({}) if not provided\n    const parameters = tool.parameters ?? z.object({});\n\n    // if parameters is not zod object, throw an error\n    if (parameters instanceof ZodType && parameters._def.typeName !== 'ZodObject') {\n      throw new Error('Tool parameters must be a Zod object schema (z.object(...))');\n    }\n\n    if (!(parameters instanceof ZodObject) && !(typeof parameters === 'object')) {\n      throw new Error('Tool parameters must be a Zod object schema or a raw JSON schema');\n    }\n\n    return {\n      type: 'function',\n      description: tool.description,\n      parameters,\n      execute: tool.execute,\n      [TOOL_SYMBOL]: true,\n      [FUNCTION_TOOL_SYMBOL]: true,\n    };\n  }\n\n  if (tool.config !== undefined && tool.id !== undefined) {\n    return {\n      type: 'provider-defined',\n      id: tool.id,\n      config: tool.config,\n      [TOOL_SYMBOL]: true,\n      [PROVIDER_DEFINED_TOOL_SYMBOL]: true,\n    };\n  }\n\n  throw new Error('Invalid tool');\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isTool(tool: any): tool is Tool {\n  return tool && tool[TOOL_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isFunctionTool(tool: any): tool is FunctionTool<any, any, any> {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isFunctionTool = tool[FUNCTION_TOOL_SYMBOL] === true;\n  return isTool && isFunctionTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isProviderDefinedTool(tool: any): tool is ProviderDefinedTool {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isProviderDefinedTool = tool[PROVIDER_DEFINED_TOOL_SYMBOL] === true;\n  return isTool && isProviderDefinedTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isToolError(error: any): error is ToolError {\n  return error && error[TOOL_ERROR_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isAgentHandoff(handoff: any): handoff is AgentHandoff {\n  return handoff && handoff[HANDOFF_SYMBOL] === true;\n}\n"],"mappings":"AAIA,SAAS,WAAW,SAAS,SAAS;AAOtC,MAAM,cAAc,OAAO,MAAM;AACjC,MAAM,uBAAuB,OAAO,eAAe;AACnD,MAAM,+BAA+B,OAAO,uBAAuB;AACnE,MAAM,oBAAoB,OAAO,YAAY;AAC7C,MAAM,iBAAiB,OAAO,SAAS;AA2BhC,MAAM,kBAAkB,MAAM;AAAA,EACnC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AAEb,WAAO,eAAe,MAAM,mBAAmB;AAAA,MAC7C,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;AAiBO,SAAS,QAAQ,SAAwD;AAC9E,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf,SAAS,QAAQ;AAAA,IACjB,CAAC,cAAc,GAAG;AAAA,EACpB;AACF;AAyHO,SAAS,KAAKA,OAAgB;AACnC,MAAIA,MAAK,YAAY,QAAW;AAE9B,UAAM,aAAaA,MAAK,cAAc,EAAE,OAAO,CAAC,CAAC;AAGjD,QAAI,sBAAsB,WAAW,WAAW,KAAK,aAAa,aAAa;AAC7E,YAAM,IAAI,MAAM,6DAA6D;AAAA,IAC/E;AAEA,QAAI,EAAE,sBAAsB,cAAc,EAAE,OAAO,eAAe,WAAW;AAC3E,YAAM,IAAI,MAAM,kEAAkE;AAAA,IACpF;AAEA,WAAO;AAAA,MACL,MAAM;AAAA,MACN,aAAaA,MAAK;AAAA,MAClB;AAAA,MACA,SAASA,MAAK;AAAA,MACd,CAAC,WAAW,GAAG;AAAA,MACf,CAAC,oBAAoB,GAAG;AAAA,IAC1B;AAAA,EACF;AAEA,MAAIA,MAAK,WAAW,UAAaA,MAAK,OAAO,QAAW;AACtD,WAAO;AAAA,MACL,MAAM;AAAA,MACN,IAAIA,MAAK;AAAA,MACT,QAAQA,MAAK;AAAA,MACb,CAAC,WAAW,GAAG;AAAA,MACf,CAAC,4BAA4B,GAAG;AAAA,IAClC;AAAA,EACF;AAEA,QAAM,IAAI,MAAM,cAAc;AAChC;AAGO,SAAS,OAAOA,OAAyB;AAC9C,SAAOA,SAAQA,MAAK,WAAW,MAAM;AACvC;AAGO,SAAS,eAAeA,OAAgD;AAC7E,QAAMC,UAASD,SAAQA,MAAK,WAAW,MAAM;AAC7C,QAAME,kBAAiBF,MAAK,oBAAoB,MAAM;AACtD,SAAOC,WAAUC;AACnB;AAGO,SAAS,sBAAsBF,OAAwC;AAC5E,QAAMC,UAASD,SAAQA,MAAK,WAAW,MAAM;AAC7C,QAAMG,yBAAwBH,MAAK,4BAA4B,MAAM;AACrE,SAAOC,WAAUE;AACnB;AAGO,SAAS,YAAY,OAAgC;AAC1D,SAAO,SAAS,MAAM,iBAAiB,MAAM;AAC/C;AAGO,SAAS,eAAeC,UAAuC;AACpE,SAAOA,YAAWA,SAAQ,cAAc,MAAM;AAChD;","names":["tool","isTool","isFunctionTool","isProviderDefinedTool","handoff"]}

package/dist/llm/tool_context.test.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var import_vitest = require("vitest");
+var import_zod = require("zod");
+var import_tool_context = require("./tool_context.cjs");
+var import_utils = require("./utils.cjs");
+(0, import_vitest.describe)("Tool Context", () => {
+  (0, import_vitest.describe)("oaiParams", () => {
+    (0, import_vitest.it)("should handle basic object schema", () => {
+      const schema = import_zod.z.object({
+        name: import_zod.z.string().describe("The user name"),
+        age: import_zod.z.number().describe("The user age")
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+    (0, import_vitest.it)("should handle enum fields", () => {
+      const schema = import_zod.z.object({
+        color: import_zod.z.enum(["red", "blue", "green"]).describe("Choose a color")
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+    (0, import_vitest.it)("should handle array fields", () => {
+      const schema = import_zod.z.object({
+        tags: import_zod.z.array(import_zod.z.string()).describe("List of tags")
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+    (0, import_vitest.it)("should handle array of enums", () => {
+      const schema = import_zod.z.object({
+        colors: import_zod.z.array(import_zod.z.enum(["red", "blue", "green"])).describe("List of colors")
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+    (0, import_vitest.it)("should handle optional fields", () => {
+      const schema = import_zod.z.object({
+        name: import_zod.z.string().describe("The user name"),
+        age: import_zod.z.number().optional().describe("The user age")
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+    (0, import_vitest.it)("should handle fields without descriptions", () => {
+      const schema = import_zod.z.object({
+        name: import_zod.z.string(),
+        age: import_zod.z.number()
+      });
+      const result = (0, import_utils.oaiParams)(schema);
+      (0, import_vitest.expect)(result).toMatchSnapshot();
+    });
+  });
+  (0, import_vitest.describe)("tool", () => {
+    (0, import_vitest.it)("should create and execute a basic core tool", async () => {
+      const getWeather = (0, import_tool_context.tool)({
+        description: "Get the weather for a given location",
+        parameters: import_zod.z.object({
+          location: import_zod.z.string()
+        }),
+        execute: async ({ location }, { ctx }) => {
+          return `The weather in ${location} is sunny, ${ctx.userData.name}`;
+        }
+      });
+      const result = await getWeather.execute(
+        { location: "San Francisco" },
+        (0, import_utils.createToolOptions)("123", { name: "John" })
+      );
+      (0, import_vitest.expect)(result).toBe("The weather in San Francisco is sunny, John");
+    });
+    (0, import_vitest.it)("should properly type a callable function", async () => {
+      const testFunction = (0, import_tool_context.tool)({
+        description: "Test function",
+        parameters: import_zod.z.object({
+          name: import_zod.z.string().describe("The user name"),
+          age: import_zod.z.number().describe("The user age")
+        }),
+        execute: async (args) => {
+          return `${args.name} is ${args.age} years old`;
+        }
+      });
+      const result = await testFunction.execute(
+        { name: "John", age: 30 },
+        (0, import_utils.createToolOptions)("123")
+      );
+      (0, import_vitest.expect)(result).toBe("John is 30 years old");
+    });
+    (0, import_vitest.it)("should handle async execution", async () => {
+      const testFunction = (0, import_tool_context.tool)({
+        description: "Async test function",
+        parameters: import_zod.z.object({
+          delay: import_zod.z.number().describe("Delay in milliseconds")
+        }),
+        execute: async (args) => {
+          await new Promise((resolve) => setTimeout(resolve, args.delay));
+          return args.delay;
+        }
+      });
+      const start = Date.now();
+      const result = await testFunction.execute({ delay: 100 }, (0, import_utils.createToolOptions)("123"));
+      const duration = Date.now() - start;
+      (0, import_vitest.expect)(result).toBe(100);
+      (0, import_vitest.expect)(duration).toBeGreaterThanOrEqual(95);
+    });
+    (0, import_vitest.describe)("nested array support", () => {
+      (0, import_vitest.it)("should handle nested array fields", () => {
+        const schema = import_zod.z.object({
+          items: import_zod.z.array(
+            import_zod.z.object({
+              name: import_zod.z.string().describe("the item name"),
+              modifiers: import_zod.z.array(
+                import_zod.z.object({
+                  modifier_name: import_zod.z.string(),
+                  modifier_value: import_zod.z.string()
+                })
+              ).describe("list of the modifiers applied on this item, such as size")
+            })
+          )
+        });
+        const result = (0, import_utils.oaiParams)(schema);
+        (0, import_vitest.expect)(result).toMatchSnapshot();
+      });
+    });
+    (0, import_vitest.describe)("optional parameters", () => {
+      (0, import_vitest.it)("should create a tool without parameters", async () => {
+        const simpleAction = (0, import_tool_context.tool)({
+          description: "Perform a simple action",
+          execute: async () => {
+            return "Action performed";
+          }
+        });
+        (0, import_vitest.expect)(simpleAction.type).toBe("function");
+        (0, import_vitest.expect)(simpleAction.description).toBe("Perform a simple action");
+        (0, import_vitest.expect)(simpleAction.parameters).toBeDefined();
+        (0, import_vitest.expect)(simpleAction.parameters._def.typeName).toBe("ZodObject");
+        const result = await simpleAction.execute({}, (0, import_utils.createToolOptions)("123"));
+        (0, import_vitest.expect)(result).toBe("Action performed");
+      });
+      (0, import_vitest.it)("should handle tools with context but no parameters", async () => {
+        const greetUser = (0, import_tool_context.tool)({
+          description: "Greet the current user",
+          execute: async (_, { ctx }) => {
+            return `Hello, ${ctx.userData.username}!`;
+          }
+        });
+        const result = await greetUser.execute({}, (0, import_utils.createToolOptions)("123", { username: "Alice" }));
+        (0, import_vitest.expect)(result).toBe("Hello, Alice!");
+      });
+      (0, import_vitest.it)("should create a tool that accesses tool call id without parameters", async () => {
+        const getCallId = (0, import_tool_context.tool)({
+          description: "Get the current tool call ID",
+          execute: async (_, { toolCallId }) => {
+            return `Tool call ID: ${toolCallId}`;
+          }
+        });
+        const result = await getCallId.execute({}, (0, import_utils.createToolOptions)("test-id-456"));
+        (0, import_vitest.expect)(result).toBe("Tool call ID: test-id-456");
+      });
+    });
+  });
+});
+//# sourceMappingURL=tool_context.test.cjs.map

package/dist/llm/tool_context.test.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/tool_context.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { describe, expect, it } from 'vitest';\nimport { z } from 'zod';\nimport { type ToolOptions, tool } from './tool_context.js';\nimport { createToolOptions, oaiParams } from './utils.js';\n\ndescribe('Tool Context', () => {\n  describe('oaiParams', () => {\n    it('should handle basic object schema', () => {\n      const schema = z.object({\n        name: z.string().describe('The user name'),\n        age: z.number().describe('The user age'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle enum fields', () => {\n      const schema = z.object({\n        color: z.enum(['red', 'blue', 'green']).describe('Choose a color'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle array fields', () => {\n      const schema = z.object({\n        tags: z.array(z.string()).describe('List of tags'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle array of enums', () => {\n      const schema = z.object({\n        colors: z.array(z.enum(['red', 'blue', 'green'])).describe('List of colors'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle optional fields', () => {\n      const schema = z.object({\n        name: z.string().describe('The user name'),\n        age: z.number().optional().describe('The user age'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle fields without descriptions', () => {\n      const schema = z.object({\n        name: z.string(),\n        age: z.number(),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n  });\n\n  describe('tool', () => {\n    it('should create and execute a basic core tool', async () => {\n      const getWeather = tool({\n        description: 'Get the weather for a given location',\n        parameters: z.object({\n          location: z.string(),\n        }),\n        execute: async ({ location }, { ctx }: ToolOptions<{ name: string }>) => {\n          return `The weather in ${location} is sunny, ${ctx.userData.name}`;\n        },\n      });\n\n      const result = await getWeather.execute(\n        { location: 'San Francisco' },\n        createToolOptions('123', { name: 'John' }),\n      );\n      expect(result).toBe('The weather in San Francisco is sunny, John');\n    });\n\n    it('should properly type a callable function', async () => {\n      const testFunction = tool({\n        description: 'Test function',\n        parameters: z.object({\n          name: z.string().describe('The user name'),\n          age: z.number().describe('The user age'),\n        }),\n        execute: async (args) => {\n          return `${args.name} is ${args.age} years old`;\n        },\n      });\n\n      const result = await testFunction.execute(\n        { name: 'John', age: 30 },\n        createToolOptions('123'),\n      );\n      expect(result).toBe('John is 30 years old');\n    });\n\n    it('should handle async execution', async () => {\n      const testFunction = tool({\n        description: 'Async test function',\n        parameters: z.object({\n          delay: z.number().describe('Delay in milliseconds'),\n        }),\n        execute: async (args) => {\n          await new Promise((resolve) => setTimeout(resolve, args.delay));\n          return args.delay;\n        },\n      });\n\n      const start = Date.now();\n      const result = await testFunction.execute({ delay: 100 }, createToolOptions('123'));\n      const duration = Date.now() - start;\n\n      expect(result).toBe(100);\n      expect(duration).toBeGreaterThanOrEqual(95); // Allow for small timing variations\n    });\n\n    describe('nested array support', () => {\n      it('should handle nested array fields', () => {\n        const schema = z.object({\n          items: z.array(\n            z.object({\n              name: z.string().describe('the item name'),\n              modifiers: z\n                .array(\n                  z.object({\n                    modifier_name: z.string(),\n                    modifier_value: z.string(),\n                  }),\n                )\n                .describe('list of the modifiers applied on this item, such as size'),\n            }),\n          ),\n        });\n        const result = oaiParams(schema);\n        expect(result).toMatchSnapshot();\n      });\n    });\n\n    describe('optional parameters', () => {\n      it('should create a tool without parameters', async () => {\n        const simpleAction = tool({\n          description: 'Perform a simple action',\n          execute: async () => {\n            return 'Action performed';\n          },\n        });\n\n        expect(simpleAction.type).toBe('function');\n        expect(simpleAction.description).toBe('Perform a simple action');\n        expect(simpleAction.parameters).toBeDefined();\n        expect(simpleAction.parameters._def.typeName).toBe('ZodObject');\n\n        const result = await simpleAction.execute({}, createToolOptions('123'));\n        expect(result).toBe('Action performed');\n      });\n\n      it('should handle tools with context but no parameters', async () => {\n        const greetUser = tool({\n          description: 'Greet the current user',\n          execute: async (_, { ctx }: ToolOptions<{ username: string }>) => {\n            return `Hello, ${ctx.userData.username}!`;\n          },\n        });\n\n        const result = await greetUser.execute({}, createToolOptions('123', { username: 'Alice' }));\n        expect(result).toBe('Hello, Alice!');\n      });\n\n      it('should create a tool that accesses tool call id without parameters', async () => {\n        const getCallId = tool({\n          description: 'Get the current tool call ID',\n          execute: async (_, { toolCallId }) => {\n            return `Tool call ID: ${toolCallId}`;\n          },\n        });\n\n        const result = await getCallId.execute({}, createToolOptions('test-id-456'));\n        expect(result).toBe('Tool call ID: test-id-456');\n      });\n    });\n  });\n});\n"],"mappings":"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","names":[]}

package/dist/llm/tool_context.test.js

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { tool } from "./tool_context.js";
+import { createToolOptions, oaiParams } from "./utils.js";
+describe("Tool Context", () => {
+  describe("oaiParams", () => {
+    it("should handle basic object schema", () => {
+      const schema = z.object({
+        name: z.string().describe("The user name"),
+        age: z.number().describe("The user age")
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+    it("should handle enum fields", () => {
+      const schema = z.object({
+        color: z.enum(["red", "blue", "green"]).describe("Choose a color")
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+    it("should handle array fields", () => {
+      const schema = z.object({
+        tags: z.array(z.string()).describe("List of tags")
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+    it("should handle array of enums", () => {
+      const schema = z.object({
+        colors: z.array(z.enum(["red", "blue", "green"])).describe("List of colors")
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+    it("should handle optional fields", () => {
+      const schema = z.object({
+        name: z.string().describe("The user name"),
+        age: z.number().optional().describe("The user age")
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+    it("should handle fields without descriptions", () => {
+      const schema = z.object({
+        name: z.string(),
+        age: z.number()
+      });
+      const result = oaiParams(schema);
+      expect(result).toMatchSnapshot();
+    });
+  });
+  describe("tool", () => {
+    it("should create and execute a basic core tool", async () => {
+      const getWeather = tool({
+        description: "Get the weather for a given location",
+        parameters: z.object({
+          location: z.string()
+        }),
+        execute: async ({ location }, { ctx }) => {
+          return `The weather in ${location} is sunny, ${ctx.userData.name}`;
+        }
+      });
+      const result = await getWeather.execute(
+        { location: "San Francisco" },
+        createToolOptions("123", { name: "John" })
+      );
+      expect(result).toBe("The weather in San Francisco is sunny, John");
+    });
+    it("should properly type a callable function", async () => {
+      const testFunction = tool({
+        description: "Test function",
+        parameters: z.object({
+          name: z.string().describe("The user name"),
+          age: z.number().describe("The user age")
+        }),
+        execute: async (args) => {
+          return `${args.name} is ${args.age} years old`;
+        }
+      });
+      const result = await testFunction.execute(
+        { name: "John", age: 30 },
+        createToolOptions("123")
+      );
+      expect(result).toBe("John is 30 years old");
+    });
+    it("should handle async execution", async () => {
+      const testFunction = tool({
+        description: "Async test function",
+        parameters: z.object({
+          delay: z.number().describe("Delay in milliseconds")
+        }),
+        execute: async (args) => {
+          await new Promise((resolve) => setTimeout(resolve, args.delay));
+          return args.delay;
+        }
+      });
+      const start = Date.now();
+      const result = await testFunction.execute({ delay: 100 }, createToolOptions("123"));
+      const duration = Date.now() - start;
+      expect(result).toBe(100);
+      expect(duration).toBeGreaterThanOrEqual(95);
+    });
+    describe("nested array support", () => {
+      it("should handle nested array fields", () => {
+        const schema = z.object({
+          items: z.array(
+            z.object({
+              name: z.string().describe("the item name"),
+              modifiers: z.array(
+                z.object({
+                  modifier_name: z.string(),
+                  modifier_value: z.string()
+                })
+              ).describe("list of the modifiers applied on this item, such as size")
+            })
+          )
+        });
+        const result = oaiParams(schema);
+        expect(result).toMatchSnapshot();
+      });
+    });
+    describe("optional parameters", () => {
+      it("should create a tool without parameters", async () => {
+        const simpleAction = tool({
+          description: "Perform a simple action",
+          execute: async () => {
+            return "Action performed";
+          }
+        });
+        expect(simpleAction.type).toBe("function");
+        expect(simpleAction.description).toBe("Perform a simple action");
+        expect(simpleAction.parameters).toBeDefined();
+        expect(simpleAction.parameters._def.typeName).toBe("ZodObject");
+        const result = await simpleAction.execute({}, createToolOptions("123"));
+        expect(result).toBe("Action performed");
+      });
+      it("should handle tools with context but no parameters", async () => {
+        const greetUser = tool({
+          description: "Greet the current user",
+          execute: async (_, { ctx }) => {
+            return `Hello, ${ctx.userData.username}!`;
+          }
+        });
+        const result = await greetUser.execute({}, createToolOptions("123", { username: "Alice" }));
+        expect(result).toBe("Hello, Alice!");
+      });
+      it("should create a tool that accesses tool call id without parameters", async () => {
+        const getCallId = tool({
+          description: "Get the current tool call ID",
+          execute: async (_, { toolCallId }) => {
+            return `Tool call ID: ${toolCallId}`;
+          }
+        });
+        const result = await getCallId.execute({}, createToolOptions("test-id-456"));
+        expect(result).toBe("Tool call ID: test-id-456");
+      });
+    });
+  });
+});
+//# sourceMappingURL=tool_context.test.js.map

package/dist/llm/tool_context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/tool_context.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { describe, expect, it } from 'vitest';\nimport { z } from 'zod';\nimport { type ToolOptions, tool } from './tool_context.js';\nimport { createToolOptions, oaiParams } from './utils.js';\n\ndescribe('Tool Context', () => {\n  describe('oaiParams', () => {\n    it('should handle basic object schema', () => {\n      const schema = z.object({\n        name: z.string().describe('The user name'),\n        age: z.number().describe('The user age'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle enum fields', () => {\n      const schema = z.object({\n        color: z.enum(['red', 'blue', 'green']).describe('Choose a color'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle array fields', () => {\n      const schema = z.object({\n        tags: z.array(z.string()).describe('List of tags'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle array of enums', () => {\n      const schema = z.object({\n        colors: z.array(z.enum(['red', 'blue', 'green'])).describe('List of colors'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle optional fields', () => {\n      const schema = z.object({\n        name: z.string().describe('The user name'),\n        age: z.number().optional().describe('The user age'),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n\n    it('should handle fields without descriptions', () => {\n      const schema = z.object({\n        name: z.string(),\n        age: z.number(),\n      });\n\n      const result = oaiParams(schema);\n\n      expect(result).toMatchSnapshot();\n    });\n  });\n\n  describe('tool', () => {\n    it('should create and execute a basic core tool', async () => {\n      const getWeather = tool({\n        description: 'Get the weather for a given location',\n        parameters: z.object({\n          location: z.string(),\n        }),\n        execute: async ({ location }, { ctx }: ToolOptions<{ name: string }>) => {\n          return `The weather in ${location} is sunny, ${ctx.userData.name}`;\n        },\n      });\n\n      const result = await getWeather.execute(\n        { location: 'San Francisco' },\n        createToolOptions('123', { name: 'John' }),\n      );\n      expect(result).toBe('The weather in San Francisco is sunny, John');\n    });\n\n    it('should properly type a callable function', async () => {\n      const testFunction = tool({\n        description: 'Test function',\n        parameters: z.object({\n          name: z.string().describe('The user name'),\n          age: z.number().describe('The user age'),\n        }),\n        execute: async (args) => {\n          return `${args.name} is ${args.age} years old`;\n        },\n      });\n\n      const result = await testFunction.execute(\n        { name: 'John', age: 30 },\n        createToolOptions('123'),\n      );\n      expect(result).toBe('John is 30 years old');\n    });\n\n    it('should handle async execution', async () => {\n      const testFunction = tool({\n        description: 'Async test function',\n        parameters: z.object({\n          delay: z.number().describe('Delay in milliseconds'),\n        }),\n        execute: async (args) => {\n          await new Promise((resolve) => setTimeout(resolve, args.delay));\n          return args.delay;\n        },\n      });\n\n      const start = Date.now();\n      const result = await testFunction.execute({ delay: 100 }, createToolOptions('123'));\n      const duration = Date.now() - start;\n\n      expect(result).toBe(100);\n      expect(duration).toBeGreaterThanOrEqual(95); // Allow for small timing variations\n    });\n\n    describe('nested array support', () => {\n      it('should handle nested array fields', () => {\n        const schema = z.object({\n          items: z.array(\n            z.object({\n              name: z.string().describe('the item name'),\n              modifiers: z\n                .array(\n                  z.object({\n                    modifier_name: z.string(),\n                    modifier_value: z.string(),\n                  }),\n                )\n                .describe('list of the modifiers applied on this item, such as size'),\n            }),\n          ),\n        });\n        const result = oaiParams(schema);\n        expect(result).toMatchSnapshot();\n      });\n    });\n\n    describe('optional parameters', () => {\n      it('should create a tool without parameters', async () => {\n        const simpleAction = tool({\n          description: 'Perform a simple action',\n          execute: async () => {\n            return 'Action performed';\n          },\n        });\n\n        expect(simpleAction.type).toBe('function');\n        expect(simpleAction.description).toBe('Perform a simple action');\n        expect(simpleAction.parameters).toBeDefined();\n        expect(simpleAction.parameters._def.typeName).toBe('ZodObject');\n\n        const result = await simpleAction.execute({}, createToolOptions('123'));\n        expect(result).toBe('Action performed');\n      });\n\n      it('should handle tools with context but no parameters', async () => {\n        const greetUser = tool({\n          description: 'Greet the current user',\n          execute: async (_, { ctx }: ToolOptions<{ username: string }>) => {\n            return `Hello, ${ctx.userData.username}!`;\n          },\n        });\n\n        const result = await greetUser.execute({}, createToolOptions('123', { username: 'Alice' }));\n        expect(result).toBe('Hello, Alice!');\n      });\n\n      it('should create a tool that accesses tool call id without parameters', async () => {\n        const getCallId = tool({\n          description: 'Get the current tool call ID',\n          execute: async (_, { toolCallId }) => {\n            return `Tool call ID: ${toolCallId}`;\n          },\n        });\n\n        const result = await getCallId.execute({}, createToolOptions('test-id-456'));\n        expect(result).toBe('Tool call ID: test-id-456');\n      });\n    });\n  });\n});\n"],"mappings":"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","names":[]}

package/dist/llm/tool_context.type.test.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var import_vitest = require("vitest");
+var import_zod = require("zod");
+var import_index = require("./index.cjs");
+(0, import_vitest.describe)("tool type inference", () => {
+  (0, import_vitest.it)("should infer argument type from zod schema", () => {
+    const toolType = (0, import_index.tool)({
+      description: "test",
+      parameters: import_zod.z.object({ number: import_zod.z.number() }),
+      execute: async () => "test"
+    });
+    (0, import_vitest.expectTypeOf)(toolType).toEqualTypeOf();
+  });
+  (0, import_vitest.it)("should infer provider defined tool type", () => {
+    const toolType = (0, import_index.tool)({
+      id: "code-interpreter",
+      config: {
+        language: "python"
+      }
+    });
+    (0, import_vitest.expectTypeOf)(toolType).toEqualTypeOf();
+  });
+  (0, import_vitest.it)("should infer run context type", () => {
+    const toolType = (0, import_index.tool)({
+      description: "test",
+      parameters: import_zod.z.object({ number: import_zod.z.number() }),
+      execute: async ({ number }, { ctx }) => {
+        return `The number is ${number}, ${ctx.userData.name}`;
+      }
+    });
+    (0, import_vitest.expectTypeOf)(toolType).toEqualTypeOf();
+  });
+  (0, import_vitest.it)("should not accept primitive zod schemas", () => {
+    (0, import_vitest.expect)(() => {
+      (0, import_index.tool)({
+        name: "test",
+        description: "test",
+        parameters: import_zod.z.string(),
+        execute: async () => "test"
+      });
+    }).toThrowError("Tool parameters must be a Zod object schema (z.object(...))");
+  });
+  (0, import_vitest.it)("should not accept array schemas", () => {
+    (0, import_vitest.expect)(() => {
+      (0, import_index.tool)({
+        name: "test",
+        description: "test",
+        parameters: import_zod.z.array(import_zod.z.string()),
+        execute: async () => "test"
+      });
+    }).toThrowError("Tool parameters must be a Zod object schema (z.object(...))");
+  });
+  (0, import_vitest.it)("should not accept union schemas", () => {
+    (0, import_vitest.expect)(() => {
+      (0, import_index.tool)({
+        name: "test",
+        description: "test",
+        parameters: import_zod.z.union([import_zod.z.object({ a: import_zod.z.string() }), import_zod.z.object({ b: import_zod.z.number() })]),
+        execute: async () => "test"
+      });
+    }).toThrowError("Tool parameters must be a Zod object schema (z.object(...))");
+  });
+  (0, import_vitest.it)("should not accept non-Zod values as parameters", () => {
+    (0, import_vitest.expect)(() => {
+      (0, import_index.tool)({
+        name: "test",
+        description: "test",
+        parameters: "invalid schema",
+        execute: async () => "test"
+      });
+    }).toThrowError("Tool parameters must be a Zod object schema or a raw JSON schema");
+  });
+  (0, import_vitest.it)("should infer empty object type when parameters are omitted", () => {
+    const toolType = (0, import_index.tool)({
+      description: "Simple action without parameters",
+      execute: async () => "done"
+    });
+    (0, import_vitest.expectTypeOf)(toolType).toEqualTypeOf();
+  });
+  (0, import_vitest.it)("should infer correct types with context but no parameters", () => {
+    const toolType = (0, import_index.tool)({
+      description: "Action with context",
+      execute: async (args, { ctx }) => {
+        (0, import_vitest.expectTypeOf)(args).toEqualTypeOf();
+        (0, import_vitest.expectTypeOf)(ctx.userData.userId).toEqualTypeOf();
+        return ctx.userData.userId;
+      }
+    });
+    (0, import_vitest.expectTypeOf)(toolType).toEqualTypeOf();
+  });
+});
+//# sourceMappingURL=tool_context.type.test.cjs.map

package/dist/llm/tool_context.type.test.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/tool_context.type.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { describe, expect, expectTypeOf, it } from 'vitest';\nimport { z } from 'zod';\nimport { type FunctionTool, type ProviderDefinedTool, type ToolOptions, tool } from './index.js';\n\ndescribe('tool type inference', () => {\n  it('should infer argument type from zod schema', () => {\n    const toolType = tool({\n      description: 'test',\n      parameters: z.object({ number: z.number() }),\n      execute: async () => 'test' as const,\n    });\n\n    expectTypeOf(toolType).toEqualTypeOf<FunctionTool<{ number: number }, unknown, 'test'>>();\n  });\n\n  it('should infer provider defined tool type', () => {\n    const toolType = tool({\n      id: 'code-interpreter',\n      config: {\n        language: 'python',\n      },\n    });\n\n    expectTypeOf(toolType).toEqualTypeOf<ProviderDefinedTool>();\n  });\n\n  it('should infer run context type', () => {\n    const toolType = tool({\n      description: 'test',\n      parameters: z.object({ number: z.number() }),\n      execute: async ({ number }, { ctx }: ToolOptions<{ name: string }>) => {\n        return `The number is ${number}, ${ctx.userData.name}`;\n      },\n    });\n\n    expectTypeOf(toolType).toEqualTypeOf<\n      FunctionTool<{ number: number }, { name: string }, string>\n    >();\n  });\n\n  it('should not accept primitive zod schemas', () => {\n    expect(() => {\n      // @ts-expect-error - Testing that non-object schemas are rejected\n      tool({\n        name: 'test',\n        description: 'test',\n        parameters: z.string(),\n        execute: async () => 'test' as const,\n      });\n    }).toThrowError('Tool parameters must be a Zod object schema (z.object(...))');\n  });\n\n  it('should not accept array schemas', () => {\n    expect(() => {\n      // @ts-expect-error - Testing that array schemas are rejected\n      tool({\n        name: 'test',\n        description: 'test',\n        parameters: z.array(z.string()),\n        execute: async () => 'test' as const,\n      });\n    }).toThrowError('Tool parameters must be a Zod object schema (z.object(...))');\n  });\n\n  it('should not accept union schemas', () => {\n    expect(() => {\n      // @ts-expect-error - Testing that union schemas are rejected\n      tool({\n        name: 'test',\n        description: 'test',\n        parameters: z.union([z.object({ a: z.string() }), z.object({ b: z.number() })]),\n        execute: async () => 'test' as const,\n      });\n    }).toThrowError('Tool parameters must be a Zod object schema (z.object(...))');\n  });\n\n  it('should not accept non-Zod values as parameters', () => {\n    expect(() => {\n      // @ts-expect-error - Testing that non-Zod values are rejected\n      tool({\n        name: 'test',\n        description: 'test',\n        parameters: 'invalid schema',\n        execute: async () => 'test' as const,\n      });\n    }).toThrowError('Tool parameters must be a Zod object schema or a raw JSON schema');\n  });\n\n  it('should infer empty object type when parameters are omitted', () => {\n    const toolType = tool({\n      description: 'Simple action without parameters',\n      execute: async () => 'done' as const,\n    });\n\n    expectTypeOf(toolType).toEqualTypeOf<FunctionTool<Record<string, never>, unknown, 'done'>>();\n  });\n\n  it('should infer correct types with context but no parameters', () => {\n    const toolType = tool({\n      description: 'Action with context',\n      execute: async (args, { ctx }: ToolOptions<{ userId: number }>) => {\n        expectTypeOf(args).toEqualTypeOf<Record<string, never>>();\n        expectTypeOf(ctx.userData.userId).toEqualTypeOf<number>();\n        return ctx.userData.userId;\n      },\n    });\n\n    expectTypeOf(toolType).toEqualTypeOf<\n      FunctionTool<Record<string, never>, { userId: number }, number>\n    >();\n  });\n});\n"],"mappings":";AAGA,oBAAmD;AACnD,iBAAkB;AAClB,mBAAoF;AAAA,IAEpF,wBAAS,uBAAuB,MAAM;AACpC,wBAAG,8CAA8C,MAAM;AACrD,UAAM,eAAW,mBAAK;AAAA,MACpB,aAAa;AAAA,MACb,YAAY,aAAE,OAAO,EAAE,QAAQ,aAAE,OAAO,EAAE,CAAC;AAAA,MAC3C,SAAS,YAAY;AAAA,IACvB,CAAC;AAED,oCAAa,QAAQ,EAAE,cAAiE;AAAA,EAC1F,CAAC;AAED,wBAAG,2CAA2C,MAAM;AAClD,UAAM,eAAW,mBAAK;AAAA,MACpB,IAAI;AAAA,MACJ,QAAQ;AAAA,QACN,UAAU;AAAA,MACZ;AAAA,IACF,CAAC;AAED,oCAAa,QAAQ,EAAE,cAAmC;AAAA,EAC5D,CAAC;AAED,wBAAG,iCAAiC,MAAM;AACxC,UAAM,eAAW,mBAAK;AAAA,MACpB,aAAa;AAAA,MACb,YAAY,aAAE,OAAO,EAAE,QAAQ,aAAE,OAAO,EAAE,CAAC;AAAA,MAC3C,SAAS,OAAO,EAAE,OAAO,GAAG,EAAE,IAAI,MAAqC;AACrE,eAAO,iBAAiB,MAAM,KAAK,IAAI,SAAS,IAAI;AAAA,MACtD;AAAA,IACF,CAAC;AAED,oCAAa,QAAQ,EAAE,cAErB;AAAA,EACJ,CAAC;AAED,wBAAG,2CAA2C,MAAM;AAClD,8BAAO,MAAM;AAEX,6BAAK;AAAA,QACH,MAAM;AAAA,QACN,aAAa;AAAA,QACb,YAAY,aAAE,OAAO;AAAA,QACrB,SAAS,YAAY;AAAA,MACvB,CAAC;AAAA,IACH,CAAC,EAAE,aAAa,6DAA6D;AAAA,EAC/E,CAAC;AAED,wBAAG,mCAAmC,MAAM;AAC1C,8BAAO,MAAM;AAEX,6BAAK;AAAA,QACH,MAAM;AAAA,QACN,aAAa;AAAA,QACb,YAAY,aAAE,MAAM,aAAE,OAAO,CAAC;AAAA,QAC9B,SAAS,YAAY;AAAA,MACvB,CAAC;AAAA,IACH,CAAC,EAAE,aAAa,6DAA6D;AAAA,EAC/E,CAAC;AAED,wBAAG,mCAAmC,MAAM;AAC1C,8BAAO,MAAM;AAEX,6BAAK;AAAA,QACH,MAAM;AAAA,QACN,aAAa;AAAA,QACb,YAAY,aAAE,MAAM,CAAC,aAAE,OAAO,EAAE,GAAG,aAAE,OAAO,EAAE,CAAC,GAAG,aAAE,OAAO,EAAE,GAAG,aAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAAA,QAC9E,SAAS,YAAY;AAAA,MACvB,CAAC;AAAA,IACH,CAAC,EAAE,aAAa,6DAA6D;AAAA,EAC/E,CAAC;AAED,wBAAG,kDAAkD,MAAM;AACzD,8BAAO,MAAM;AAEX,6BAAK;AAAA,QACH,MAAM;AAAA,QACN,aAAa;AAAA,QACb,YAAY;AAAA,QACZ,SAAS,YAAY;AAAA,MACvB,CAAC;AAAA,IACH,CAAC,EAAE,aAAa,kEAAkE;AAAA,EACpF,CAAC;AAED,wBAAG,8DAA8D,MAAM;AACrE,UAAM,eAAW,mBAAK;AAAA,MACpB,aAAa;AAAA,MACb,SAAS,YAAY;AAAA,IACvB,CAAC;AAED,oCAAa,QAAQ,EAAE,cAAoE;AAAA,EAC7F,CAAC;AAED,wBAAG,6DAA6D,MAAM;AACpE,UAAM,eAAW,mBAAK;AAAA,MACpB,aAAa;AAAA,MACb,SAAS,OAAO,MAAM,EAAE,IAAI,MAAuC;AACjE,wCAAa,IAAI,EAAE,cAAqC;AACxD,wCAAa,IAAI,SAAS,MAAM,EAAE,cAAsB;AACxD,eAAO,IAAI,SAAS;AAAA,MACtB;AAAA,IACF,CAAC;AAED,oCAAa,QAAQ,EAAE,cAErB;AAAA,EACJ,CAAC;AACH,CAAC;","names":[]}