Typia Guide Documents

`parameters()` function

typia

export namespace llm {
  // LLM FUNCTION CALLING APPLICATION SCHEMA
  export function application<
    App extends Record<string, any>,
    Model extends ILlmSchema.Model,
    Config extends Partial<ILlmSchema.ModelConfig[Model]> = {},
  >(
    options?: Partial<Pick<ILlmApplication.IOptions<Model>, "separate">>,
  ): ILlmApplication<Model>;
 
  // +VALIDATE FUNCTION EMBEDDED
  export function applicationOfValidate<
    App extends Record<string, any>,
    Model extends ILlmSchema.Model,
    Config extends Partial<ILlmSchema.ModelConfig[Model]> = {},
  >(
    options?: Partial<Pick<ILlmApplicationOfValidate.IOptions<Model>, "separate">>,
  ): ILlmApplicationOfValidate<Model>;
 
  // STRUCTURED OUTPUT
  export function parameters<
    Parameters extends Record<string, any>,
    Model extends ILlmSchema.Model,
    Config extends Partial<ILlmSchema.ModelConfig[Model]> = {},
  >(): ILlmSchema.ModelParameters[Model];
 
  // TYPE SCHEMA
  export function schema<
    T,
    Model extends ILlmSchema.Model,
    Config extends Partial<ILlmSchema.ModelConfig[Model]> = {},
  >(
    ...$defs: Extract<
      ILlmSchema.ModelSchema[Model],
      { $ref: string }
    > extends never
      ? []
      : [Record<string, ILlmSchema.ModelSchema[Model]>]
  ): ILlmSchema.ModelSchema[Model];
}

@samchon/openapi

import { IGeminiSchema } from "./IGeminiSchema";
import { ILlmFunction } from "./ILlmFunction";
import { ILlmSchema } from "./ILlmSchema";
 
/**
 * Application of LLM function calling.
 *
 * `ILlmApplication` is a data structure representing a collection of
 * {@link ILlmFunction LLM function calling schemas}, composed from a native
 * TypeScript class (or interface) type by the `typia.llm.application<App, Model>()`
 * function.
 *
 * Also, there can be some parameters (or their nested properties) which must be
 * composed by Human, not by LLM. File uploading feature or some sensitive information
 * like secrety key (password) are the examples. In that case, you can separate the
 * function parameters to both LLM and human sides by configuring the
 * {@link ILlmApplication.IOptions.separate} property. The separated parameters are
 * assigned to the {@link ILlmFunction.separated} property.
 *
 * For reference, when both LLM and Human filled parameter values to call, you can
 * merge them by calling the {@link HttpLlm.mergeParameters} function. In other words,
 * if you've configured the {@link ILlmApplication.IOptions.separate} property, you
 * have to merge the separated parameters before the funtion call execution.
 *
 * @reference https://platform.openai.com/docs/guides/function-calling
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface ILlmApplication<Model extends ILlmSchema.Model> {
  /**
   * Model of the LLM.
   */
  model: Model;
 
  /**
   * List of function metadata.
   *
   * List of function metadata that can be used for the LLM function call.
   */
  functions: ILlmFunction<Model>[];
 
  /**
   * Configuration for the application.
   */
  options: ILlmApplication.IOptions<Model>;
}
export namespace ILlmApplication {
  /**
   * Options for application composition.
   */
  export type IOptions<Model extends ILlmSchema.Model> = {
    /**
     * Separator function for the parameters.
     *
     * When composing parameter arguments through LLM function call,
     * there can be a case that some parameters must be composed by human,
     * or LLM cannot understand the parameter.
     *
     * For example, if the parameter type has configured
     * {@link IGeminiSchema.IString.contentMediaType} which indicates file
     * uploading, it must be composed by human, not by LLM
     * (Large Language Model).
     *
     * In that case, if you configure this property with a function that
     * predicating whether the schema value must be composed by human or
     * not, the parameters would be separated into two parts.
     *
     * - {@link ILlmFunction.separated.llm}
     * - {@link ILlmFunction.separated.human}
     *
     * When writing the function, note that returning value `true` means
     * to be a human composing the value, and `false` means to LLM
     * composing the value. Also, when predicating the schema, it would
     * better to utilize the {@link GeminiTypeChecker} like features.
     *
     * @param schema Schema to be separated.
     * @returns Whether the schema value must be composed by human or not.
     * @default null
     */
    separate: null | ((schema: ILlmSchema.ModelSchema[Model]) => boolean);
  } & ILlmSchema.ModelConfig[Model];
}

