@typia/vercel 12.1.0-dev.20260325 → 13.0.0-dev.20260426

package/src/index.ts

@@ -1,155 +1,155 @@
-import {
-  IHttpLlmController,
-  ILlmController,
-  ILlmSchema,
-} from "@typia/interface";
-import type { Schema, Tool } from "ai";
-
-import { VercelParameterConverter } from "./internal/VercelParameterConverter";
-import { VercelToolsRegistrar } from "./internal/VercelToolsRegistrar";
-
-/**
- * Convert typia controllers to Vercel AI SDK tools.
- *
- * Transforms TypeScript class methods via `typia.llm.controller<Class>()` or
- * OpenAPI operations via `HttpLlm.controller()` into Vercel AI SDK tools that
- * can be used with any LLM provider (OpenAI, Anthropic, Google, etc.).
- *
- * Every tool call is validated by typia. If the LLM provides invalid arguments,
- * returns a validation error formatted by {@link LlmJson.stringify} so the LLM
- * can auto-correct in the next turn.
- *
- * ## Example with OpenAI
- *
- * ```typescript
- * import { generateText } from "ai";
- * import { openai } from "@ai-sdk/openai";
- * import typia from "typia";
- * import { toVercelTools } from "@typia/vercel";
- *
- * class Calculator {
- *   /&#42;&#42; Add two numbers together. &#42;/
- *   add(props: { a: number; b: number }): { value: number } {
- *     return { value: props.a + props.b };
- *   }
- * }
- *
- * const controller = typia.llm.controller<Calculator>("calc", new Calculator());
- * const tools = toVercelTools({ controllers: [controller] });
- *
- * const result = await generateText({
- *   model: openai("gpt-4o"),
- *   tools,
- *   prompt: "What is 15 + 27?",
- * });
- * ```
- *
- * ## Example with Anthropic
- *
- * ```typescript
- * import { anthropic } from "@ai-sdk/anthropic";
- * import { toVercelTools } from "@typia/vercel";
- * import { generateText } from "ai";
- *
- * const result = await generateText({
- *   model: anthropic("claude-sonnet-4-20250514"),
- *   tools: toVercelTools({ controllers: [controller] }),
- *   prompt: "Calculate 100 * 50",
- * });
- * ```
- *
- * ## Example with HTTP Controller (OpenAPI)
- *
- * ```typescript
- * import { openai } from "@ai-sdk/openai";
- * import { HttpLlm } from "@typia/utils";
- * import { toVercelTools } from "@typia/vercel";
- * import { generateText } from "ai";
- *
- * const controller = HttpLlm.controller({
- *   name: "shopping",
- *   document: await fetch("https://api.example.com/swagger.json").then(
- *     (r) => r.json(),
- *   ),
- *   connection: { host: "https://api.example.com" },
- * });
- *
- * const result = await generateText({
- *   model: openai("gpt-4o"),
- *   tools: toVercelTools({ controllers: [controller] }),
- *   prompt: "Search for laptops under $1000",
- * });
- * ```
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param props Conversion properties
- * @returns Record of Vercel AI SDK Tools keyed by tool name
- */
-export function toVercelTools(props: {
-  /**
-   * List of controllers to convert to Vercel tools.
-   *
-   * - {@link ILlmController}: from `typia.llm.controller<Class>()`, converts all
-   *   methods of the class to tools
-   * - {@link IHttpLlmController}: from `HttpLlm.controller()`, converts all
-   *   operations from OpenAPI document to tools
-   */
-  controllers: Array<ILlmController | IHttpLlmController>;
-
-  /**
-   * Whether to prefix tool names with controller name.
-   *
-   * If `true`, tool names are formatted as `{controller}_{function}`. If
-   * `false`, only the function name is used (may cause conflicts).
-   *
-   * @default false
-   */
-  prefix?: boolean | undefined;
-}): Record<string, Tool> {
-  return VercelToolsRegistrar.convert(props);
-}
-
-/**
- * Convert LLM parameters schema to Vercel AI SDK schema format.
- *
- * Transforms {@link ILlmSchema.IParameters} into Vercel AI SDK's `Schema` type
- * for use with `generateObject()`. Use with `typia.llm.structuredOutput<T>()`
- * or `typia.llm.parameters<T>()`.
- *
- * ## Example
- *
- * ```typescript
- * import { openai } from "@ai-sdk/openai";
- * import { toVercelSchema } from "@typia/vercel";
- * import { generateObject } from "ai";
- * import typia from "typia";
- *
- * interface IMember {
- *   name: string;
- *   age: number;
- * }
- *
- * const output = typia.llm.structuredOutput<IMember>();
- * const schema = toVercelSchema(output.parameters);
- *
- * const { object } = await generateObject({
- *   model: openai("gpt-4o"),
- *   schema,
- *   prompt: "Generate a member named John who is 30 years old",
- * });
- *
- * const coerced = output.coerce(object);
- * const result = output.validate(coerced);
- * ```
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param parameters LLM parameters schema from
- *   `typia.llm.structuredOutput<T>().parameters` or
- *   `typia.llm.parameters<T>()`
- * @returns Vercel AI SDK Schema for `generateObject()`
- */
-export function toVercelSchema(
-  parameters: ILlmSchema.IParameters,
-): Schema<object> {
-  return VercelParameterConverter.convert(parameters);
-}
+import {
+  IHttpLlmController,
+  ILlmController,
+  ILlmSchema,
+} from "@typia/interface";
+import type { Schema, Tool } from "ai";
+
+import { VercelParameterConverter } from "./internal/VercelParameterConverter";
+import { VercelToolsRegistrar } from "./internal/VercelToolsRegistrar";
+
+/**
+ * Convert typia controllers to Vercel AI SDK tools.
+ *
+ * Transforms TypeScript class methods via `typia.llm.controller<Class>()` or
+ * OpenAPI operations via `HttpLlm.controller()` into Vercel AI SDK tools that
+ * can be used with any LLM provider (OpenAI, Anthropic, Google, etc.).
+ *
+ * Every tool call is validated by typia. If the LLM provides invalid arguments,
+ * returns a validation error formatted by {@link LlmJson.stringify} so the LLM
+ * can auto-correct in the next turn.
+ *
+ * ## Example with OpenAI
+ *
+ * ```typescript
+ * import { generateText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ * import typia from "typia";
+ * import { toVercelTools } from "@typia/vercel";
+ *
+ * class Calculator {
+ *   /&#42;&#42; Add two numbers together. &#42;/
+ *   add(props: { a: number; b: number }): { value: number } {
+ *     return { value: props.a + props.b };
+ *   }
+ * }
+ *
+ * const controller = typia.llm.controller<Calculator>("calc", new Calculator());
+ * const tools = toVercelTools({ controllers: [controller] });
+ *
+ * const result = await generateText({
+ *   model: openai("gpt-4o"),
+ *   tools,
+ *   prompt: "What is 15 + 27?",
+ * });
+ * ```
+ *
+ * ## Example with Anthropic
+ *
+ * ```typescript
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * import { toVercelTools } from "@typia/vercel";
+ * import { generateText } from "ai";
+ *
+ * const result = await generateText({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: toVercelTools({ controllers: [controller] }),
+ *   prompt: "Calculate 100 * 50",
+ * });
+ * ```
+ *
+ * ## Example with HTTP Controller (OpenAPI)
+ *
+ * ```typescript
+ * import { openai } from "@ai-sdk/openai";
+ * import { HttpLlm } from "@typia/utils";
+ * import { toVercelTools } from "@typia/vercel";
+ * import { generateText } from "ai";
+ *
+ * const controller = HttpLlm.controller({
+ *   name: "shopping",
+ *   document: await fetch("https://api.example.com/swagger.json").then(
+ *     (r) => r.json(),
+ *   ),
+ *   connection: { host: "https://api.example.com" },
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai("gpt-4o"),
+ *   tools: toVercelTools({ controllers: [controller] }),
+ *   prompt: "Search for laptops under $1000",
+ * });
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param props Conversion properties
+ * @returns Record of Vercel AI SDK Tools keyed by tool name
+ */
+export function toVercelTools(props: {
+  /**
+   * List of controllers to convert to Vercel tools.
+   *
+   * - {@link ILlmController}: from `typia.llm.controller<Class>()`, converts all
+   *   methods of the class to tools
+   * - {@link IHttpLlmController}: from `HttpLlm.controller()`, converts all
+   *   operations from OpenAPI document to tools
+   */
+  controllers: Array<ILlmController | IHttpLlmController>;
+
+  /**
+   * Whether to prefix tool names with controller name.
+   *
+   * If `true`, tool names are formatted as `{controller}_{function}`. If
+   * `false`, only the function name is used (may cause conflicts).
+   *
+   * @default false
+   */
+  prefix?: boolean | undefined;
+}): Record<string, Tool> {
+  return VercelToolsRegistrar.convert(props);
+}
+
+/**
+ * Convert LLM parameters schema to Vercel AI SDK schema format.
+ *
+ * Transforms {@link ILlmSchema.IParameters} into Vercel AI SDK's `Schema` type
+ * for use with `generateObject()`. Use with `typia.llm.structuredOutput<T>()`
+ * or `typia.llm.parameters<T>()`.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { openai } from "@ai-sdk/openai";
+ * import { toVercelSchema } from "@typia/vercel";
+ * import { generateObject } from "ai";
+ * import typia from "typia";
+ *
+ * interface IMember {
+ *   name: string;
+ *   age: number;
+ * }
+ *
+ * const output = typia.llm.structuredOutput<IMember>();
+ * const schema = toVercelSchema(output.parameters);
+ *
+ * const { object } = await generateObject({
+ *   model: openai("gpt-4o"),
+ *   schema,
+ *   prompt: "Generate a member named John who is 30 years old",
+ * });
+ *
+ * const coerced = output.coerce(object);
+ * const result = output.validate(coerced);
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param parameters LLM parameters schema from
+ *   `typia.llm.structuredOutput<T>().parameters` or
+ *   `typia.llm.parameters<T>()`
+ * @returns Vercel AI SDK Schema for `generateObject()`
+ */
+export function toVercelSchema(
+  parameters: ILlmSchema.IParameters,
+): Schema<object> {
+  return VercelParameterConverter.convert(parameters);
+}

