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

package/lib/schema/ILlmApplication.d.ts

@@ -83,6 +83,6 @@ export declare namespace ILlmApplication {
      * @ignore
      */
     interface __IPrimitive<Class extends object = any> extends Omit<ILlmApplication<Class>, "config" | "functions"> {
-        functions: Omit<ILlmFunction, "parse">[];
+        functions: Omit<ILlmFunction, "parse" | "coerce">[];
     }
 }

package/lib/schema/ILlmFunction.d.ts

@@ -1,3 +1,4 @@
+import { tags } from "..";
 import { IJsonParseResult } from "./IJsonParseResult";
 import { ILlmSchema } from "./ILlmSchema";
 import { IValidation } from "./IValidation";
@@ -20,11 +21,11 @@ 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.
+     * the application.
      *
-     * @maxLength 64
+     * OpenAI limits function names to 64 characters.
      */
-    name: string;
+    name: string & tags.MaxLength<64>;
     /**
      * Schema for function parameters.
      *
@@ -82,10 +83,39 @@ export interface ILlmFunction {
      *
      * 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.
      *
@@ -93,10 +123,10 @@ export interface ILlmFunction {
      * numbers or missing required properties. Use this validator to check
      * arguments before execution.
      *
-     * When validation fails, use `stringifyValidationFailure()` 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.
+     * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typia/interface",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260309",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "exports": {

package/src/schema/ILlmApplication.ts

@@ -94,6 +94,6 @@ export namespace ILlmApplication {
     ILlmApplication<Class>,
     "config" | "functions"
   > {
-    functions: Omit<ILlmFunction, "parse">[];
+    functions: Omit<ILlmFunction, "parse" | "coerce">[];
   }
 }

package/src/schema/ILlmFunction.ts

@@ -1,3 +1,4 @@
+import { tags } from "..";
 import { IJsonParseResult } from "./IJsonParseResult";
 import { ILlmSchema } from "./ILlmSchema";
 import { IValidation } from "./IValidation";
@@ -21,11 +22,11 @@ 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.
+   * the application.
    *
-   * @maxLength 64
+   * OpenAI limits function names to 64 characters.
    */
-  name: string;
+  name: string & tags.MaxLength<64>;
 
   /**
    * Schema for function parameters.
@@ -89,11 +90,41 @@ export interface ILlmFunction {
    *
    * 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.
    *
@@ -101,10 +132,10 @@ export interface ILlmFunction {
    * numbers or missing required properties. Use this validator to check
    * arguments before execution.
    *
-   * When validation fails, use `stringifyValidationFailure()` 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.
+   * 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