feat(utils): LlmJson.coerce for already json parsed SDKs. (#1769)

samchon · web-flow · commit c87511d3ca6b · 2026-03-07T17:03:45.000+09:00
* feat(utils): `LlmJson.coerce` for already json parsed SDKs.

* next version packaging.

* fix something?
diff --git a/benchmark/package.json b/benchmark/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/benchmark",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Benchmark program of typia performance",
   "main": "bin/index.js",
   "scripts": {
diff --git a/config/package.json b/config/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/config",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Shared build configuration for typia packages",
   "devDependencies": {
     "@rollup/plugin-commonjs": "catalog:rollup",
diff --git a/examples/package.json b/examples/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/examples",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Example codes for typia website",
   "scripts": {
     "build": "rimraf bin && cross-env NODE_OPTIONS=\"--no-experimental-strip-types -r ts-node/register\" tsc && prettier --write bin/**/*.js",
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/station",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Typia Station",
   "scripts": {
     "build": "pnpm --filter=./packages/* -r build",
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/core",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/interface/package.json b/packages/interface/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/interface",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/interface/src/schema/ILlmFunction.ts b/packages/interface/src/schema/ILlmFunction.ts
@@ -89,6 +89,10 @@ 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 `LlmJson.coerce()` from `@typia/utils`
+   * 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
    */
diff --git a/packages/langchain/package.json b/packages/langchain/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/langchain",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "LangChain.js integration for typia",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/langchain/src/internal/LangChainToolsRegistrar.ts b/packages/langchain/src/internal/LangChainToolsRegistrar.ts
@@ -113,8 +113,9 @@ export namespace LangChainToolsRegistrar {
       description: entry.function.description ?? "",
       schema: passthroughSchema,
       func: async (args: unknown): Promise<string> => {
+        const coerced: unknown = LlmJson.coerce(args, entry.function.parameters);
         const validation: IValidation<unknown> =
-          entry.function.validate(args);
+          entry.function.validate(coerced);
         if (!validation.success) {
           return LlmJson.stringify(validation);
         }
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/mcp",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "MCP (Model Context Protocol) integration for typia",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/mcp/src/internal/McpControllerRegistrar.ts b/packages/mcp/src/internal/McpControllerRegistrar.ts
@@ -260,7 +260,8 @@ export namespace McpControllerRegistrar {
     entry: IToolEntry,
     args: unknown,
   ): Promise<CallToolResult> => {
-    const validation: IValidation<unknown> = entry.function.validate(args);
+    const coerced: unknown = LlmJson.coerce(args, entry.function.parameters);
+    const validation: IValidation<unknown> = entry.function.validate(coerced);
     if (!validation.success) {
       return {
         isError: true,
diff --git a/packages/transform/package.json b/packages/transform/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/transform",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/typia/package.json b/packages/typia/package.json
@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/unplugin/package.json b/packages/unplugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@typia/unplugin",
   "type": "module",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "private": true,
   "description": "unplugin for typia",
   "author": "ryoppippi",
diff --git a/packages/utils/package.json b/packages/utils/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/utils",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/utils/src/utils/LlmJson.ts b/packages/utils/src/utils/LlmJson.ts
@@ -21,6 +21,32 @@ import { stringifyValidationFailure } from "./internal/stringifyValidationFailur
  * @author Jeongho Nam - https://github.com/samchon
  */
 export namespace LlmJson {
+  /**
+   * Coerce LLM arguments to match expected schema types.
+   *
+   * LLMs often return values with incorrect types (e.g., numbers as strings).
+   * This function recursively coerces values based on the schema:
+   *
+   * - `"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)
+   *
+   * Use this when SDK provides already-parsed objects but values may have
+   * wrong types. For raw JSON strings, use {@link parse} instead.
+   *
+   * @param input Parsed arguments object from LLM
+   * @param parameters LLM function parameters schema for type coercion
+   * @returns Coerced arguments with corrected types
+   */
+  export function coerce<T = unknown>(
+    input: T,
+    parameters: ILlmSchema.IParameters,
+  ): T {
+    return coerceLlmArguments(input, parameters);
+  }
+
   /**
    * Parse lenient JSON with optional schema-based coercion.
    *
diff --git a/packages/utils/src/utils/internal/coerceLlmArguments.ts b/packages/utils/src/utils/internal/coerceLlmArguments.ts
@@ -17,11 +17,11 @@ import { parseLenientJson } from "./parseLenientJson";
  * @returns Coerced value with double-stringified JSON parsed
  * @internal
  */
-export function coerceLlmArguments(
-  value: unknown,
+export function coerceLlmArguments<T = unknown>(
+  value: T,
   parameters: ILlmSchema.IParameters,
-): unknown {
-  return coerceValue(value, parameters, parameters.$defs);
+): T {
+  return coerceValue(value, parameters, parameters.$defs) as T;
 }
 
 function coerceValue(
diff --git a/packages/vercel/package.json b/packages/vercel/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@typia/vercel",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Vercel AI SDK integration for typia",
   "main": "src/index.ts",
   "exports": {
diff --git a/packages/vercel/src/internal/VercelToolsRegistrar.ts b/packages/vercel/src/internal/VercelToolsRegistrar.ts
@@ -135,8 +135,9 @@ export namespace VercelToolsRegistrar {
       ),
 
       execute: async (args: object) => {
-        // Validate using typia's built-in validator
-        const validation: IValidation<unknown> = func.validate(args);
+        // Coerce and validate using typia's built-in functions
+        const coerced: unknown = LlmJson.coerce(args, func.parameters);
+        const validation: IValidation<unknown> = func.validate(coerced);
         if (!validation.success) {
           // Return validation error in LLM-friendly format
           return {
diff --git a/tests/debug/package.json b/tests/debug/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/debug",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Convenient debug program for typia",
   "scripts": {
     "start": "ts-node src/index.ts"
diff --git a/tests/template/package.json b/tests/template/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/template",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Template structures for typia testing.",
   "main": "src/index.ts",
   "repository": {
diff --git a/tests/test-error/package.json b/tests/test-error/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-error",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test program of typia generated error",
   "main": "index.js",
   "scripts": {
diff --git a/tests/test-langchain/package.json b/tests/test-langchain/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-langchain",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test suite for @typia/langchain package",
   "scripts": {
     "start": "ts-node src/index.ts"
diff --git a/tests/test-langchain/src/features/test_langchain_class_controller_validation.ts b/tests/test-langchain/src/features/test_langchain_class_controller_validation.ts
@@ -29,10 +29,11 @@ export const test_langchain_class_controller_validation =
     const invalidResult = await addTool.invoke({ x: "not a number", y: 5 });
 
     // Generate expected validation error message using typia
-    const expected: IValidation = typia.validate<Calculator.IProps>({
-      x: "not a number",
-      y: 5,
-    });
+    const coerced: unknown = LlmJson.coerce(
+      { x: "not a number", y: 5 },
+      controller.application.functions.find((f) => f.name === "add")!.parameters,
+    );
+    const expected: IValidation = typia.validate<Calculator.IProps>(coerced);
     if (expected.success === true) {
       throw new Error("Expected validation to fail, but it succeeded.");
     }
diff --git a/tests/test-langchain/src/features/test_langchain_http_controller_validation.ts b/tests/test-langchain/src/features/test_langchain_http_controller_validation.ts
@@ -82,6 +82,11 @@ export const test_langchain_http_controller_validation =
     const result = await addTool.invoke(invalidArgs);
 
     // 6. Verify validation matches LlmJson.stringify output
+    const func = controller.application.functions.find(
+      (f) => f.name === "calculate_add_post",
+    )!;
+    const coerced: unknown = LlmJson.coerce(invalidArgs, func.parameters);
+
     const parameterSchema: OpenApi.IJsonSchema.IObject = {
       type: "object",
       properties: {
@@ -93,7 +98,7 @@ export const test_langchain_http_controller_validation =
     const expected: IValidation = OpenApiValidator.validate({
       components: {},
       schema: parameterSchema,
-      value: invalidArgs,
+      value: coerced,
       required: true,
       equals: false,
     });
diff --git a/tests/test-mcp/package.json b/tests/test-mcp/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-mcp",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test suite for @typia/mcp package",
   "scripts": {
     "start": "ts-node src/index.ts"
diff --git a/tests/test-mcp/src/features/test_mcp_class_controller_validation.ts b/tests/test-mcp/src/features/test_mcp_class_controller_validation.ts
@@ -54,10 +54,11 @@ export const test_mcp_class_controller_validation = async (): Promise<void> => {
     },
     { signal: new AbortController().signal },
   );
-  const expected: IValidation = typia.validate<Calculator.IProps>({
-    x: "not a number",
-    y: 5,
-  });
+  const coerced: unknown = LlmJson.coerce(
+    { x: "not a number", y: 5 },
+    controller.application.functions.find((f) => f.name === "add")!.parameters,
+  );
+  const expected: IValidation = typia.validate<Calculator.IProps>(coerced);
   if (expected.success === true)
     throw new Error("Expected validation to fail, but it succeeded.");
 
diff --git a/tests/test-mcp/src/features/test_mcp_http_controller_validation.ts b/tests/test-mcp/src/features/test_mcp_http_controller_validation.ts
@@ -107,6 +107,11 @@ export const test_mcp_http_controller_validation = async (): Promise<void> => {
   );
 
   // 7. Verify validation matches LlmJson.stringify output
+  const func = controller.application.functions.find(
+    (f) => f.name === "calculate_add_post",
+  )!;
+  const coerced: unknown = LlmJson.coerce(invalidArgs, func.parameters);
+
   const parameterSchema: OpenApi.IJsonSchema.IObject = {
     type: "object",
     properties: {
@@ -118,7 +123,7 @@ export const test_mcp_http_controller_validation = async (): Promise<void> => {
   const expected: IValidation = OpenApiValidator.validate({
     components: {},
     schema: parameterSchema,
-    value: invalidArgs,
+    value: coerced,
     required: true,
     equals: false,
   });
diff --git a/tests/test-typia-automated/package.json b/tests/test-typia-automated/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-typia-automated",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Automated test features of typia.",
   "scripts": {
     "start": "ts-node src/index.ts"
diff --git a/tests/test-typia-generate/package.json b/tests/test-typia-generate/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-typia-generate",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test typia generation command",
   "scripts": {
     "build": "cross-env NODE_OPTIONS=\"--no-experimental-strip-types -r ts-node/register\" tsc",
diff --git a/tests/test-typia-schema/package.json b/tests/test-typia-schema/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-typia-schema",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test features for JSON schema, LLM schema and protobuf message of typia.",
   "scripts": {
     "dev": "tsc --watch",
diff --git a/tests/test-unplugin/package.json b/tests/test-unplugin/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-unplugin",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "type": "module",
   "description": "Test for @typia/unplugin package",
   "scripts": {
diff --git a/tests/test-utils-automated/package.json b/tests/test-utils-automated/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-openapiautomated",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Automated test features of openapi.",
   "scripts": {
     "start": "node -r ts-node/register src/index.ts"
diff --git a/tests/test-utils/package.json b/tests/test-utils/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-utils",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Automated test features of typia.",
   "scripts": {
     "dev": "tsc --watch",
diff --git a/tests/test-vercel/package.json b/tests/test-vercel/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/test-vercel",
-  "version": "12.0.0-dev.20260307",
+  "version": "12.0.0-dev.20260307-2",
   "description": "Test suite for @typia/vercel package",
   "scripts": {
     "start": "ts-node src/index.ts"
diff --git a/tests/test-vercel/src/features/test_vercel_class_controller_validation.ts b/tests/test-vercel/src/features/test_vercel_class_controller_validation.ts
@@ -26,10 +26,11 @@ export const test_vercel_class_controller_validation =
     );
 
     // 4. Verify the result contains validation error
-    const expected: IValidation = typia.validate<Calculator.IProps>({
-      x: "not a number",
-      y: 5,
-    });
+    const coerced: unknown = LlmJson.coerce(
+      { x: "not a number", y: 5 },
+      controller.application.functions.find((f) => f.name === "add")!.parameters,
+    );
+    const expected: IValidation = typia.validate<Calculator.IProps>(coerced);
     if (expected.success === true)
       throw new Error("Expected validation to fail, but it succeeded.");
 

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"private": true,`
`3`	`3`	`"name": "@typia/benchmark",`
`4`		`- "version": "12.0.0-dev.20260307",`
	`4`	`+ "version": "12.0.0-dev.20260307-2",`
`5`	`5`	`"description": "Benchmark program of typia performance",`
`6`	`6`	`"main": "bin/index.js",`
`7`	`7`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"private": true,`
`3`	`3`	`"name": "@typia/config",`
`4`		`- "version": "12.0.0-dev.20260307",`
	`4`	`+ "version": "12.0.0-dev.20260307-2",`
`5`	`5`	`"description": "Shared build configuration for typia packages",`
`6`	`6`	`"devDependencies": {`
`7`	`7`	`"@rollup/plugin-commonjs": "catalog:rollup",`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"private": true,`
`3`	`3`	`"name": "@typia/examples",`
`4`		`- "version": "12.0.0-dev.20260307",`
	`4`	`+ "version": "12.0.0-dev.20260307-2",`
`5`	`5`	`"description": "Example codes for typia website",`
`6`	`6`	`"scripts": {`
`7`	`7`	`"build": "rimraf bin && cross-env NODE_OPTIONS=\"--no-experimental-strip-types -r ts-node/register\" tsc && prettier --write bin/*/.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"private": true,`
`3`	`3`	`"name": "@typia/station",`
`4`		`- "version": "12.0.0-dev.20260307",`
	`4`	`+ "version": "12.0.0-dev.20260307-2",`
`5`	`5`	`"description": "Typia Station",`
`6`	`6`	`"scripts": {`
`7`	`7`	`"build": "pnpm --filter=./packages/* -r build",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@typia/core",`
`3`		`- "version": "12.0.0-dev.20260307",`
	`3`	`+ "version": "12.0.0-dev.20260307-2",`
`4`	`4`	`"description": "Superfast runtime validators with only one line",`
`5`	`5`	`"main": "src/index.ts",`
`6`	`6`	`"exports": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@typia/interface",`
`3`		`- "version": "12.0.0-dev.20260307",`
	`3`	`+ "version": "12.0.0-dev.20260307-2",`
`4`	`4`	`"description": "Superfast runtime validators with only one line",`
`5`	`5`	`"main": "src/index.ts",`
`6`	`6`	`"exports": {`
Original file line number	Diff line number	Diff line change
`@@ -89,6 +89,10 @@ export interface ILlmFunction {`
`89`	`89`	`*`
`90`	`90`	`* Type validation is NOT performed — use {@link validate} after parsing.`
`91`	`91`	`*`
	`92`	`+ * If the SDK (e.g., LangChain, Vercel AI, MCP) already parses JSON internally`
	`93`	+ * and provides a pre-parsed object, use `LlmJson.coerce()` from `@typia/utils`
	`94`	`+ * instead to apply schema-based type coercion without re-parsing.`
	`95`	`+ *`
`92`	`96`	`* @param str Raw JSON string from LLM output`
`93`	`97`	`* @returns Parse result with data on success, or partial data with errors`
`94`	`98`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@typia/langchain",`
`3`		`- "version": "12.0.0-dev.20260307",`
	`3`	`+ "version": "12.0.0-dev.20260307-2",`
`4`	`4`	`"description": "LangChain.js integration for typia",`
`5`	`5`	`"main": "src/index.ts",`
`6`	`6`	`"exports": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@typia/mcp",`
`3`		`- "version": "12.0.0-dev.20260307",`
	`3`	`+ "version": "12.0.0-dev.20260307-2",`
`4`	`4`	`"description": "MCP (Model Context Protocol) integration for typia",`
`5`	`5`	`"main": "src/index.ts",`
`6`	`6`	`"exports": {`