@typia/interface 12.0.0-dev.20260225

package/src/schema/IJsonSchemaUnit.ts

@@ -0,0 +1,120 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { OpenApiV3 } from "../openapi/OpenApiV3";
+
+/**
+ * Single JSON schema unit for one TypeScript type.
+ *
+ * `IJsonSchemaUnit` represents a complete JSON schema for a single TypeScript
+ * type, including the main schema definition and any referenced component
+ * schemas. Generated by `typia.json.schema<T>()` at compile time.
+ *
+ * The result contains:
+ *
+ * - {@link IV3_0.schema | schema}: The main JSON schema for the type
+ * - {@link IV3_0.components | components}: Shared schemas referenced via `$ref`
+ * - {@link IV3_0.__type | __type}: Phantom property for TypeScript type inference
+ *
+ * Use this for single-type schema generation. For multiple types, see
+ * {@link IJsonSchemaCollection}. For function schemas, see
+ * {@link IJsonSchemaApplication}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Version OpenAPI version ("3.0" or "3.1")
+ * @template Type Original TypeScript type
+ */
+export type IJsonSchemaUnit<
+  Version extends "3.0" | "3.1" = "3.1",
+  Type = unknown,
+> = Version extends "3.0"
+  ? IJsonSchemaUnit.IV3_0<Type>
+  : IJsonSchemaUnit.IV3_1<Type>;
+
+export namespace IJsonSchemaUnit {
+  /**
+   * JSON Schema unit for OpenAPI v3.0 specification.
+   *
+   * Uses OpenAPI v3.0 compatible JSON Schema format. In v3.0, nullable types
+   * are expressed with `nullable: true` rather than v3.1's `type: ["string",
+   * "null"]`.
+   *
+   * @template Type Original TypeScript type for phantom type preservation
+   */
+  export interface IV3_0<Type> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.0"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.0";
+
+    /**
+     * The main JSON schema definition for the type.
+     *
+     * Contains the complete schema for the target TypeScript type. May include
+     * `$ref` references to schemas in {@link components}.
+     */
+    schema: OpenApiV3.IJsonSchema;
+
+    /**
+     * Reusable schema definitions for `$ref` references.
+     *
+     * Contains named schemas that can be referenced throughout the main schema.
+     * Essential for recursive types and reducing duplication.
+     */
+    components: OpenApiV3.IComponents;
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Type`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __type?: Type | undefined;
+  }
+
+  /**
+   * JSON Schema unit for OpenAPI v3.1 specification.
+   *
+   * Uses OpenAPI v3.1 compatible JSON Schema format. v3.1 aligns more closely
+   * with JSON Schema draft 2020-12, supporting features like `type` arrays for
+   * nullable types and `const` values.
+   *
+   * @template Type Original TypeScript type for phantom type preservation
+   */
+  export interface IV3_1<Type> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.1"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.1";
+
+    /**
+     * The main JSON schema definition for the type.
+     *
+     * Contains the complete schema for the target TypeScript type. May include
+     * `$ref` references to schemas in {@link components}.
+     */
+    schema: OpenApi.IJsonSchema;
+
+    /**
+     * Reusable schema definitions for `$ref` references.
+     *
+     * Contains named schemas that can be referenced throughout the main schema.
+     * Essential for recursive types and reducing duplication.
+     */
+    components: OpenApi.IComponents;
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Type`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __type?: Type | undefined;
+  }
+}

package/src/schema/ILlmApplication.ts

