typia 6.9.0 → 6.10.0-dev.20240906

package/src/llm.ts

@@ -0,0 +1,30 @@
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+
+export function application(): never;
+export function application<T extends object>(): ILlmApplication;
+
+/**
+ * @internal
+ */
+export function application(): never {
+  halt("application");
+}
+
+export function schema(): never;
+export function schema<T>(): ILlmSchema;
+
+/**
+ * @internal
+ */
+export function schema(): never {
+  halt("schema");
+}
+
+/**
+ * @internal
+ */
+function halt(name: string): never {
+  throw new Error(
+    `Error on typia.llm.${name}(): no transform has been configured. Read and follow https://typia.io/docs/setup please.`,
+  );
+}

package/src/module.ts

@@ -8,6 +8,7 @@ import { TypeGuardError } from "./TypeGuardError";
 
 export * as functional from "./functional";
 export * as http from "./http";
+export * as llm from "./llm";
 export * as json from "./json";
 export * as misc from "./misc";
 export * as notations from "./notations";

package/src/programmers/internal/application_escaped.ts

@@ -10,11 +10,11 @@ export const application_escaped =
   <Version extends "3.0" | "3.1">(
     generator: (meta: Metadata) => Schema<Version>,
   ) =>
-  (resolved: MetadataEscaped): Schema<Version>[] => {
-    const output: Schema<Version> | null = generator(resolved.returns);
+  (escaped: MetadataEscaped): Schema<Version>[] => {
+    const output: Schema<Version> | null = generator(escaped.returns);
     if (output === null) return [];
 
-    if (is_date(new Set())(resolved.original)) {
+    if (is_date(new Set())(escaped.original)) {
       const string: StringSchema<Version> | undefined = is_string(output)
         ? output
         : is_one_of(output)
@@ -27,9 +27,7 @@ export const application_escaped =
       )
         string.format = "date-time";
     }
-    return is_one_of(output)
-      ? (output.oneOf as OneOfSchema<Version>[])
-      : [output];
+    return is_one_of(output) ? (output.oneOf as Schema<Version>[]) : [output];
   };
 
 /**

package/src/programmers/internal/llm_schema_array.ts

@@ -0,0 +1,22 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { MetadataArray } from "../../schemas/metadata/MetadataArray";
+
+import { application_plugin } from "./application_plugin";
+import { llm_schema_station } from "./llm_schema_station";
+
+/**
+ * @internal
+ */
+export const llm_schema_array = (array: MetadataArray): ILlmSchema.IArray[] =>
+  application_plugin(
+    {
+      type: "array",
+      items: llm_schema_station({
+        metadata: array.type.value,
+        blockNever: false,
+        attribute: {},
+      }),
+    },
+    array.tags,
+  );

package/src/programmers/internal/llm_schema_escaped.ts

@@ -0,0 +1,61 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataEscaped } from "../../schemas/metadata/MetadataEscaped";
+
+import { llm_schema_station } from "./llm_schema_station";
+
+/**
+ * @internal
+ */
+export const llm_schema_escaped = (escaped: MetadataEscaped): ILlmSchema[] => {
+  const output: ILlmSchema | null = llm_schema_station({
+    metadata: escaped.returns,
+    blockNever: false,
+    attribute: {},
+  });
+  if (output === null) return [];
+  else if (is_date(new Set())(escaped.original)) {
+    const string: ILlmSchema.IString | undefined = is_string(output)
+      ? output
+      : is_one_of(output)
+        ? (output.oneOf.find(is_string) as ILlmSchema.IString)
+        : undefined;
+    if (
+      string !== undefined &&
+      string.format !== "date" &&
+      string.format !== "date-time"
+    )
+      string.format = "date-time";
+  }
+  return is_one_of(output) ? (output.oneOf as ILlmSchema[]) : [output];
+};
+
+/**
+ * @internal
+ */
+const is_string = (elem: ILlmSchema): elem is ILlmSchema.IString =>
+  (elem as ILlmSchema.IString).type === "string";
+
+/**
+ * @internal
+ */
+const is_one_of = (elem: ILlmSchema): elem is ILlmSchema.IOneOf =>
+  Array.isArray((elem as ILlmSchema.IOneOf).oneOf);
+
+/**
+ * @internal
+ */
+const is_date =
+  (visited: Set<Metadata>) =>
+  (meta: Metadata): boolean => {
+    if (visited.has(meta)) return false;
+    visited.add(meta);
+
+    return (
+      meta.natives.some((name) => name === "Date") ||
+      meta.arrays.some((array) => is_date(visited)(array.type.value)) ||
+      meta.tuples.some((tuple) => tuple.type.elements.some(is_date(visited))) ||
+      meta.aliases.some((alias) => is_date(visited)(alias.value))
+    );
+  };

