@typia/core 12.0.0-dev.20260225

package/src/programmers/llm/LlmMetadataFactory.ts

@@ -0,0 +1,91 @@
+import { ILlmSchema, ValidationPipe } from "@typia/interface";
+import ts from "typescript";
+
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { TransformerError } from "../../context/TransformerError";
+import { MetadataFactory } from "../../factories/MetadataFactory";
+import { MetadataObject } from "../../schemas/metadata/MetadataObject";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { MetadataStorage } from "../../schemas/metadata/MetadataStorage";
+
+export namespace LlmMetadataFactory {
+  export const getConfig = (props: {
+    context: ITypiaContext;
+    method: string;
+    node: ts.TypeNode | undefined;
+  }):
+    | Partial<
+        ILlmSchema.IConfig & {
+          equals: boolean;
+        }
+      >
+    | undefined => {
+    if (props.node === undefined) return undefined;
+
+    const type: ts.Type = props.context.checker.getTypeFromTypeNode(props.node);
+    const collection: MetadataStorage = new MetadataStorage();
+    const result: ValidationPipe<MetadataSchema, MetadataFactory.IError> =
+      MetadataFactory.analyze({
+        checker: props.context.checker,
+        transformer: props.context.transformer,
+        options: {
+          absorb: true,
+          escape: false,
+          constant: true,
+          functional: false,
+        },
+        components: collection,
+        type,
+      });
+    if (result.success === false)
+      throw new TransformerError({
+        code: `typia.llm.${props.method}`,
+        message: `Failed to analyze generic argument "Config".`,
+      });
+
+    const meta: MetadataSchema = result.data;
+    if (
+      meta.size() !== 1 ||
+      meta.objects.length !== 1 ||
+      meta.nullable === true ||
+      meta.isRequired() === false
+    )
+      throw new TransformerError({
+        code: `typia.llm.${props.method}`,
+        message: `Invalid generic argument "Config". It must be a literal object type.`,
+      });
+
+    const obj: MetadataObject = meta.objects[0]!;
+    if (obj.type.properties.some((p) => p.key.isSoleLiteral() === false))
+      throw new TransformerError({
+        code: `typia.llm.${props.method}`,
+        message: `Invalid generic argument "Config". It must be a literal object type. Do not allow dynamic properties.`,
+      });
+    else if (
+      obj.type.properties.some(
+        (p) =>
+          p.value.size() !== 1 ||
+          p.value.constants.length !== 1 ||
+          p.value.nullable === true ||
+          p.value.isRequired() === false,
+      )
+    )
+      throw new TransformerError({
+        code: `typia.llm.${props.method}`,
+        message: `Invalid generic argument "Config". It must be a literal object type. Do not allow variable type.`,
+      });
+    const config: Partial<ILlmSchema.IConfig> = {};
+    for (const prop of obj.type.properties) {
+      const key: string = prop.key.getSoleLiteral()!;
+      const value: boolean | bigint | number | string =
+        prop.value.constants[0]!.values[0]!.value;
+      if (typeof value === "bigint")
+        throw new TransformerError({
+          code: `typia.llm.${props.method}`,
+          message: `Invalid generic argument "Config". It must be a literal object type. Do not allow bigint.`,
+        });
+      (config as any)[key] = value;
+    }
+    return config;
+  };
+}

package/src/programmers/llm/LlmParametersProgrammer.ts