@@ -0,0 +1,103 @@
+import { ILlmFunction } from "./ILlmFunction";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM function calling application.
+ *
+ * `ILlmApplication` is a collection of {@link ILlmFunction} schemas generated
+ * from a TypeScript class or interface by `typia.llm.application<App>()`. Each
+ * public method becomes an {@link ILlmFunction} that LLM agents can invoke.
+ *
+ * Configure behavior via {@link ILlmApplication.IConfig}:
+ *
+ * - {@link ILlmApplication.IConfig.separate}: Split parameters into LLM-fillable
+ *   vs human-required (e.g., file uploads, passwords)
+ * - {@link ILlmApplication.IConfig.validate}: Custom validation per method
+ * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
+ * - {@link ILlmSchema.IConfig.reference}: Control `$ref` inlining behavior
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Class Source class/interface type
+ */
+export interface ILlmApplication<Class extends object = any> {
+  /**
+   * Array of callable function schemas.
+   *
+   * Each function represents a method from the source class that the LLM can
+   * invoke. Functions include parameter schemas, descriptions, and validation
+   * logic for type-safe function calling.
+   */
+  functions: ILlmFunction[];
+
+  /**
+   * Configuration used to generate this application.
+   *
+   * Contains the settings that were applied during schema generation, including
+   * reference handling, strict mode, and parameter separation.
+   */
+  config: ILlmApplication.IConfig<Class>;
+
+  /**
+   * Phantom property for TypeScript generic type preservation.
+   *
+   * This property exists only in the type system to preserve the `Class`
+   * generic parameter at compile time. It is always `undefined` at runtime and
+   * should not be accessed or used in application code.
+   *
+   * This pattern enables type inference to recover the original class type from
+   * an `ILlmApplication` instance, useful for type-safe function routing.
+   */
+  __class?: Class | undefined;
+}
+export namespace ILlmApplication {
+  /**
+   * Configuration for LLM application generation.
+   *
+   * Extends {@link ILlmSchema.IConfig} with application-specific options for
+   * parameter separation and custom validation. These settings control how the
+   * application schema is generated from the source class.
+   */
+  export interface IConfig<Class extends object = any>
+    extends ILlmSchema.IConfig {
+    /**
+     * Function to separate LLM-fillable from human-required parameters.
+     *
+     * When provided, this function is called for each parameter schema to
+     * determine if it should be filled by the LLM (`false`) or require human
+     * input (`true`). Use this for sensitive data like passwords, file uploads,
+     * or data the LLM cannot generate.
+     *
+     * @default null (no separation)
+     * @param schema - The parameter schema to evaluate
+     * @returns `true` if human input required, `false` if LLM can fill
+     */
+    separate: null | ((schema: ILlmSchema) => boolean);
+
+    /**
+     * Custom validation functions per method name.
+     *
+     * Allows overriding the default type-based validation with custom business
+     * logic. Useful for complex validation rules that cannot be expressed in
+     * JSON Schema.
+     *
+     * @default null (use default type validation)
+     */
+    validate: null | Partial<ILlmApplication.IValidationHook<Class>>;
+  }
+
+  /**
+   * Type-safe mapping of method names to custom validators.
+   *
+   * Maps each method name to a validation function that receives the raw input
+   * and returns a validation result. The type inference ensures validators
+   * match the expected argument types.
+   *
+   * @template Class - The source class type for type inference
+   */
+  export type IValidationHook<Class extends object> = {
+    [K in keyof Class]?: Class[K] extends (args: infer Argument) => unknown
+      ? (input: unknown) => IValidation<Argument>
+      : never;
+  };
+}

package/src/schema/ILlmController.ts

@@ -0,0 +1,57 @@
+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;
+}

package/src/schema/ILlmFunction.ts

@@ -0,0 +1,144 @@
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM function calling metadata.
+ *
+ * `ILlmFunction` describes a single callable function for LLM agents. Generated
+ * as part of {@link ILlmApplication} by `typia.llm.application<App>()`.
+ *
+ * Contains the function {@link name} (max 64 chars for OpenAI),
+ * {@link parameters} schema for input types, optional {@link output} schema for
+ * return type, and {@link description} for LLM to understand the function's
+ * purpose.
+ *
+ * The built-in {@link validate} function checks LLM-generated arguments against
+ * the schema, enabling auto-correction when the LLM makes type errors (e.g.,
+ * returning `"123"` instead of `123`).
+ *
+ * Use {@link separated} when some parameters require human input (files,
+ * passwords) via {@link ILlmApplication.IConfig.separate}.
+ *
+ * @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.
+   *
+   * @maxLength 64
+   */
+  name: string;
+
+  /**
+   * 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;
+
+  /**
+   * Parameters split between LLM and human input.
+   *
+   * Present when {@link ILlmApplication.IConfig.separate} is configured. Allows
+   * separating parameters that the LLM can fill from those requiring human
+   * input (e.g., file uploads, passwords).
+   */
+  separated?: ILlmFunction.ISeparated;
+
+  /**
+   * Schema for the return type.
+   *
+   * Defines the expected output type as a JSON Schema. `undefined` when the
+   * function returns `void` or has no meaningful return value.
+   */
+  output?: ILlmSchema | 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;
+
+  /**
+   * 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 `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.
+   *
+   * @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>;
+}
+export namespace ILlmFunction {
+  /**
+   * Separated parameter schemas for hybrid LLM/human input.
+   *
+   * When a function has parameters that cannot or should not be filled by the
+   * LLM (e.g., file uploads, passwords, sensitive data), the parameters are
+   * split into two schemas.
+   */
+  export interface ISeparated {
+    /**
+     * Parameters the LLM should fill.
+     *
+     * Contains only the parameters that are safe and appropriate for the LLM to
+     * generate values for.
+     */
+    llm: ILlmSchema.IParameters;
+
+    /**
+     * Parameters requiring human input.
+     *
+     * Contains parameters that must be provided by the user directly, such as
+     * file uploads, passwords, or other sensitive data. `null` when all
+     * parameters can be filled by the LLM.
+     */
+    human: ILlmSchema.IParameters | null;
+
+    /**
+     * Validates the LLM portion of separated parameters.
+     *
+     * Validates only the LLM-fillable portion, allowing human parameters to be
+     * validated separately with appropriate handling.
+     *
+     * When validation fails, use `stringifyValidationFailure()` from
+     * `@typia/utils` to format the error for LLM feedback.
+     *
+     * @see stringifyValidationFailure Format errors for LLM auto-correction
+     */
+    validate?: ((args: unknown) => IValidation<unknown>) | undefined;
+  }
+}