package/src/programmers/internal/llm_schema_native.ts

@@ -0,0 +1,17 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+/**
+ * @internal
+ */
+export const llm_schema_native = (
+  name: string,
+): ILlmSchema.IString | ILlmSchema.IObject =>
+  name === "Blob" || name === "File"
+    ? {
+        type: "string",
+        format: "binary",
+      }
+    : {
+        type: "object",
+        properties: {},
+      };

package/src/programmers/internal/llm_schema_object.ts

@@ -0,0 +1,129 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { CommentFactory } from "../../factories/CommentFactory";
+
+import { IJsDocTagInfo } from "../../schemas/metadata/IJsDocTagInfo";
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataObject } from "../../schemas/metadata/MetadataObject";
+
+import { PatternUtil } from "../../utils/PatternUtil";
+
+import { application_description } from "./application_description";
+import { llm_schema_station } from "./llm_schema_station";
+import { metadata_to_pattern } from "./metadata_to_pattern";
+
+/**
+ * @internal
+ */
+export const llm_schema_object = (props: {
+  object: MetadataObject;
+  nullable: boolean;
+}): ILlmSchema.IObject => {
+  // ITERATE PROPERTIES
+  const properties: Record<string, any> = {};
+  const extraMeta: ISuperfluous = {
+    patternProperties: {},
+    additionalProperties: undefined,
+  };
+  const required: string[] = [];
+
+  for (const property of props.object.properties) {
+    if (
+      // FUNCTIONAL TYPE
+      property.value.functional === true &&
+      property.value.nullable === false &&
+      property.value.isRequired() === true &&
+      property.value.size() === 0
+    )
+      continue;
+    else if (property.jsDocTags.find((tag) => tag.name === "hidden")) continue; // THE HIDDEN TAG
+
+    const key: string | null = property.key.getSoleLiteral();
+    const schema: ILlmSchema | null = llm_schema_station({
+      blockNever: true,
+      attribute: {
+        deprecated:
+          property.jsDocTags.some((tag) => tag.name === "deprecated") ||
+          undefined,
+        title: (() => {
+          const info: IJsDocTagInfo | undefined = property.jsDocTags.find(
+            (tag) => tag.name === "title",
+          );
+          if (info?.text?.length) return CommentFactory.merge(info.text);
+          else if (!property.description?.length) return undefined;
+
+          const index: number = property.description.indexOf("\n");
+          const top: string = (
+            index === -1
+              ? property.description
+              : property.description.substring(0, index)
+          ).trim();
+          return top.endsWith(".")
+            ? top.substring(0, top.length - 1)
+            : undefined;
+        })(),
+        description: application_description(property),
+      },
+      metadata: property.value,
+    });
+
+    if (schema === null) continue;
+    if (key !== null) {
+      properties[key] = schema;
+      if (property.value.isRequired() === true) required.push(key);
+    } else {
+      const pattern: string = metadata_to_pattern(true)(property.key);
+      if (pattern === PatternUtil.STRING)
+        extraMeta.additionalProperties = [property.value, schema];
+      else extraMeta.patternProperties[pattern] = [property.value, schema];
+    }
+  }
+
+  return {
+    type: "object",
+    properties,
+    nullable: props.nullable,
+    required: required.length ? required : undefined,
+    title: (() => {
+      const info: IJsDocTagInfo | undefined = props.object.jsDocTags.find(
+        (tag) => tag.name === "title",
+      );
+      return info?.text?.length ? CommentFactory.merge(info.text) : undefined;
+    })(),
+    description: application_description(props.object),
+    additionalProperties: join(extraMeta),
+  };
+};
+
+/**
+ * @internal
+ */
+const join = (extra: ISuperfluous): ILlmSchema | undefined => {
+  // LIST UP METADATA
+  const elements: [Metadata, ILlmSchema][] = Object.values(
+    extra.patternProperties || {},
+  );
+  if (extra.additionalProperties) elements.push(extra.additionalProperties);
+
+  // SHORT RETURN
+  if (elements.length === 0) return undefined;
+  else if (elements.length === 1) return elements[0]![1]!;
+
+  // MERGE METADATA AND GENERATE VULNERABLE SCHEMA
+  const meta: Metadata = elements
+    .map((tuple) => tuple[0])
+    .reduce((x, y) => Metadata.merge(x, y));
+  return llm_schema_station({
+    blockNever: true,
+    attribute: {},
+    metadata: meta,
+  });
+};
+
+/**
+ * @internal
+ */
+interface ISuperfluous {
+  additionalProperties?: undefined | [Metadata, ILlmSchema];
+  patternProperties: Record<string, [Metadata, ILlmSchema]>;
+}