@@ -0,0 +1,82 @@
+import {
+  IJsonSchemaCollection,
+  IJsonSchemaTransformError,
+  ILlmSchema,
+  IResult,
+  OpenApi,
+} from "@typia/interface";
+import { LlmSchemaConverter, OpenApiTypeChecker } from "@typia/utils";
+
+import { TransformerError } from "../../context/TransformerError";
+import { MetadataFactory } from "../../factories/MetadataFactory";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { JsonSchemasProgrammer } from "../json/JsonSchemasProgrammer";
+import { LlmSchemaProgrammer } from "./LlmSchemaProgrammer";
+
+export namespace LlmParametersProgrammer {
+  export const write = (props: {
+    metadata: MetadataSchema;
+    config?: Partial<ILlmSchema.IConfig>;
+  }): ILlmSchema.IParameters => {
+    const collection: IJsonSchemaCollection<"3.1"> =
+      JsonSchemasProgrammer.write({
+        version: "3.1",
+        metadatas: [props.metadata],
+      });
+    const schema: OpenApi.IJsonSchema.IObject = (() => {
+      const schema: OpenApi.IJsonSchema = collection.schemas[0]!;
+      if (OpenApiTypeChecker.isObject(schema)) return schema;
+      else if (OpenApiTypeChecker.isReference(schema)) {
+        const last =
+          collection.components.schemas?.[schema.$ref.split("/").pop()!];
+        if (last && OpenApiTypeChecker.isObject(last)) return last;
+      }
+      throw new Error("Unreachable code. Failed to find the object schema.");
+    })();
+
+    const result: IResult<ILlmSchema.IParameters, IJsonSchemaTransformError> =
+      LlmSchemaConverter.parameters({
+        config: LlmSchemaConverter.getConfig(props.config),
+        components: collection.components,
+        schema,
+      });
+    if (result.success === false)
+      throw new TransformerError({
+        code: "typia.llm.parameters",
+        message:
+          "failed to convert JSON schema to LLM schema.\n\n" +
+          result.error.reasons
+            .map((r) => `  - ${r.accessor}: ${r.message}`)
+            .join("\n"),
+      });
+    return result.value;
+  };
+
+  export const validate = (props: {
+    config?: Partial<ILlmSchema.IConfig>;
+    metadata: MetadataSchema;
+    explore: MetadataFactory.IExplore;
+  }): string[] => {
+    const output: string[] = [];
+    if (props.explore.top === true) {
+      if (props.metadata.objects.length === 0)
+        output.push("LLM parameters must be an object type.");
+      else if (props.metadata.objects.length !== 1 || props.metadata.size() > 1)
+        output.push("LLM parameters must be a single object type.");
+      else {
+        if (
+          props.metadata.objects[0]!.type.properties.some(
+            (p) => p.key.isSoleLiteral() === false,
+          )
+        )
+          output.push("LLM parameters must not have dynamic keys.");
+        if (props.metadata.nullable)
+          output.push("LLM parameters must be a non-nullable object type.");
+        if (props.metadata.isRequired() === false)
+          output.push("LLM parameters must be a non-undefined object type.");
+      }
+    }
+    output.push(...LlmSchemaProgrammer.validate(props));
+    return output;
+  };
+}

package/src/programmers/llm/LlmSchemaProgrammer.ts

