typia 6.10.0-dev.20240906 → 6.10.0-dev.20240908

package/src/programmers/internal/application_escaped.ts

@@ -1,74 +1,74 @@
-import { OpenApi, OpenApiV3 } from "@samchon/openapi";
-
-import { Metadata } from "../../schemas/metadata/Metadata";
-import { MetadataEscaped } from "../../schemas/metadata/MetadataEscaped";
-
-/**
- * @internal
- */
-export const application_escaped =
-  <Version extends "3.0" | "3.1">(
-    generator: (meta: Metadata) => Schema<Version>,
-  ) =>
-  (escaped: MetadataEscaped): Schema<Version>[] => {
-    const output: Schema<Version> | null = generator(escaped.returns);
-    if (output === null) return [];
-
-    if (is_date(new Set())(escaped.original)) {
-      const string: StringSchema<Version> | undefined = is_string(output)
-        ? output
-        : is_one_of(output)
-          ? (output.oneOf.find(is_string) as StringSchema<Version>)
-          : undefined;
-      if (
-        string !== undefined &&
-        string.format !== "date" &&
-        string.format !== "date-time"
-      )
-        string.format = "date-time";
-    }
-    return is_one_of(output) ? (output.oneOf as Schema<Version>[]) : [output];
-  };
-
-/**
- * @internal
- */
-const is_string = <Version extends "3.0" | "3.1">(
-  elem: Schema<Version>,
-): elem is StringSchema<Version> =>
-  (elem as StringSchema<Version>).type === "string";
-
-/**
- * @internal
- */
-const is_one_of = <Version extends "3.0" | "3.1">(
-  elem: Schema<Version>,
-): elem is OneOfSchema<Version> =>
-  Array.isArray((elem as OneOfSchema<Version>).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))
-    );
-  };
-
-type Schema<Version extends "3.0" | "3.1"> = Version extends "3.0"
-  ? OpenApiV3.IJsonSchema
-  : OpenApi.IJsonSchema;
-type StringSchema<Version extends "3.0" | "3.1"> = Version extends "3.0"
-  ? OpenApiV3.IJsonSchema.IString
-  : OpenApi.IJsonSchema.IString;
-type OneOfSchema<Version extends "3.0" | "3.1"> = Version extends "3.0"
-  ? OpenApiV3.IJsonSchema.IOneOf
-  : OpenApi.IJsonSchema.IOneOf;
+import { OpenApi, OpenApiV3 } from "@samchon/openapi";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataEscaped } from "../../schemas/metadata/MetadataEscaped";
+
+/**
+ * @internal
+ */
+export const application_escaped =
+  <Version extends "3.0" | "3.1">(
+    generator: (meta: Metadata) => Schema<Version>,
+  ) =>
+  (escaped: MetadataEscaped): Schema<Version>[] => {
+    const output: Schema<Version> | null = generator(escaped.returns);
+    if (output === null) return [];
+
+    if (is_date(new Set())(escaped.original)) {
+      const string: StringSchema<Version> | undefined = is_string(output)
+        ? output
+        : is_one_of(output)
+          ? (output.oneOf.find(is_string) as StringSchema<Version>)
+          : undefined;
+      if (
+        string !== undefined &&
+        string.format !== "date" &&
+        string.format !== "date-time"
+      )
+        string.format = "date-time";
+    }
+    return is_one_of(output) ? (output.oneOf as Schema<Version>[]) : [output];
+  };
+
+/**
+ * @internal
+ */
+const is_string = <Version extends "3.0" | "3.1">(
+  elem: Schema<Version>,
+): elem is StringSchema<Version> =>
+  (elem as StringSchema<Version>).type === "string";
+
+/**
+ * @internal
+ */
+const is_one_of = <Version extends "3.0" | "3.1">(
+  elem: Schema<Version>,
+): elem is OneOfSchema<Version> =>
+  Array.isArray((elem as OneOfSchema<Version>).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))
+    );
+  };
+
+type Schema<Version extends "3.0" | "3.1"> = Version extends "3.0"
+  ? OpenApiV3.IJsonSchema
+  : OpenApi.IJsonSchema;
+type StringSchema<Version extends "3.0" | "3.1"> = Version extends "3.0"
+  ? OpenApiV3.IJsonSchema.IString
+  : OpenApi.IJsonSchema.IString;
+type OneOfSchema<Version extends "3.0" | "3.1"> = Version extends "3.0"
+  ? OpenApiV3.IJsonSchema.IOneOf
+  : OpenApi.IJsonSchema.IOneOf;