@samchon/openapi

import { ILlmSchema } from "./ILlmSchema";
 
/**
 * LLM function metadata.
 *
 * `ILlmFunction` is an interface representing a function metadata,
 * which has been used for the LLM (Language Large Model) function
 * calling. Also, it's a function structure containing the function
 * {@link name}, {@link parameters} and {@link output return type}.
 *
 * If you provide this `ILlmFunction` data to the LLM provider like "OpenAI",
 * the "OpenAI" will compose a function arguments by analyzing conversations
 * with the user. With the LLM composed arguments, you can execute the function
 * and get the result.
 *
 * By the way, do not ensure that LLM will always provide the correct
 * arguments. The LLM of present age is not perfect, so that you would
 * better to validate the arguments before executing the function.
 * I recommend you to validate the arguments before execution by using
 * [`typia`](https://github.com/samchon/typia) library.
 *
 * @reference https://platform.openai.com/docs/guides/function-calling
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface ILlmFunction<Model extends ILlmSchema.Model> {
  /**
   * Representative name of the function.
   */
  name: string;
 
  /**
   * List of parameter types.
   */
  parameters: ILlmSchema.ModelParameters[Model];
 
  /**
   * Collection of separated parameters.
   */
  separated?: ILlmFunction.ISeparated<Model>;
 
  /**
   * Expected return type.
   *
   * If the function returns nothing (`void`), the `output` value would
   * be `undefined`.
   */
  output?: ILlmSchema.ModelSchema[Model];
 
  /**
   * Whether the function schema types are strict or not.
   *
   * Newly added specification to "OpenAI" at 2024-08-07.
   *
   * @reference https://openai.com/index/introducing-structured-outputs-in-the-api/
   */
  strict: true;
 
  /**
   * Description of the function.
   *
   * For reference, the `description` is very important property to teach
   * the purpose of the function to the LLM (Language Large Model), and
   * LLM actually determines which function to call by the description.
   *
   * Also, when the LLM conversates with the user, the `description` is
   * used to explain the function to the user. Therefore, the `description`
   * property has the highest priroity, and you have to consider it.
   */
  description?: string | undefined;
 
  /**
   * Whether the function is deprecated or not.
   *
   * If the `deprecated` is `true`, the function is not recommended to use.
   *
   * LLM (Large Language Model) may not use the deprecated function.
   */
  deprecated?: boolean | undefined;
 
  /**
   * Category tags for the function.
   *
   * You can fill this property by the `@tag ${name}` comment tag.
   */
  tags?: string[];
}
export namespace ILlmFunction {
  /**
   * Collection of separated parameters.
   */
  export interface ISeparated<Model extends ILlmSchema.Model> {
    /**
     * Parameters that would be composed by the LLM.
     */
    llm: ILlmSchema.ModelParameters[Model] | null;
 
    /**
     * Parameters that would be composed by the human.
     */
    human: ILlmSchema.ModelParameters[Model] | null;
  }
}

@samchon/openapi

import { IChatGptSchema } from "./IChatGptSchema";
import { IClaudeSchema } from "./IClaudeSchema";
import { IGeminiSchema } from "./IGeminiSchema";
import { ILlamaSchema } from "./ILlamaSchema";
import { ILlmSchemaV3 } from "./ILlmSchemaV3";
import { ILlmSchemaV3_1 } from "./ILlmSchemaV3_1";
 
/**
 * The schemas for the LLM function calling.
 *
 * `ILlmSchema` is an union type collecting every the schemas for the
 * LLM function calling.
 *
 * Select a proper schema type according to the LLM provider you're using.
 *
 * @template Model Name of the target LLM model
 * @reference https://platform.openai.com/docs/guides/function-calling
 * @reference https://platform.openai.com/docs/guides/structured-outputs
 * @author Jeongho Nam - https://github.com/samchon
 */