@@ -0,0 +1,149 @@
+import {
+  IJsonSchemaCollection,
+  IJsonSchemaTransformError,
+  ILlmSchema,
+  IResult,
+} from "@typia/interface";
+import { LlmSchemaConverter } from "@typia/utils";
+
+import { TransformerError } from "../../context/TransformerError";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { AtomicPredicator } from "../helpers/AtomicPredicator";
+import { json_schema_bigint } from "../iterate/json_schema_bigint";
+import { json_schema_boolean } from "../iterate/json_schema_boolean";
+import { json_schema_native } from "../iterate/json_schema_native";
+import { json_schema_number } from "../iterate/json_schema_number";
+import { json_schema_string } from "../iterate/json_schema_string";
+import { JsonSchemasProgrammer } from "../json/JsonSchemasProgrammer";
+
+export namespace LlmSchemaProgrammer {
+  export interface IOutput {
+    schema: ILlmSchema;
+    $defs: Record<string, ILlmSchema>;
+  }
+
+  export const write = (props: {
+    metadata: MetadataSchema;
+    config?: Partial<ILlmSchema.IConfig>;
+  }): IOutput => {
+    const collection: IJsonSchemaCollection<"3.1"> =
+      JsonSchemasProgrammer.write({
+        version: "3.1",
+        metadatas: [props.metadata],
+      });
+
+    const $defs: Record<string, ILlmSchema> = {};
+    const result: IResult<ILlmSchema, IJsonSchemaTransformError> =
+      LlmSchemaConverter.schema({
+        config: LlmSchemaConverter.getConfig(props.config),
+        components: collection.components,
+        schema: collection.schemas[0]!,
+        $defs,
+      });
+    if (result.success === false)
+      throw new TransformerError({
+        code: "typia.llm.schema",
+        message:
+          "failed to convert JSON schema to LLM schema.\n\n" +
+          result.error.reasons
+            .map((r) => `  - ${r.accessor}: ${r.message}`)
+            .join("\n"),
+      });
+    return {
+      $defs,
+      schema: result.value,
+    };
+  };
+
+  export const validate = (props: {
+    config?: Partial<ILlmSchema.IConfig>;
+    metadata: MetadataSchema;
+  }): string[] => {
+    const output: string[] = [];
+
+    // no additionalProperties in OpenAI strict mode
+    const config: ILlmSchema.IConfig = LlmSchemaConverter.getConfig(
+      props.config,
+    );
+    if (
+      config.strict === true &&
+      props.metadata.objects.some((o) =>
+        o.type.properties.some(
+          (p) => p.key.isSoleLiteral() === false && p.value.size() !== 0,
+        ),
+      )
+    )
+      output.push(`Strict mode does not allow dynamic property in object.`);
+
+    // OpenAI strict mode even does not support the optional property
+    if (
+      config.strict === true &&
+      props.metadata.objects.some((o) =>
+        o.type.properties.some((p) => p.value.isRequired() === false),
+      )
+    )
+      output.push(`Strict mode does not support optional property in object.`);
+
+    // just JSON rule
+    if (
+      props.metadata.atomics.some((a) => a.type === "bigint") ||
+      props.metadata.constants.some((c) => c.type === "bigint")
+    )
+      output.push("LLM schema does not support bigint type.");
+    if (props.metadata.tuples.length !== 0)
+      output.push("LLM schema does not support tuple type.");
+    if (props.metadata.arrays.some((a) => a.type.value.isRequired() === false))
+      output.push("LLM schema does not support undefined type in array.");
+    if (props.metadata.maps.length)
+      output.push("LLM schema does not support Map type.");
+    if (props.metadata.sets.length)
+      output.push("LLM schema does not support Set type.");
+    for (const native of props.metadata.natives)
+      if (
+        AtomicPredicator.native(native.name) === false &&
+        native.name !== "Date" &&
+        native.name !== "Blob" &&
+        native.name !== "File"
+      )
+        output.push(`LLM schema does not support ${native.name} type.`);
+    return output;
+  };
+}
+
+const size = (metadata: MetadataSchema): number =>
+  (metadata.escaped ? size(metadata.escaped.returns) : 0) +
+  metadata.aliases.length +
+  metadata.objects.length +
+  metadata.arrays.length +
+  metadata.tuples.length +
+  (metadata.maps.length ? 1 : 0) +
+  (metadata.sets.length ? 1 : 0) +
+  metadata.atomics
+    .map((a) =>
+      a.type === "boolean"
+        ? json_schema_boolean(a).length
+        : a.type === "bigint"
+          ? json_schema_bigint(a).length
+          : a.type === "number"
+            ? json_schema_number(a).length
+            : json_schema_string(a).length,
+    )
+    .reduce((a, b) => a + b, 0) +
+  metadata.constants.filter(
+    (c) => metadata.atomics.some((a) => a.type === c.type) === false,
+  ).length +
+  metadata.templates.length +
+  metadata.natives
+    .filter(
+      (n) =>
+        metadata.atomics.some((a) => a.type === n.name) === false &&
+        metadata.constants.some((c) => c.type === n.name) === false,
+    )
+    .map(
+      (n) =>
+        json_schema_native({
+          components: {},
+          native: n,
+        }).length,
+    )
+    .reduce((a, b) => a + b, 0);

package/src/programmers/llm/index.ts

@@ -0,0 +1,4 @@
+export * from "./LlmApplicationProgrammer";
+export * from "./LlmMetadataFactory";
+export * from "./LlmParametersProgrammer";
+export * from "./LlmSchemaProgrammer";

package/src/programmers/misc/MiscAssertCloneProgrammer.ts

@@ -0,0 +1,93 @@
+import ts from "typescript";
+
+import { IProgrammerProps } from "../../context/IProgrammerProps";
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { StatementFactory } from "../../factories/StatementFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { AssertProgrammer } from "../AssertProgrammer";
+import { FunctionProgrammer } from "../helpers/FunctionProgrammer";
+import { FeatureProgrammer } from "../internal/FeatureProgrammer";
+import { MiscCloneProgrammer } from "./MiscCloneProgrammer";
+
+export namespace MiscAssertCloneProgrammer {
+  export const decompose = (props: {
+    context: ITypiaContext;
+    functor: FunctionProgrammer;
+    type: ts.Type;
+    name: string | undefined;
+    init?: ts.Expression | undefined;
+  }): FeatureProgrammer.IDecomposed => {
+    const assert: FeatureProgrammer.IDecomposed = AssertProgrammer.decompose({
+      ...props,
+      config: {
+        equals: false,
+        guard: false,
+      },
+    });
+    const clone: FeatureProgrammer.IDecomposed = MiscCloneProgrammer.decompose({
+      ...props,
+      validated: true,
+    });
+    return {
+      functions: {
+        ...assert.functions,
+        ...clone.functions,
+      },
+      statements: [
+        ...assert.statements,
+        ...clone.statements,
+        StatementFactory.constant({
+          name: "__assert",
+          value: assert.arrow,
+        }),
+        StatementFactory.constant({
+          name: "__clone",
+          value: clone.arrow,
+        }),
+      ],
+      arrow: ts.factory.createArrowFunction(
+        undefined,
+        undefined,
+        [
+          IdentifierFactory.parameter("input", TypeFactory.keyword("any")),
+          AssertProgrammer.Guardian.parameter({
+            context: props.context,
+            init: props.init,
+          }),
+        ],
+        clone.arrow.type,
+        undefined,
+        ts.factory.createCallExpression(
+          ts.factory.createIdentifier("__clone"),
+          undefined,
+          [
+            ts.factory.createCallExpression(
+              ts.factory.createIdentifier("__assert"),
+              undefined,
+              [
+                ts.factory.createIdentifier("input"),
+                AssertProgrammer.Guardian.identifier(),
+              ],
+            ),
+          ],
+        ),
+      ),
+    };
+  };
+
+  export const write = (props: IProgrammerProps): ts.CallExpression => {
+    const functor: FunctionProgrammer = new FunctionProgrammer(
+      props.modulo.getText(),
+    );
+    const result: FeatureProgrammer.IDecomposed = decompose({
+      ...props,
+      functor,
+    });
+    return FeatureProgrammer.writeDecomposed({
+      modulo: props.modulo,
+      functor,
+      result,
+    });
+  };
+}