package/src/programmers/internal/llm_schema_station.ts

@@ -0,0 +1,185 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
+
+import { AtomicPredicator } from "../helpers/AtomicPredicator";
+import { application_bigint } from "./application_bigint";
+import { application_boolean } from "./application_boolean";
+import { application_number } from "./application_number";
+import { application_string } from "./application_string";
+import { application_templates } from "./application_templates";
+import { application_v30_constant } from "./application_v30_constant";
+import { llm_schema_array } from "./llm_schema_array";
+import { llm_schema_escaped } from "./llm_schema_escaped";
+import { llm_schema_native } from "./llm_schema_native";
+import { llm_schema_object } from "./llm_schema_object";
+import { llm_schema_tuple } from "./llm_schema_tuple";
+
+/**
+ * @internal
+ */
+export const llm_schema_station = (props: {
+  metadata: Metadata;
+  blockNever: boolean;
+  attribute: ILlmSchema.__IAttribute;
+}): ILlmSchema => {
+  // VULNERABLE CASE
+  if (props.metadata.any === true)
+    return {
+      ...props.attribute,
+      type: undefined,
+    };
+  else if (props.metadata.nullable === true && props.metadata.empty() === true)
+    return {
+      ...props.attribute,
+      type: "null",
+    };
+
+  //----
+  // GATHER UNION SCHEMAS
+  //----
+  const union: ILlmSchema[] = [];
+  const insert = props.metadata.nullable
+    ? (schema: ILlmSchema) =>
+        union.push({
+          ...schema,
+          nullable: (schema as ILlmSchema.__ISignificant<any>).type
+            ? true
+            : undefined,
+        } as ILlmSchema)
+    : (schema: ILlmSchema) => union.push(schema);
+
+  // toJSON() METHOD
+  if (props.metadata.escaped !== null)
+    llm_schema_escaped(props.metadata.escaped).forEach(insert);
+
+  // ATOMIC TYPES
+  if (
+    props.metadata.templates.length &&
+    AtomicPredicator.template(props.metadata)
+  )
+    application_templates<"3.0">(props.metadata).map(insert);
+  for (const constant of props.metadata.constants)
+    if (AtomicPredicator.constant(props.metadata)(constant.type) === false)
+      continue;
+    else insert(application_v30_constant(constant));
+  for (const a of props.metadata.atomics)
+    if (a.type === "boolean") application_boolean<"3.0">(a).forEach(insert);
+    else if (a.type === "bigint") application_bigint<"3.0">(a).forEach(insert);
+    else if (a.type === "number") application_number<"3.0">(a).forEach(insert);
+    else if (a.type === "string") application_string<"3.0">(a).forEach(insert);
+
+  // ARRAY
+  for (const array of props.metadata.arrays)
+    if (array.type.recursive)
+      throw new Error(
+        "Error on LlmSchemaProgrammer.write(): LLM schema does not allow recursive array type.",
+      );
+    else llm_schema_array(array).forEach(insert);
+
+  // TUPLE
+  for (const tuple of props.metadata.tuples)
+    if (tuple.type.recursive)
+      throw new Error(
+        "Error on LlmSchemaProgrammer.write(): LLM schema does not allow recursive tuple type.",
+      );
+    else
+      insert(
+        llm_schema_tuple({
+          tuple,
+          attribute: props.attribute,
+        }),
+      );
+
+  // NATIVES
+  for (const native of props.metadata.natives)
+    if (AtomicPredicator.native(native)) {
+      const type: string = native.toLowerCase();
+      if (props.metadata.atomics.some((a) => a.type === type)) continue;
+      else if (type === "boolean")
+        insert(
+          application_boolean<"3.0">(
+            MetadataAtomic.create({
+              type: "boolean",
+              tags: [],
+            }),
+          )[0]!,
+        );
+      else if (type === "bigint")
+        insert(
+          application_bigint(
+            MetadataAtomic.create({
+              type: "bigint",
+              tags: [],
+            }),
+          )[0]!,
+        );
+      else if (type === "number")
+        insert(
+          application_number(
+            MetadataAtomic.create({
+              type: "number",
+              tags: [],
+            }),
+          )[0]!,
+        );
+      else if (type === "string")
+        insert(
+          application_string(
+            MetadataAtomic.create({
+              type: "string",
+              tags: [],
+            }),
+          )[0]!,
+        );
+    } else insert(llm_schema_native(native));
+  if (props.metadata.sets.length) insert(llm_schema_native("Set"));
+  if (props.metadata.maps.length) insert(llm_schema_native("Map"));
+
+  // OBJECT
+  for (const object of props.metadata.objects)
+    if (object.recursive)
+      throw new Error(
+        "Error on LlmSchemaProgrammer.write(): LLM schema does not allow recursive object type.",
+      );
+    else
+      insert(
+        llm_schema_object({
+          object,
+          nullable: props.metadata.nullable,
+        }),
+      );
+
+  // ALIASES
+  for (const alias of props.metadata.aliases)
+    if (alias.recursive)
+      throw new Error(
+        "Error on LlmSchemaProgrammer.write(): LLM schema does not allow recursive alias type.",
+      );
+    else
+      insert(
+        llm_schema_station({
+          ...props,
+          metadata: alias.value,
+        }),
+      );
+
+  //----
+  // RETURNS
+  //----
+  if (union.length === 0 && props.blockNever === true) return null!;
+  const schema: ILlmSchema =
+    union.length === 0
+      ? { type: undefined }
+      : union.length === 1
+        ? union[0]!
+        : { oneOf: union };
+  return {
+    ...schema,
+    ...props.attribute,
+    title: props.attribute.title ?? schema.title,
+    description: props.attribute.description ?? schema.description,
+    deprecated: props.attribute.deprecated ?? schema.deprecated,
+  };
+};