package/src/internal/VercelParameterConverter.ts

@@ -1,8 +1,8 @@
-import { ILlmSchema } from "@typia/interface";
-import { Schema, jsonSchema } from "ai";
-import { JSONSchema7 } from "json-schema";
-
-export namespace VercelParameterConverter {
-  export const convert = (parameters: ILlmSchema.IParameters): Schema<object> =>
-    jsonSchema<object>(parameters as JSONSchema7);
-}
+import { ILlmSchema } from "@typia/interface";
+import { Schema, jsonSchema } from "ai";
+import { JSONSchema7 } from "json-schema";
+
+export namespace VercelParameterConverter {
+  export const convert = (parameters: ILlmSchema.IParameters): Schema<object> =>
+    jsonSchema<object>(parameters as JSONSchema7);
+}

package/src/internal/VercelToolsRegistrar.ts

@@ -1,166 +1,166 @@
-import {
-  IHttpLlmController,
-  IHttpLlmFunction,
-  ILlmController,
-  ILlmFunction,
-  IValidation,
-} from "@typia/interface";
-import { HttpLlm, LlmJson } from "@typia/utils";
-import { Tool, tool } from "ai";
-
-import { VercelParameterConverter } from "./VercelParameterConverter";
-
-export namespace VercelToolsRegistrar {
-  /**
-   * Convert typia controllers to Vercel AI SDK tools.
-   *
-   * @param props Conversion properties
-   * @returns Record of Vercel AI SDK Tools
-   */
-  export const convert = (props: {
-    controllers: Array<ILlmController | IHttpLlmController>;
-    prefix?: boolean | undefined;
-  }): Record<string, Tool> => {
-    const prefix: boolean = props.prefix ?? false;
-    const tools: Record<string, Tool> = {};
-
-    // check duplicate tool names
-    if (prefix === false && props.controllers.length >= 2) {
-      const names: Map<string, string> = new Map();
-      const duplicates: string[] = [];
-      for (const controller of props.controllers) {
-        for (const func of controller.application.functions) {
-          const existing: string | undefined = names.get(func.name);
-          if (existing !== undefined)
-            duplicates.push(
-              `"${func.name}" in "${controller.name}" (conflicts with "${existing}")`,
-            );
-          else names.set(func.name, controller.name);
-        }
-      }
-      if (duplicates.length > 0)
-        throw new Error(
-          `Duplicate tool names found:\n  - ${duplicates.join("\n  - ")}`,
-        );
-    }
-
-    // convert controllers to tools
-    for (const controller of props.controllers) {
-      if (controller.protocol === "class") {
-        registerClassController({ tools, controller, prefix });
-      } else {
-        registerHttpController({ tools, controller, prefix });
-      }
-    }
-
-    return tools;
-  };
-
-  const registerClassController = (props: {
-    tools: Record<string, Tool>;
-    controller: ILlmController;
-    prefix: boolean;
-  }): void => {
-    const { tools, controller, prefix } = props;
-    const execute: Record<string, unknown> = controller.execute;
-
-    for (const func of controller.application.functions) {
-      const toolName: string = prefix
-        ? `${controller.name}_${func.name}`
-        : func.name;
-
-      const method: unknown = execute[func.name];
-      if (typeof method !== "function") {
-        throw new Error(
-          `Method "${func.name}" not found on controller "${controller.name}"`,
-        );
-      }
-
-      tools[toolName] = createTool({
-        name: toolName,
-        func,
-        execute: async (args: unknown) => method.call(execute, args),
-      });
-    }
-  };
-
-  const registerHttpController = (props: {
-    tools: Record<string, Tool>;
-    controller: IHttpLlmController;
-    prefix: boolean;
-  }): void => {
-    const { tools, controller, prefix } = props;
-    const application = controller.application;
-    const connection = controller.connection;
-
-    for (const func of application.functions) {
-      const toolName: string = prefix
-        ? `${controller.name}_${func.name}`
-        : func.name;
-
-      tools[toolName] = createTool({
-        name: toolName,
-        func,
-        execute: async (args: unknown) => {
-          if (controller.execute !== undefined) {
-            const response = await controller.execute({
-              connection,
-              application,
-              function: func,
-              arguments: args as object,
-            });
-            return response.body;
-          }
-          return HttpLlm.execute({
-            application,
-            function: func,
-            connection,
-            input: args as object,
-          });
-        },
-      });
-    }
-  };
-
-  const createTool = (props: {
-    name: string;
-    func: ILlmFunction | IHttpLlmFunction;
-    execute: (args: unknown) => Promise<unknown>;
-  }): Tool => {
-    const { name, func, execute } = props;
-
-    return tool({
-      description: func.description ?? "",
-      inputSchema: VercelParameterConverter.convert(func.parameters),
-      execute: async (args: unknown): Promise<ITryResult> => {
-        const coerced: unknown = LlmJson.coerce(args, func.parameters);
-        const validation: IValidation<unknown> = func.validate(coerced);
-        if (!validation.success)
-          return {
-            success: false,
-            error:
-              `Type errors in "${name}" arguments:\n\n` +
-              `\`\`\`json\n${LlmJson.stringify(validation)}\n\`\`\``,
-          } satisfies ITryResult;
-        try {
-          const result: unknown = await execute(validation.data);
-          return result === undefined
-            ? ({ success: true } satisfies ITryResult)
-            : ({ success: true, data: result } satisfies ITryResult);
-        } catch (error) {
-          return {
-            success: false,
-            error:
-              error instanceof Error
-                ? `${error.name}: ${error.message}`
-                : String(error),
-          } satisfies ITryResult;
-        }
-      },
-    });
-  };
-}
-
-type ITryResult =
-  | { success: true; data?: unknown | undefined }
-  | { success: false; error: string };
+import {
+  IHttpLlmController,
+  IHttpLlmFunction,
+  ILlmController,
+  ILlmFunction,
+  IValidation,
+} from "@typia/interface";
+import { HttpLlm, LlmJson } from "@typia/utils";
+import { Tool, tool } from "ai";
+
+import { VercelParameterConverter } from "./VercelParameterConverter";
+
+export namespace VercelToolsRegistrar {
+  /**
+   * Convert typia controllers to Vercel AI SDK tools.
+   *
+   * @param props Conversion properties
+   * @returns Record of Vercel AI SDK Tools
+   */
+  export const convert = (props: {
+    controllers: Array<ILlmController | IHttpLlmController>;
+    prefix?: boolean | undefined;
+  }): Record<string, Tool> => {
+    const prefix: boolean = props.prefix ?? false;
+    const tools: Record<string, Tool> = {};
+
+    // check duplicate tool names
+    if (prefix === false && props.controllers.length >= 2) {
+      const names: Map<string, string> = new Map();
+      const duplicates: string[] = [];
+      for (const controller of props.controllers) {
+        for (const func of controller.application.functions) {
+          const existing: string | undefined = names.get(func.name);
+          if (existing !== undefined)
+            duplicates.push(
+              `"${func.name}" in "${controller.name}" (conflicts with "${existing}")`,
+            );
+          else names.set(func.name, controller.name);
+        }
+      }
+      if (duplicates.length > 0)
+        throw new Error(
+          `Duplicate tool names found:\n  - ${duplicates.join("\n  - ")}`,
+        );
+    }
+
+    // convert controllers to tools
+    for (const controller of props.controllers) {
+      if (controller.protocol === "class") {
+        registerClassController({ tools, controller, prefix });
+      } else {
+        registerHttpController({ tools, controller, prefix });
+      }
+    }
+
+    return tools;
+  };
+
+  const registerClassController = (props: {
+    tools: Record<string, Tool>;
+    controller: ILlmController;
+    prefix: boolean;
+  }): void => {
+    const { tools, controller, prefix } = props;
+    const execute: Record<string, unknown> = controller.execute;
+
+    for (const func of controller.application.functions) {
+      const toolName: string = prefix
+        ? `${controller.name}_${func.name}`
+        : func.name;
+
+      const method: unknown = execute[func.name];
+      if (typeof method !== "function") {
+        throw new Error(
+          `Method "${func.name}" not found on controller "${controller.name}"`,
+        );
+      }
+
+      tools[toolName] = createTool({
+        name: toolName,
+        func,
+        execute: async (args: unknown) => method.call(execute, args),
+      });
+    }
+  };
+
+  const registerHttpController = (props: {
+    tools: Record<string, Tool>;
+    controller: IHttpLlmController;
+    prefix: boolean;
+  }): void => {
+    const { tools, controller, prefix } = props;
+    const application = controller.application;
+    const connection = controller.connection;
+
+    for (const func of application.functions) {
+      const toolName: string = prefix
+        ? `${controller.name}_${func.name}`
+        : func.name;
+
+      tools[toolName] = createTool({
+        name: toolName,
+        func,
+        execute: async (args: unknown) => {
+          if (controller.execute !== undefined) {
+            const response = await controller.execute({
+              connection,
+              application,
+              function: func,
+              arguments: args as object,
+            });
+            return response.body;
+          }
+          return HttpLlm.execute({
+            application,
+            function: func,
+            connection,
+            input: args as object,
+          });
+        },
+      });
+    }
+  };
+
+  const createTool = (props: {
+    name: string;
+    func: ILlmFunction | IHttpLlmFunction;
+    execute: (args: unknown) => Promise<unknown>;
+  }): Tool => {
+    const { name, func, execute } = props;
+
+    return tool({
+      description: func.description ?? "",
+      inputSchema: VercelParameterConverter.convert(func.parameters),
+      execute: async (args: unknown): Promise<ITryResult> => {
+        const coerced: unknown = LlmJson.coerce(args, func.parameters);
+        const validation: IValidation<unknown> = func.validate(coerced);
+        if (!validation.success)
+          return {
+            success: false,
+            error:
+              `Type errors in "${name}" arguments:\n\n` +
+              `\`\`\`json\n${LlmJson.stringify(validation)}\n\`\`\``,
+          } satisfies ITryResult;
+        try {
+          const result: unknown = await execute(validation.data);
+          return result === undefined
+            ? ({ success: true } satisfies ITryResult)
+            : ({ success: true, data: result } satisfies ITryResult);
+        } catch (error) {
+          return {
+            success: false,
+            error:
+              error instanceof Error
+                ? `${error.name}: ${error.message}`
+                : String(error),
+          } satisfies ITryResult;
+        }
+      },
+    });
+  };
+}
+
+type ITryResult =
+  | { success: true; data?: unknown | undefined }
+  | { success: false; error: string };