@typia/interface 12.0.0-dev.20260315 → 12.0.0

package/src/schema/ILlmStructuredOutput.ts

@@ -1,112 +1,112 @@
-import { IJsonParseResult } from "./IJsonParseResult";
-import { ILlmSchema } from "./ILlmSchema";
-import { IValidation } from "./IValidation";
-
-/**
- * LLM structured output schema with parsing and validation utilities.
- *
- * `ILlmStructuredOutput<T>` is generated by `typia.llm.structuredOutput<T>()`
- * to provide everything needed for handling LLM structured outputs: the JSON
- * schema for prompting, and functions for parsing, coercing, and validating
- * responses.
- *
- * Structured outputs allow LLMs to generate data conforming to a predefined
- * schema instead of free-form text. This is useful for:
- *
- * - Extracting structured data from conversations
- * - Generating typed responses for downstream processing
- * - Ensuring consistent output formats across LLM calls
- *
- * Workflow:
- *
- * 1. Pass {@link parameters} schema to LLM provider
- * 2. Receive LLM response (JSON string or pre-parsed object)
- * 3. Use {@link parse} for raw strings or {@link coerce} for pre-parsed objects
- * 4. Use {@link validate} to check the result and get detailed errors
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @template T The expected output type
- */
-export interface ILlmStructuredOutput<T = unknown> {
-  /**
-   * JSON schema for the structured output.
-   *
-   * Pass this schema to LLM providers (OpenAI, Anthropic, Google, etc.) to
-   * constrain the output format. The schema includes `$defs` for shared type
-   * definitions and `properties` for the output structure.
-   *
-   * Most LLM providers accept this directly in their structured output or
-   * response format configuration.
-   */
-  parameters: ILlmSchema.IParameters;
-
-  /**
-   * Lenient JSON parser with schema-based type coercion.
-   *
-   * Handles incomplete or 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 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)
-   *
-   * 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.
-   *
-   * @param input Raw JSON string from LLM output
-   * @returns Parse result with data on success, or partial data with errors
-   */
-  parse: (input: string) => IJsonParseResult<T>;
-
-  /**
-   * Coerce pre-parsed output to match expected schema types.
-   *
-   * **Use this only when the SDK 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 input Pre-parsed output object from SDK
-   * @returns Coerced output with corrected types
-   */
-  coerce: (input: unknown) => T;
-
-  /**
-   * Validates LLM-generated output against the schema.
-   *
-   * LLMs frequently make type errors such as returning strings instead of
-   * numbers or missing required properties. Use this validator to check output
-   * before further processing.
-   *
-   * 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 input The output generated by the LLM
-   * @returns Validation result with success status and any errors
-   */
-  validate: (input: unknown) => IValidation<T>;
-}
+import { IJsonParseResult } from "./IJsonParseResult";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM structured output schema with parsing and validation utilities.
+ *
+ * `ILlmStructuredOutput<T>` is generated by `typia.llm.structuredOutput<T>()`
+ * to provide everything needed for handling LLM structured outputs: the JSON
+ * schema for prompting, and functions for parsing, coercing, and validating
+ * responses.
+ *
+ * Structured outputs allow LLMs to generate data conforming to a predefined
+ * schema instead of free-form text. This is useful for:
+ *
+ * - Extracting structured data from conversations
+ * - Generating typed responses for downstream processing
+ * - Ensuring consistent output formats across LLM calls
+ *
+ * Workflow:
+ *
+ * 1. Pass {@link parameters} schema to LLM provider
+ * 2. Receive LLM response (JSON string or pre-parsed object)
+ * 3. Use {@link parse} for raw strings or {@link coerce} for pre-parsed objects
+ * 4. Use {@link validate} to check the result and get detailed errors
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T The expected output type
+ */
+export interface ILlmStructuredOutput<T = unknown> {
+  /**
+   * JSON schema for the structured output.
+   *
+   * Pass this schema to LLM providers (OpenAI, Anthropic, Google, etc.) to
+   * constrain the output format. The schema includes `$defs` for shared type
+   * definitions and `properties` for the output structure.
+   *
+   * Most LLM providers accept this directly in their structured output or
+   * response format configuration.
+   */
+  parameters: ILlmSchema.IParameters;
+
+  /**
+   * Lenient JSON parser with schema-based type coercion.
+   *
+   * Handles incomplete or 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 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)
+   *
+   * 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.
+   *
+   * @param input Raw JSON string from LLM output
+   * @returns Parse result with data on success, or partial data with errors
+   */
+  parse: (input: string) => IJsonParseResult<T>;
+
+  /**
+   * Coerce pre-parsed output to match expected schema types.
+   *
+   * **Use this only when the SDK 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 input Pre-parsed output object from SDK
+   * @returns Coerced output with corrected types
+   */
+  coerce: (input: unknown) => T;
+
+  /**
+   * Validates LLM-generated output against the schema.
+   *
+   * LLMs frequently make type errors such as returning strings instead of
+   * numbers or missing required properties. Use this validator to check output
+   * before further processing.
+   *
+   * 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 input The output generated by the LLM
+   * @returns Validation result with success status and any errors
+   */
+  validate: (input: unknown) => IValidation<T>;
+}

package/src/schema/index.ts

@@ -1,15 +1,15 @@
-export * from "./IResult";
-export * from "./IValidation";
-
-export * from "./IJsonSchemaTransformError";
-export * from "./IJsonSchemaApplication";
-export * from "./IJsonSchemaCollection";
-export * from "./IJsonSchemaUnit";
-export * from "./IJsonSchemaAttribute";
-
-export * from "./ILlmController";
-export * from "./ILlmApplication";
-export * from "./ILlmFunction";
-export * from "./ILlmSchema";
-export * from "./ILlmStructuredOutput";
-export * from "./IJsonParseResult";
+export * from "./IResult";
+export * from "./IValidation";
+
+export * from "./IJsonSchemaTransformError";
+export * from "./IJsonSchemaApplication";
+export * from "./IJsonSchemaCollection";
+export * from "./IJsonSchemaUnit";
+export * from "./IJsonSchemaAttribute";
+
+export * from "./ILlmController";
+export * from "./ILlmApplication";
+export * from "./ILlmFunction";
+export * from "./ILlmSchema";
+export * from "./ILlmStructuredOutput";
+export * from "./IJsonParseResult";