@typia/interface 12.0.0-dev.20260309 → 12.0.0-dev.20260310

package/src/schema/ILlmController.ts

@@ -1,57 +1,54 @@
-import { ILlmApplication } from "./ILlmApplication";
-
-/**
- * Controller of TypeScript class-based LLM function calling.
- *
- * `ILlmController` is a controller for registering TypeScript class methods as
- * LLM function calling tools. It contains {@link ILlmApplication} with
- * {@link ILlmFunction function calling schemas}, {@link name identifier}, and
- * {@link execute class instance} for method execution.
- *
- * You can create this controller with `typia.llm.controller<Class>()` function,
- * and register it to MCP server with {@link registerMcpControllers}:
- *
- * ```typescript
- * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- * import typia from "typia";
- * import { registerMcpControllers } from "@typia/mcp";
- *
- * class Calculator {
- *   add(input: { a: number; b: number }): number {
- *     return input.a + input.b;
- *   }
- *   subtract(input: { a: number; b: number }): number {
- *     return input.a - input.b;
- *   }
- * }
- *
- * const server = new McpServer({ name: "my-server", version: "1.0.0" });
- * registerMcpControllers({
- *   server,
- *   controllers: [
- *     typia.llm.controller<Calculator>(
- *       "calculator",
- *       new Calculator(),
- *     ),
- *   ],
- * });
- * ```
- *
- * For OpenAPI/HTTP-based controller, use {@link IHttpLlmController} instead.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @template Class Class type of the function executor
- */
-export interface ILlmController<Class extends object = any> {
-  /** Protocol discriminator. */
-  protocol: "class";
-
-  /** Identifier name of the controller. */
-  name: string;
-
-  /** Application schema of function calling. */
-  application: ILlmApplication<Class>;
-
-  /** Target class instance for function execution. */
-  execute: Class;
-}
+import { ILlmApplication } from "./ILlmApplication";
+
+/**
+ * Controller of TypeScript class-based LLM function calling.
+ *
+ * `ILlmController` is a controller for registering TypeScript class methods as
+ * LLM function calling tools. It contains {@link ILlmApplication} with
+ * {@link ILlmFunction function calling schemas}, {@link name identifier}, and
+ * {@link execute class instance} for method execution.
+ *
+ * You can create this controller with `typia.llm.controller<Class>()` function,
+ * and register it to MCP server with {@link registerMcpControllers}:
+ *
+ * ```typescript
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { registerMcpControllers } from "@typia/mcp";
+ * import typia from "typia";
+ *
+ * class Calculator {
+ *   add(input: { a: number; b: number }): number {
+ *     return input.a + input.b;
+ *   }
+ *   subtract(input: { a: number; b: number }): number {
+ *     return input.a - input.b;
+ *   }
+ * }
+ *
+ * const server = new McpServer({ name: "my-server", version: "1.0.0" });
+ * registerMcpControllers({
+ *   server,
+ *   controllers: [
+ *     typia.llm.controller<Calculator>("calculator", new Calculator()),
+ *   ],
+ * });
+ * ```
+ *
+ * For OpenAPI/HTTP-based controller, use {@link IHttpLlmController} instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Class Class type of the function executor
+ */
+export interface ILlmController<Class extends object = any> {
+  /** Protocol discriminator. */
+  protocol: "class";
+
+  /** Identifier name of the controller. */
+  name: string;
+
+  /** Application schema of function calling. */
+  application: ILlmApplication<Class>;
+
+  /** Target class instance for function execution. */
+  execute: Class;
+}

package/src/schema/ILlmFunction.ts