package/src/programmers/internal/application_v30_object.ts

@@ -53,7 +53,7 @@ const create_object_schema =
     for (const property of obj.properties) {
       if (
         // FUNCTIONAL TYPE
-        property.value.functional === true &&
+        property.value.functions.length &&
         property.value.nullable === false &&
         property.value.isRequired() === true &&
         property.value.size() === 0

package/src/programmers/internal/application_v31_object.ts

@@ -51,7 +51,7 @@ const create_object_schema =
     for (const property of obj.properties) {
       if (
         // FUNCTIONAL TYPE
-        property.value.functional === true &&
+        property.value.functions.length &&
         property.value.nullable === false &&
         property.value.isRequired() === true &&
         property.value.size() === 0

package/src/programmers/internal/llm_schema_object.ts

@@ -30,7 +30,7 @@ export const llm_schema_object = (props: {
   for (const property of props.object.properties) {
     if (
       // FUNCTIONAL TYPE
-      property.value.functional === true &&
+      property.value.functions.length &&
       property.value.nullable === false &&
       property.value.isRequired() === true &&
       property.value.size() === 0

package/src/programmers/internal/stringify_regular_properties.ts

@@ -31,14 +31,14 @@ export const stringify_regular_properties = (
       (entry.meta.isRequired() === false &&
         entry.meta.nullable === false &&
         entry.meta.size() === 0) ||
-      (entry.meta.functional &&
+      (!!entry.meta.functions.length &&
         entry.meta.nullable === false &&
         entry.meta.size() === 1);
 
     if (empty === true) return;
     else if (
       entry.meta.isRequired() === false ||
-      entry.meta.functional === true ||
+      entry.meta.functions.length ||
       entry.meta.any === true
     )
       output.push(
@@ -52,7 +52,7 @@ export const stringify_regular_properties = (
                   entry.input,
                 ),
               );
-            if (entry.meta.functional || entry.meta.any)
+            if (entry.meta.functions.length || entry.meta.any)
               conditions.push(
                 ts.factory.createStrictEquality(
                   ts.factory.createStringLiteral("function"),
@@ -78,4 +78,4 @@ export const stringify_regular_properties = (
  * @internal
  */
 const sequence = (meta: Metadata): number =>
-  meta.any || !meta.isRequired() || meta.functional ? 0 : 1;
+  meta.any || !meta.isRequired() || meta.functions.length ? 0 : 1;

package/src/programmers/json/JsonStringifyProgrammer.ts

@@ -233,7 +233,7 @@ export namespace JsonStringifyProgrammer {
               explore,
             ),
         });
-      else if (meta.functional === true)
+      else if (meta.functions.length)
         unions.push({
           type: "functional",
           is: () => IsProgrammer.decode_functional(input),
@@ -797,7 +797,7 @@ export namespace JsonStringifyProgrammer {
     meta: Metadata,
     explore: FeatureProgrammer.IExplore,
   ): ((expression: ts.Expression) => ts.Expression) => {
-    if (meta.functional === false) return (expression) => expression;
+    if (meta.functions.length === 0) return (expression) => expression;
     return (expression) =>
       ts.factory.createConditionalExpression(
         ts.factory.createStrictInequality(

package/src/programmers/llm/LlmApplicationProgrammer.ts

@@ -0,0 +1,211 @@
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { ILlmFunction } from "@samchon/openapi/lib/structures/ILlmFunction";
+
+import { MetadataFactory } from "../../factories/MetadataFactory";
+
+import { Metadata } from "../../schemas/metadata/Metadata";
+import { MetadataFunction } from "../../schemas/metadata/MetadataFunction";
+import { MetadataObject } from "../../schemas/metadata/MetadataObject";
+
+import { IJsDocTagInfo } from "../../module";
+import { LlmSchemaProgrammer } from "./LlmSchemaProgrammer";
+
+export namespace LlmApplicationProgrammer {
+  export const validate = (
+    meta: Metadata,
+    explore: MetadataFactory.IExplore,
+  ): string[] => {
+    if (explore.top === false) return LlmSchemaProgrammer.validate(meta);
+
+    const output: string[] = [];
+    const valid: boolean =
+      meta.size() === 1 &&
+      meta.objects.length === 1 &&
+      meta.isRequired() === true &&
+      meta.nullable === false;
+    if (valid === false)
+      output.push(
+        "LLM application's generic arugment must be a class/interface type.",
+      );
+
+    const object: MetadataObject | undefined = meta.objects[0];
+    if (object !== undefined) {
+      if (object.properties.some((p) => p.key.isSoleLiteral() === false))
+        output.push("LLM application does not allow dynamic keys.");
+      let least: boolean = false;
+      for (const p of object.properties) {
+        const value: Metadata = p.value;
+        if (value.functions.length) {
+          least ||= true;
+          if (valid === false) {
+            if (value.functions.length !== 1 || value.size() !== 1)
+              output.push(
+                "LLM application's function type does not allow union type.",
+              );
+            if (value.isRequired() === false)
+              output.push("LLM application's function type must be required.");
+            if (value.nullable === true)
+              output.push(
+                "LLM application's function type must not be nullable.",
+              );
+          }
+        }
+      }
+      if (least === false)
+        output.push(
+          "LLM application's target type must have at least a function type.",
+        );
+    }
+    return output;
+  };
+
+  export const write = (metadata: Metadata): ILlmApplication => {
+    const errors: string[] = validate(metadata, {
+      top: true,
+      object: null,
+      property: null,
+      nested: null,
+      escaped: false,
+      aliased: false,
+    });
+    if (errors.length)
+      throw new Error("Failed to write LLM application: " + errors.join("\n"));
+
+    const object: MetadataObject = metadata.objects[0]!;
+    return {
+      functions: object.properties
+        .filter(
+          (p) =>
+            p.value.functions.length === 1 &&
+            p.value.size() === 1 &&
+            p.key.isSoleLiteral(),
+        )
+        .map((p) =>
+          writeFunction({
+            name: p.key.getSoleLiteral()!,
+            function: p.value.functions[0]!,
+            description: p.description,
+            jsDocTags: p.jsDocTags,
+          }),
+        ),
+      options: {
+        separate: null,
+      },
+    };
+  };
+
+  const writeFunction = (props: {
+    name: string;
+    function: MetadataFunction;
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+  }): ILlmFunction => ({
+    name: props.name,
+    parameters: props.function.parameters.map((p) => {
+      const jsDocTagDescription = writeDescriptionFromJsDocTag({
+        jsDocTags: p.jsDocTags,
+        tag: "param",
+        parameter: p.name,
+      });
+      return writeSchema({
+        metadata: p.type,
+        description: jsDocTagDescription ?? p.description,
+        jsDocTags: jsDocTagDescription ? [] : p.jsDocTags,
+      });
+    }),
+    output:
+      props.function.output.size() || props.function.output.nullable
+        ? writeSchema({
+            metadata: props.function.output,
+            description:
+              writeDescriptionFromJsDocTag({
+                jsDocTags: props.jsDocTags,
+                tag: "return",
+              }) ??
+              writeDescriptionFromJsDocTag({
+                jsDocTags: props.jsDocTags,
+                tag: "returns",
+              }),
+            jsDocTags: [],
+          })
+        : undefined,
+    description: props.description ?? undefined,
+  });
+
+  const writeSchema = (props: {
+    metadata: Metadata;
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+  }): ILlmSchema => {
+    const schema: ILlmSchema = LlmSchemaProgrammer.write(props.metadata);
+    const explicit: Pick<ILlmSchema, "title" | "description"> =
+      writeDescription({
+        description: props.description,
+        jsDocTags: props.jsDocTags,
+      });
+    return {
+      ...schema,
+      ...(!!explicit.title?.length || !!explicit.description?.length
+        ? explicit
+        : {}),
+    };
+  };
+
+  const writeDescription = (props: {
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+  }): Pick<ILlmSchema, "title" | "description"> => {
+    const title: string | undefined = (() => {
+      const [explicit] = getJsDocTexts({
+        jsDocTags: props.jsDocTags,
+        name: "title",
+      });
+      if (explicit?.length) return explicit;
+      else if (!props.description?.length) return undefined;
+
+      const index: number = props.description.indexOf("\n");
+      const top: string = (
+        index === -1 ? props.description : props.description.substring(0, index)
+      ).trim();
+      return top.endsWith(".") ? top.substring(0, top.length - 1) : undefined;
+    })();
+    return {
+      title: title,
+      description: props.description?.length ? props.description : undefined,
+    } as any;
+  };
+
+  const writeDescriptionFromJsDocTag = (props: {
+    jsDocTags: IJsDocTagInfo[];
+    tag: string;
+    parameter?: string;
+  }): string | null => {
+    const parametric: (elem: IJsDocTagInfo) => boolean = props.parameter
+      ? (tag) =>
+          tag.text!.find(
+            (elem) =>
+              elem.kind === "parameterName" && elem.text === props.parameter,
+          ) !== undefined
+      : () => true;
+    const tag: IJsDocTagInfo | undefined = props.jsDocTags.find(
+      (tag) => tag.name === props.tag && tag.text && parametric(tag),
+    );
+    return tag && tag.text
+      ? (tag.text.find((elem) => elem.kind === "text")?.text ?? null)
+      : null;
+  };
+
+  const getJsDocTexts = (props: {
+    jsDocTags: IJsDocTagInfo[];
+    name: string;
+  }): string[] =>
+    props.jsDocTags
+      .filter(
+        (tag) =>
+          tag.name === props.name &&
+          tag.text &&
+          tag.text.find((elem) => elem.kind === "text" && elem.text.length) !==
+            undefined,
+      )
+      .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
+}

package/src/programmers/misc/MiscCloneProgrammer.ts

@@ -179,7 +179,7 @@ export namespace MiscCloneProgrammer {
       // LIST UP UNION TYPES
       //----
       // FUNCTIONAL
-      if (meta.functional)
+      if (meta.functions.length)
         unions.push({
           type: "functional",
           is: () =>

package/src/programmers/notations/NotationGeneralProgrammer.ts

@@ -193,7 +193,7 @@ export namespace NotationGeneralProgrammer {
       // LIST UP UNION TYPES
       //----
       // FUNCTIONAL
-      if (meta.functional)
+      if (meta.functions.length)
         unions.push({
           type: "functional",
           is: () =>

package/src/schemas/metadata/IMetadata.ts

@@ -2,6 +2,7 @@ import { IMetadataAtomic } from "./IMetadataAtomic";
 import { IMetadataConstant } from "./IMetadataConstant";
 import { IMetadataEntry } from "./IMetadataEntry";
 import { IMetadataEscaped } from "./IMetadataEscaped";
+import { IMetadataFunction } from "./IMetadataFunction";
 import { IMetadataTemplate } from "./IMetadataTemplate";
 import { IMetadataTypeTag } from "./IMetadataTypeTag";
 
@@ -10,7 +11,7 @@ export interface IMetadata {
   required: boolean;
   optional: boolean;
   nullable: boolean;
-  functional: boolean;
+  functions: IMetadataFunction[];
 
   atomics: IMetadataAtomic[];
   constants: IMetadataConstant[];

package/src/schemas/metadata/IMetadataFunction.ts

@@ -0,0 +1,8 @@
+import { IMetadata } from "./IMetadata";
+import { IMetadataParameter } from "./IMetadataParameter";
+
+export interface IMetadataFunction {
+  parameters: IMetadataParameter[];
+  output: IMetadata;
+  async: boolean;
+}

package/src/schemas/metadata/IMetadataParameter.ts

@@ -0,0 +1,9 @@
+import { IJsDocTagInfo } from "./IJsDocTagInfo";
+import { IMetadata } from "./IMetadata";
+
+export interface IMetadataParameter {
+  name: string;
+  type: IMetadata;
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+}

package/src/schemas/metadata/Metadata.ts

@@ -10,6 +10,7 @@ import { MetadataArray } from "./MetadataArray";
 import { MetadataAtomic } from "./MetadataAtomic";
 import { MetadataConstant } from "./MetadataConstant";
 import { MetadataEscaped } from "./MetadataEscaped";
+import { MetadataFunction } from "./MetadataFunction";
 import { MetadataObject } from "./MetadataObject";
 import { MetadataTemplate } from "./MetadataTemplate";
 import { MetadataTuple } from "./MetadataTuple";
@@ -19,7 +20,6 @@ export class Metadata {
   public required: boolean;
   public optional: boolean;
   public nullable: boolean;
-  public functional: boolean;
 
   public escaped: MetadataEscaped | null;
   public atomics: MetadataAtomic[];
@@ -31,6 +31,7 @@ export class Metadata {
   public arrays: MetadataArray[];
   public tuples: MetadataTuple[];
   public objects: MetadataObject[];
+  public functions: MetadataFunction[];
 
   public natives: string[];
   public sets: Metadata[];
@@ -53,7 +54,7 @@ export class Metadata {
     this.required = props.required;
     this.optional = props.optional;
     this.nullable = props.nullable;
-    this.functional = props.functional;
+    this.functions = props.functions;
 
     this.escaped = props.escaped;
     this.atomics = props.atomics;
@@ -87,7 +88,6 @@ export class Metadata {
       nullable: false,
       required: true,
       optional: false,
-      functional: false,
 
       escaped: null,
       constants: [],
@@ -97,6 +97,7 @@ export class Metadata {
       tuples: [],
       objects: [],
       aliases: [],
+      functions: [],
 
       rest: null,
       natives: [],
@@ -113,7 +114,7 @@ export class Metadata {
       required: this.required,
       optional: this.optional,
       nullable: this.nullable,
-      functional: this.functional,
+      functions: this.functions.map((f) => f.toJSON()),
 
       atomics: this.atomics.map((a) => a.toJSON()),
       constants: this.constants.map((c) => c.toJSON()),
@@ -147,7 +148,7 @@ export class Metadata {
       required: meta.required,
       optional: meta.optional,
       nullable: meta.nullable,
-      functional: meta.functional,
+      functions: meta.functions.map((f) => MetadataFunction.from(f, dict)),
 
       constants: meta.constants.map(MetadataConstant.from),
       atomics: meta.atomics.map(MetadataAtomic.from),
@@ -218,7 +219,6 @@ export class Metadata {
     return (
       (this.any ? 1 : 0) +
       (this.escaped ? 1 : 0) +
-      (this.functional ? 1 : 0) +
       (this.rest ? this.rest.size() : 0) +
       this.templates.length +
       this.atomics.length +
@@ -229,6 +229,7 @@ export class Metadata {
       this.maps.length +
       this.sets.length +
       this.objects.length +
+      this.functions.length +
       this.aliases.length
     );
   }
@@ -237,7 +238,6 @@ export class Metadata {
     return (
       (this.any ? 1 : 0) +
       (this.escaped ? 1 : 0) +
-      (this.functional ? 1 : 0) +
       (this.templates.length ? 1 : 0) +
       (this.atomics.length ? 1 : 0) +
       (this.constants.length ? 1 : 0) +
@@ -248,6 +248,7 @@ export class Metadata {
       (this.sets.length ? 1 : 0) +
       (this.maps.length ? 1 : 0) +
       (this.objects.length ? 1 : 0) +
+      (this.functions.length ? 1 : 0) +
       (this.aliases.length ? 1 : 0)
     );
   }
@@ -301,7 +302,7 @@ export namespace Metadata {
     if (x.any || y.any) return true;
     if (x.isRequired() === false && false === y.isRequired()) return true;
     if (x.nullable === true && true === y.nullable) return true;
-    if (x.functional === true && y.functional === true) return true;
+    if (!!x.functions.length && !!y.functions.length === true) return true;
 
     //----
     // INSTANCES
@@ -459,7 +460,7 @@ export namespace Metadata {
     }
 
     // FUNCTIONAL
-    if (x.functional === false && y.functional) return false;
+    if (!!x.functions.length === false && !!y.functions.length) return false;
 
     // SUCCESS
     return true;
@@ -474,7 +475,7 @@ export namespace Metadata {
       nullable: x.nullable || y.nullable,
       required: x.required && y.required,
       optional: x.optional || y.optional,
-      functional: x.functional || y.functional,
+      functions: x.functions.length ? x.functions : y.functions, // @todo
 
       escaped:
         x.escaped !== null && y.escaped !== null
@@ -482,7 +483,7 @@ export namespace Metadata {
               original: merge(x.escaped.original, y.escaped.original),
               returns: merge(x.escaped.returns, y.escaped.returns),
             })
-          : x.escaped ?? y.escaped,
+          : (x.escaped ?? y.escaped),
       atomics: mergeTaggedTypes({
         container: x.atomics,
         equals: (x, y) => x.type === y.type,
@@ -494,7 +495,7 @@ export namespace Metadata {
       rest:
         x.rest !== null && y.rest !== null
           ? merge(x.rest, y.rest)
-          : x.rest ?? y.rest,
+          : (x.rest ?? y.rest),
       // arrays: x.arrays.slice(),
       arrays: mergeTaggedTypes({
         container: x.arrays,