package/src/programmers/internal/llm_schema_tuple.ts

@@ -0,0 +1,31 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataTuple } from "../../schemas/metadata/MetadataTuple";
+
+import { llm_schema_station } from "./llm_schema_station";
+
+/**
+ * @internal
+ */
+export const llm_schema_tuple = (props: {
+  tuple: MetadataTuple;
+  attribute: ILlmSchema.__IAttribute;
+}): ILlmSchema.IArray => ({
+  ...props.attribute,
+  type: "array",
+  items: llm_schema_station({
+    blockNever: false,
+    attribute: props.attribute,
+    metadata: props.tuple.type.elements.reduce(
+      (x, y) => Metadata.merge(x.rest ?? x, y.rest ?? y),
+      Metadata.initialize(),
+    ),
+  }),
+  minItems: !!props.tuple.type.elements.at(-1)?.rest
+    ? props.tuple.type.elements.length - 1
+    : props.tuple.type.elements.filter((x) => !x.optional).length,
+  maxItems: !!props.tuple.type.elements.at(-1)?.rest
+    ? undefined!
+    : props.tuple.type.elements.length,
+});

package/src/programmers/json/JsonApplicationProgrammer.ts

@@ -10,7 +10,7 @@ import { application_v30_schema } from "../internal/application_v30_schema";
 import { application_v31_schema } from "../internal/application_v31_schema";
 
 export namespace JsonApplicationProgrammer {
-  export const validate = (meta: Metadata) => {
+  export const validate = (meta: Metadata): string[] => {
     const output: string[] = [];
     if (
       meta.atomics.some((a) => a.type === "bigint") ||

package/src/programmers/llm/LlmSchemaProgrammer.ts

@@ -0,0 +1,49 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+
+import { AtomicPredicator } from "../helpers/AtomicPredicator";
+import { llm_schema_station } from "../internal/llm_schema_station";
+
+export namespace LlmSchemaProgrammer {
+  export const validate = (meta: Metadata): string[] => {
+    const output: string[] = [];
+    if (
+      meta.atomics.some((a) => a.type === "bigint") ||
+      meta.constants.some((c) => c.type === "bigint")
+    )
+      output.push("LLM schema does not support bigint type.");
+    if (
+      meta.tuples.some((t) =>
+        t.type.elements.some((e) => e.isRequired() === false),
+      ) ||
+      meta.arrays.some((a) => a.type.value.isRequired() === false)
+    )
+      output.push("LLM schema does not support undefined type in array.");
+    if (meta.maps.length) output.push("LLM schema does not support Map type.");
+    if (meta.sets.length) output.push("LLM schema does not support Set type.");
+    for (const native of meta.natives)
+      if (
+        AtomicPredicator.native(native) === false &&
+        native !== "Date" &&
+        native !== "Blob" &&
+        native !== "File"
+      )
+        output.push(`LLM schema does not support ${native} type.`);
+    if (
+      meta.aliases.some((a) => a.recursive) ||
+      meta.arrays.some((a) => a.type.recursive) ||
+      meta.objects.some((o) => o.recursive) ||
+      meta.tuples.some((t) => t.type.recursive)
+    )
+      output.push("LLM schema does not support recursive type.");
+    return output;
+  };
+
+  export const write = (metadata: Metadata): ILlmSchema =>
+    llm_schema_station({
+      metadata,
+      blockNever: true,
+      attribute: {},
+    });
+}

package/src/schemas/json/IJsonApplication.ts

@@ -1,16 +1,22 @@
-import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
-
-export type IJsonApplication<Version extends "3.0" | "3.1" = "3.1"> =
-  Version extends "3.0" ? IJsonApplication.IV3_0 : IJsonApplication.IV3_1;
-export namespace IJsonApplication {
-  export interface IV3_0 {
-    version: "3.0";
-    schemas: OpenApiV3.IJsonSchema[];
-    components: OpenApiV3.IComponents;
-  }
-  export interface IV3_1 {
-    version: "3.1";
-    components: OpenApi.IComponents;
-    schemas: OpenApi.IJsonSchema[];
-  }
-}
+import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+export type IJsonApplication<
+  Version extends "3.0" | "3.1" = "3.1",
+  Types = unknown[],
+> = Version extends "3.0"
+  ? IJsonApplication.IV3_0<Types>
+  : IJsonApplication.IV3_1<Types>;
+export namespace IJsonApplication {
+  export interface IV3_0<Types = unknown[]> {
+    version: "3.0";
+    schemas: OpenApiV3.IJsonSchema[];
+    components: OpenApiV3.IComponents;
+    __types?: Types | undefined;
+  }
+  export interface IV3_1<Types = unknown[]> {
+    version: "3.1";
+    components: OpenApi.IComponents;
+    schemas: OpenApi.IJsonSchema[];
+    __types?: Types | undefined;
+  }
+}

package/src/transformers/CallExpressionTransformer.ts

@@ -64,6 +64,7 @@ import { JsonIsStringifyTransformer } from "./features/json/JsonIsStringifyTrans
 import { JsonStringifyTransformer } from "./features/json/JsonStringifyTransformer";
 import { JsonValidateParseTransformer } from "./features/json/JsonValidateParseTransformer";
 import { JsonValidateStringifyTransformer } from "./features/json/JsonValidateStringifyTransformer";
+import { LlmSchemaTransformer } from "./features/llm/LlmSchemaTransformer";
 import { MiscAssertCloneTransformer } from "./features/misc/MiscAssertCloneTransformer";
 import { MiscAssertPruneTransformer } from "./features/misc/MiscAssertPruneTransformer";
 import { MiscCloneTransformer } from "./features/misc/MiscCloneTransformer";
@@ -353,9 +354,13 @@ const FUNCTORS: Record<string, Record<string, () => Task>> = {
     createAssertQuery: () => CreateHttpAssertQueryTransformer.transform,
     createValidateQuery: () => CreateHttpValidateQueryTransformer.transform,
   },
+  llm: {
+    schema: () => (project) => () => LlmSchemaTransformer.transform(project),
+  },
   json: {
     // SCHEMA
-    application: () => (P) => () => JsonApplicationTransformer.transform(P),
+    application: () => (project) => () =>
+      JsonApplicationTransformer.transform(project),
 
     // PARSER
     isParse: () => JsonIsParseTransformer.transform,