@@ -1,145 +1,145 @@
-import { tags } from "..";
-import { IJsonParseResult } from "./IJsonParseResult";
-import { ILlmSchema } from "./ILlmSchema";
-import { IValidation } from "./IValidation";
-
-/**
- * LLM function calling schema for TypeScript functions.
- *
- * Generated by `typia.llm.application<App>()` as part of
- * {@link ILlmApplication}.
- *
- * - {@link name}: Function identifier (max 64 chars for OpenAI)
- * - {@link parameters}: Input schema, {@link output}: Return schema
- * - {@link description}: Guides LLM function selection
- * - {@link parse}: Lenient JSON parser with type coercion
- * - {@link validate}: Argument validator for LLM error correction
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export interface ILlmFunction {
-  /**
-   * Function name for LLM invocation.
-   *
-   * The identifier used by the LLM to call this function. Must be unique within
-   * the application.
-   *
-   * OpenAI limits function names to 64 characters.
-   */
-  name: string & tags.MaxLength<64>;
-
-  /**
-   * Schema for function parameters.
-   *
-   * Defines the expected argument types as a JSON Schema object. Contains
-   * `$defs` for shared type definitions and `properties` for each named
-   * parameter.
-   */
-  parameters: ILlmSchema.IParameters;
-
-  /**
-   * Schema for the return type.
-   *
-   * Defines the expected output type as an object parameters schema, wrapping
-   * the return type in an {@link ILlmSchema.IParameters} object with `$defs` for
-   * shared type definitions and `properties` for the structured output.
-   *
-   * `undefined` when the function returns `void` or has no meaningful return
-   * value.
-   */
-  output?: ILlmSchema.IParameters | undefined;
-
-  /**
-   * Human-readable function description.
-   *
-   * Explains what the function does, when to use it, and any important
-   * considerations. This description is crucial for LLMs to understand when to
-   * invoke this function. Extracted from JSDoc comments.
-   */
-  description?: string | undefined;
-
-  /**
-   * Whether this function is deprecated.
-   *
-   * When `true`, indicates the function should no longer be used. LLMs may
-   * still invoke deprecated functions but should prefer non-deprecated
-   * alternatives when available.
-   */
-  deprecated?: boolean | undefined;
-
-  /**
-   * Category tags for function organization.
-   *
-   * Extracted from `@tag` JSDoc annotations. Useful for grouping related
-   * functions and filtering the function list.
-   */
-  tags?: string[] | undefined;
-
-  /**
-   * Lenient JSON parser with schema-based coercion.
-   *
-   * Handles incomplete/malformed JSON commonly produced by LLMs:
-   *
-   * - Unclosed brackets, strings, trailing commas
-   * - JavaScript-style comments (`//` and multi-line)
-   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
-   * - Markdown code block extraction, junk prefix skipping
-   *
-   * Also coerces double-stringified values (`"42"` → `42`) using the
-   * {@link parameters} schema.
-   *
-   * Type validation is NOT performed — use {@link validate} after parsing.
-   *
-   * If the SDK (e.g., LangChain, Vercel AI, MCP) already parses JSON internally
-   * and provides a pre-parsed object, use {@link coerce} instead to apply
-   * schema-based type coercion without re-parsing.
-   *
-   * @param str Raw JSON string from LLM output
-   * @returns Parse result with data on success, or partial data with errors
-   */
-  parse: (str: string) => IJsonParseResult<unknown>;
-
-  /**
-   * Coerce pre-parsed arguments to match expected schema types.
-   *
-   * **Use this only when the SDK (e.g., LangChain, Vercel AI, MCP) already
-   * parses JSON internally.** For raw JSON strings from LLM output, use
-   * {@link parse} instead — it handles both lenient parsing and type coercion in
-   * one step.
-   *
-   * LLMs often return values with incorrect types even after parsing:
-   *
-   * - `"42"` → `42` (when schema expects number)
-   * - `"true"` → `true` (when schema expects boolean)
-   * - `"null"` → `null` (when schema expects null)
-   * - `"{...}"` → `{...}` (when schema expects object)
-   * - `"[...]"` → `[...]` (when schema expects array)
-   *
-   * This function recursively coerces these double-stringified values based on
-   * the {@link parameters} schema.
-   *
-   * Type validation is NOT performed — use {@link validate} after coercion.
-   *
-   * @param data Pre-parsed arguments object from SDK
-   * @returns Coerced arguments with corrected types
-   */
-  coerce: (data: unknown) => unknown;
-
-  /**
-   * Validates LLM-generated arguments against the schema.
-   *
-   * LLMs frequently make type errors such as returning strings instead of
-   * numbers or missing required properties. Use this validator to check
-   * arguments before execution.
-   *
-   * When validation fails, use {@link LlmJson.stringify} from `@typia/utils` to
-   * format the error for LLM feedback. The formatted output shows the invalid
-   * JSON with inline error comments, helping the LLM understand and correct its
-   * mistakes in the next turn.
-   *
-   * @param args The arguments generated by the LLM
-   * @returns Validation result with success status and any errors
-   * @see stringifyValidationFailure Format errors for LLM auto-correction
-   */
-  validate: (args: unknown) => IValidation<unknown>;
-}
+import { tags } from "..";
+import { IJsonParseResult } from "./IJsonParseResult";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM function calling schema for TypeScript functions.
+ *
+ * Generated by `typia.llm.application<App>()` as part of
+ * {@link ILlmApplication}.
+ *
+ * - {@link name}: Function identifier (max 64 chars for OpenAI)
+ * - {@link parameters}: Input schema, {@link output}: Return schema
+ * - {@link description}: Guides LLM function selection
+ * - {@link parse}: Lenient JSON parser with type coercion
+ * - {@link validate}: Argument validator for LLM error correction
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ILlmFunction {
+  /**
+   * Function name for LLM invocation.
+   *
+   * The identifier used by the LLM to call this function. Must be unique within
+   * the application.
+   *
+   * OpenAI limits function names to 64 characters.
+   */
+  name: string & tags.MaxLength<64>;
+
+  /**
+   * Schema for function parameters.
+   *
+   * Defines the expected argument types as a JSON Schema object. Contains
+   * `$defs` for shared type definitions and `properties` for each named
+   * parameter.
+   */
+  parameters: ILlmSchema.IParameters;
+
+  /**
+   * Schema for the return type.
+   *
+   * Defines the expected output type as an object parameters schema, wrapping
+   * the return type in an {@link ILlmSchema.IParameters} object with `$defs` for
+   * shared type definitions and `properties` for the structured output.
+   *
+   * `undefined` when the function returns `void` or has no meaningful return
+   * value.
+   */
+  output?: ILlmSchema.IParameters | undefined;
+
+  /**
+   * Human-readable function description.
+   *
+   * Explains what the function does, when to use it, and any important
+   * considerations. This description is crucial for LLMs to understand when to
+   * invoke this function. Extracted from JSDoc comments.
+   */
+  description?: string | undefined;
+
+  /**
+   * Whether this function is deprecated.
+   *
+   * When `true`, indicates the function should no longer be used. LLMs may
+   * still invoke deprecated functions but should prefer non-deprecated
+   * alternatives when available.
+   */
+  deprecated?: boolean | undefined;
+
+  /**
+   * Category tags for function organization.
+   *
+   * Extracted from `@tag` JSDoc annotations. Useful for grouping related
+   * functions and filtering the function list.
+   */
+  tags?: string[] | undefined;
+
+  /**
+   * Lenient JSON parser with schema-based coercion.
+   *
+   * Handles incomplete/malformed JSON commonly produced by LLMs:
+   *
+   * - Unclosed brackets, strings, trailing commas
+   * - JavaScript-style comments (`//` and multi-line)
+   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
+   * - Markdown code block extraction, junk prefix skipping
+   *
+   * Also coerces double-stringified values (`"42"` → `42`) using the
+   * {@link parameters} schema.
+   *
+   * Type validation is NOT performed — use {@link validate} after parsing.
+   *
+   * If the SDK (e.g., LangChain, Vercel AI, MCP) already parses JSON internally
+   * and provides a pre-parsed object, use {@link coerce} instead to apply
+   * schema-based type coercion without re-parsing.
+   *
+   * @param str Raw JSON string from LLM output
+   * @returns Parse result with data on success, or partial data with errors
+   */
+  parse: (str: string) => IJsonParseResult<unknown>;
+
+  /**
+   * Coerce pre-parsed arguments to match expected schema types.
+   *
+   * **Use this only when the SDK (e.g., LangChain, Vercel AI, MCP) already
+   * parses JSON internally.** For raw JSON strings from LLM output, use
+   * {@link parse} instead — it handles both lenient parsing and type coercion in
+   * one step.
+   *
+   * LLMs often return values with incorrect types even after parsing:
+   *
+   * - `"42"` → `42` (when schema expects number)
+   * - `"true"` → `true` (when schema expects boolean)
+   * - `"null"` → `null` (when schema expects null)
+   * - `"{...}"` → `{...}` (when schema expects object)
+   * - `"[...]"` → `[...]` (when schema expects array)
+   *
+   * This function recursively coerces these double-stringified values based on
+   * the {@link parameters} schema.
+   *
+   * Type validation is NOT performed — use {@link validate} after coercion.
+   *
+   * @param data Pre-parsed arguments object from SDK
+   * @returns Coerced arguments with corrected types
+   */
+  coerce: (data: unknown) => unknown;
+
+  /**
+   * Validates LLM-generated arguments against the schema.
+   *
+   * LLMs frequently make type errors such as returning strings instead of
+   * numbers or missing required properties. Use this validator to check
+   * arguments before execution.
+   *
+   * When validation fails, use {@link LlmJson.stringify} from `@typia/utils` to
+   * format the error for LLM feedback. The formatted output shows the invalid
+   * JSON with inline error comments, helping the LLM understand and correct its
+   * mistakes in the next turn.
+   *
+   * @param args The arguments generated by the LLM
+   * @returns Validation result with success status and any errors
+   * @see stringifyValidationFailure Format errors for LLM auto-correction
+   */
+  validate: (args: unknown) => IValidation<unknown>;
+}