package/src/programmers/misc/MiscAssertPruneProgrammer.ts

@@ -0,0 +1,114 @@
+import ts from "typescript";
+
+import { IProgrammerProps } from "../../context/IProgrammerProps";
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { StatementFactory } from "../../factories/StatementFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { AssertProgrammer } from "../AssertProgrammer";
+import { FunctionProgrammer } from "../helpers/FunctionProgrammer";
+import { FeatureProgrammer } from "../internal/FeatureProgrammer";
+import { MiscPruneProgrammer } from "./MiscPruneProgrammer";
+
+export namespace MiscAssertPruneProgrammer {
+  export const decompose = (props: {
+    context: ITypiaContext;
+    functor: FunctionProgrammer;
+    type: ts.Type;
+    name: string | undefined;
+    init?: ts.Expression | undefined;
+  }): FeatureProgrammer.IDecomposed => {
+    const assert: FeatureProgrammer.IDecomposed = AssertProgrammer.decompose({
+      ...props,
+      config: {
+        equals: false,
+        guard: false,
+      },
+    });
+    const prune: FeatureProgrammer.IDecomposed = MiscPruneProgrammer.decompose({
+      ...props,
+      validated: true,
+    });
+    return {
+      functions: {
+        ...assert.functions,
+        ...prune.functions,
+      },
+      statements: [
+        ...assert.statements,
+        ...prune.statements,
+        StatementFactory.constant({
+          name: "__assert",
+          value: assert.arrow,
+        }),
+        StatementFactory.constant({
+          name: "__prune",
+          value: prune.arrow,
+        }),
+      ],
+      arrow: ts.factory.createArrowFunction(
+        undefined,
+        undefined,
+        [
+          IdentifierFactory.parameter("input", TypeFactory.keyword("any")),
+          AssertProgrammer.Guardian.parameter({
+            context: props.context,
+            init: props.init,
+          }),
+        ],
+        ts.factory.createTypeReferenceNode(
+          props.name ??
+            TypeFactory.getFullName({
+              checker: props.context.checker,
+              type: props.type,
+            }),
+        ),
+        undefined,
+        ts.factory.createBlock(
+          [
+            ts.factory.createExpressionStatement(
+              ts.factory.createBinaryExpression(
+                ts.factory.createIdentifier("input"),
+                ts.SyntaxKind.EqualsToken,
+                ts.factory.createCallExpression(
+                  ts.factory.createIdentifier("__assert"),
+                  undefined,
+                  [
+                    ts.factory.createIdentifier("input"),
+                    AssertProgrammer.Guardian.identifier(),
+                  ],
+                ),
+              ),
+            ),
+            ts.factory.createExpressionStatement(
+              ts.factory.createCallExpression(
+                ts.factory.createIdentifier("__prune"),
+                undefined,
+                [ts.factory.createIdentifier("input")],
+              ),
+            ),
+            ts.factory.createReturnStatement(
+              ts.factory.createIdentifier("input"),
+            ),
+          ],
+          true,
+        ),
+      ),
+    };
+  };
+
+  export const write = (props: IProgrammerProps): ts.CallExpression => {
+    const functor: FunctionProgrammer = new FunctionProgrammer(
+      props.modulo.getText(),
+    );
+    const result: FeatureProgrammer.IDecomposed = decompose({
+      ...props,
+      functor,
+    });
+    return FeatureProgrammer.writeDecomposed({
+      modulo: props.modulo,
+      functor,
+      result,
+    });
+  };
+}