@typia/interface 12.0.0-dev.20260225

package/lib/schema/IJsonSchemaUnit.d.ts

@@ -0,0 +1,106 @@
+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 declare 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
+     */
+    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
+     */
+    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/lib/schema/IJsonSchemaUnit.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IJsonSchemaUnit.js.map

package/lib/schema/IJsonSchemaUnit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IJsonSchemaUnit.js","sourceRoot":"","sources":["../../src/schema/IJsonSchemaUnit.ts"],"names":[],"mappings":""}

package/lib/schema/ILlmApplication.d.ts

@@ -0,0 +1,95 @@
+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 declare 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.
+     */
+    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
+     */
+    type IValidationHook<Class extends object> = {
+        [K in keyof Class]?: Class[K] extends (args: infer Argument) => unknown ? (input: unknown) => IValidation<Argument> : never;
+    };
+}

package/lib/schema/ILlmApplication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ILlmApplication.js.map

package/lib/schema/ILlmApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmApplication.js","sourceRoot":"","sources":["../../src/schema/ILlmApplication.ts"],"names":[],"mappings":""}

package/lib/schema/ILlmController.d.ts

@@ -0,0 +1,53 @@
+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/lib/schema/ILlmController.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ILlmController.js.map

package/lib/schema/ILlmController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmController.js","sourceRoot":"","sources":["../../src/schema/ILlmController.ts"],"names":[],"mappings":""}

package/lib/schema/ILlmFunction.d.ts

@@ -0,0 +1,134 @@
+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 declare 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.
+     */
+    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;
+    }
+}

package/lib/schema/ILlmFunction.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ILlmFunction.js.map

package/lib/schema/ILlmFunction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmFunction.js","sourceRoot":"","sources":["../../src/schema/ILlmFunction.ts"],"names":[],"mappings":""}