export type ILlmSchema<Model extends ILlmSchema.Model = ILlmSchema.Model> =
  ILlmSchema.ModelSchema[Model];
 
export namespace ILlmSchema {
  export type Model = "chatgpt" | "claude" | "gemini" | "llama" | "3.0" | "3.1";
  export interface ModelConfig {
    chatgpt: IChatGptSchema.IConfig;
    claude: IClaudeSchema.IConfig;
    gemini: IGeminiSchema.IConfig;
    llama: ILlamaSchema.IConfig;
    "3.0": ILlmSchemaV3.IConfig;
    "3.1": ILlmSchemaV3_1.IConfig;
  }
  export interface ModelParameters {
    chatgpt: IChatGptSchema.IParameters;
    claude: IClaudeSchema.IParameters;
    gemini: IGeminiSchema.IParameters;
    llama: ILlamaSchema.IParameters;
    "3.0": ILlmSchemaV3.IParameters;
    "3.1": ILlmSchemaV3_1.IParameters;
  }
  export interface ModelSchema {
    chatgpt: IChatGptSchema;
    claude: IClaudeSchema;
    gemini: IGeminiSchema;
    llama: ILlamaSchema;
    "3.0": ILlmSchemaV3;
    "3.1": ILlmSchemaV3_1;
  }
 
  /**
   * Type of function parameters.
   *
   * `ILlmSchema.IParameters` is a type defining a function's pamameters
   * as a keyworded object type.
   *
   * It also can be utilized for the structured output metadata.
   *
   * @reference https://platform.openai.com/docs/guides/structured-outputs
   */
  export type IParameters<Model extends ILlmSchema.Model = ILlmSchema.Model> =
    ILlmSchema.ModelParameters[Model];
 
  /**
   * Configuration for the LLM schema composition.
   */
  export type IConfig<Model extends ILlmSchema.Model = ILlmSchema.Model> =
    ILlmSchema.ModelConfig[Model];
}

typia

import { ILlmApplication, ILlmFunction, ILlmSchema } from "@samchon/openapi";
 
import { IValidation } from "../../IValidation";
 
/**
 * Application of LLM function calling with validators.
 *
 * `ILlmApplication` is a data structure representing a collection of
 * {@link ILlmFunctionOfValidate LLM function calling schemas}, composed from a native
 * TypeScript class (or interface) type by the `typia.llm.applicationOfValidate<App, Model>()`
 * function.
 *
 * If you put the returned {@link ILlmApplicationOfValidate.functions} objects to the
 * LLM provider like [OpenAI (ChatGPT)](https://openai.com/), the LLM will automatically
 * select the proper function and fill its arguments from the conversation
 * (maybe chatting text) with user (human). This is the concept of the LLM function calling.
 *
 * Additionally, the LLM function calling sometimes take a mistake that composing wrong typed
 * {@link ILlmFunctionOfValidate.parameters}. In that case, deliver return value of the
 * {@link ILlmFunctionOfValidate.validate} function, then LLM provider will correct the
 * parameters at the next conversation. The {@link ILlmFunctionOfValidate.validate} function
 * is a validator function reporting the detailed information about the wrong typed parameters.
 *
 * By the way, there can be some parameters (or their nested properties) which must be
 * composed by Human, not by LLM. File uploading feature or some sensitive information
 * like secrety key (password) are the examples. In that case, you can separate the
 * function parameters to both LLM and human sides by configuring the
 * {@link ILlmApplication.IOptions.separate} property. The separated parameters are
 * assigned to the {@link ILlmFunction.separated} property.
 *
 * For reference, when both LLM and Human filled parameter values to call, you can
 * merge them by calling the {@link HttpLlm.mergeParameters} function. In other words,
 * if you've configured the {@link ILlmApplication.IOptions.separate} property, you
 * have to merge the separated parameters before the funtion call execution.
 *
 * @reference https://platform.openai.com/docs/guides/function-calling
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface ILlmApplicationOfValidate<Model extends ILlmSchema.Model>
  extends ILlmApplication<Model> {
  /**
   * List of function metadata.
   *
   * List of function metadata that can be used for the LLM function call.
   *
   * Also, every functions have their own parameters validator
   * {@link ILlmFunctionOfValidate.validate}. If the LLM function calling composes wrong
   * typed parameters, then deliver return value of it, then LLM will correct parameters
   * at the next conversation.
   */
  functions: ILlmFunctionOfValidate<Model>[];
}
export namespace ILlmApplicationOfValidate {
  export import IOptions = ILlmApplication.IOptions;
}
 
/**
 * LLM function metadata with validator.
 *
 * `ILlmFunctionOfValidate` is an interface representing a function metadata,
 * which has been used for the LLM (Language Large Model) function
 * calling. Also, it's a function structure containing the function
 * {@link name}, {@link parameters} and {@link output return type}.
 *
 * If you provide this `ILlmFunctionOfValidate` data to the LLM provider like "OpenAI",
 * the "OpenAI" will compose a function arguments by analyzing conversations
 * with the user. With the LLM composed arguments, you can execute the function
 * and get the result.
 *
 * If the LLM function calling take s a mistake that composing wrong typed
 * {@link parameters}, you can correct the parameters by delivering the return
 * value of the {@link validate} function. The {@link validate} function is a
 * validator function reporting the detailed information about the wrong typed
 * {@link parameters}.
 *
 * By the way, do not ensure that LLM will always provide the correct arguments.
 * The LLM of present age is not perfect, and sometimes takes a mistake that composing
 * wrong typed {@link parameters}. In that case, you can correc the parameters by
 * delivering the return value of the {@link validate} function. The {@link validate}
 * function reports the detailed information about the wrong typed {@link parameters},
 *
 * @reference https://platform.openai.com/docs/guides/function-calling
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface ILlmFunctionOfValidate<Model extends ILlmSchema.Model>
  extends ILlmFunction<Model> {
  validate(props: object): IValidation<unknown>;
}
export namespace ILlmFunctionOfValidate {
  export import ISeparated = ILlmFunction.ISeparated;
}

Structured output schema of LLM (Large Language Model).

typia.llm.parameters<Parameters, Model>() is a function generating structured output of LLM (Large Language Model) from a TypeScript object type. It is used to LLM function calling or structured output feature provided by OpenAI like LLM providers.

Return value type ILlmSchema.IParameters is a similar with the JSON schema definition’s object type. However, its detailed specification becomes different by LLM provider model you’ve chosen. Here is the list of LLM schema definitions of each model. Determine one of them carefully reading the LLM schema definitions.

Supported schemas
- IChatGptSchema: OpenAI ChatGPT
- IClaudeSchema: Anthropic Claude
- IGeminiSchema: Google Gemini
- ILlamaSchema: Meta Llama
Midldle layer schemas
- ILlmSchemaV3: middle layer based on OpenAPI v3.0 specification
- ILlmSchemaV3_1: middle layer based on OpenAPI v3.1 specification

LLM Function Calling and Structured Output

LLM selects proper function and fill arguments.

In nowadays, most LLM (Large Language Model) like OpenAI are supporting “function calling” feature. The “LLM function calling” means that LLM automatically selects a proper function and fills parameter values from conversation with the user (may by chatting text).

Structured output is another feature of LLM. The “structured output” means that LLM automatically transforms the output conversation into a structured data format like JSON.

Specialization

Customziation

Restrictions

typia.llm.parameters<Parameters, Model>() follows the same restrictions typia.llm.schema<T, Model>() function. Also, it has only one additional restriction; the keyworded argument.

In the LLM function calling and structured output, the parameters must be a keyworded object type with static keys without any dynamic keys. Also, the object type must not be nullable or optional.

If you don’t follow the LLM’s keyworded arguments rule, typia.llm.parameters<Parameters, Model>() will throw compilation error like below.

src/examples/llm.parameters.violation.ts

import typia from "typia";
 
typia.llm.parameters<string>();
typia.llm.parameters<Record<string, boolean>, "chatgpt">();
typia.llm.parameters<Array<number>>();

application() function schema() function

parameters() function

Specialization

Customziation

Restrictions

`parameters()` function