Merge pull request #46 from samchon/doc/README

Re-write README document.

package.json

@@ -44,6 +44,7 @@
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.12.7",
+    "@types/uuid": "^10.0.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
     "nestia": "^6.0.1",
@@ -54,7 +55,8 @@
     "ts-patch": "^3.2.1",
     "typescript": "^5.5.3",
     "typescript-transform-paths": "^3.4.7",
-    "typia": "^6.9.0"
+    "typia": "^6.9.0",
+    "uuid": "^10.0.0"
   },
   "files": [
     "lib",

src/HttpLlm.ts

@@ -111,12 +111,12 @@ export namespace HttpLlm {
    */
   export interface IFetchProps {
     /**
-     * Document of the OpenAI function call schemas.
+     * Application of the LLM function calling.
      */
     application: IHttpLlmApplication;
 
     /**
-     * Function schema to call.
+     * LLM function schema to call.
      */
     function: IHttpLlmFunction;
 

test/examples/execute.ts

@@ -0,0 +1,51 @@
+import {
+  HttpLlm,
+  IHttpLlmApplication,
+  IHttpLlmFunction,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@samchon/openapi";
+import fs from "fs";
+import typia from "typia";
+
+const main = async (): Promise<void> => {
+  // read swagger document and validate it
+  const swagger:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument = JSON.parse(
+    await fs.promises.readFile("swagger.json", "utf8"),
+  );
+  typia.assert(swagger);
+
+  // convert to emended OpenAPI document,
+  // and compose LLM function calling application
+  const document: OpenApi.IDocument = OpenApi.convert(swagger);
+  const application: IHttpLlmApplication = HttpLlm.application(document);
+
+  // Let's imagine that LLM has selected a function to call
+  const func: IHttpLlmFunction | undefined = application.functions.find(
+    (f) => f.path === "/bbs/articles" && f.method === "post",
+  );
+  typia.assertGuard<IHttpLlmFunction>(func);
+
+  // actual execution is by yourself
+  const article = await HttpLlm.execute({
+    connection: {
+      host: "http://localhost:3000",
+    },
+    application,
+    function: func,
+    arguments: [
+      "general",
+      {
+        title: "Hello, world!",
+        body: "Let's imagine that this argument is composed by LLM.",
+      },
+    ],
+  });
+  console.log("article", article);
+};
+main().catch(console.error);

test/examples/keyword.ts

@@ -0,0 +1,63 @@
+import {
+  HttpLlm,
+  IHttpLlmApplication,
+  IHttpLlmFunction,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@samchon/openapi";
+import fs from "fs";
+import typia from "typia";
+import { v4 } from "uuid";
+
+const main = async (): Promise<void> => {
+  // read swagger document and validate it
+  const swagger:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument = JSON.parse(
+    await fs.promises.readFile("swagger.json", "utf8"),
+  );
+  typia.assert(swagger); // recommended
+
+  // convert to emended OpenAPI document,
+  // and compose LLM function calling application
+  const document: OpenApi.IDocument = OpenApi.convert(swagger);
+  const application: IHttpLlmApplication = HttpLlm.application(document, {
+    keyword: true,
+  });
+
+  // Let's imagine that LLM has selected a function to call
+  const func: IHttpLlmFunction | undefined = application.functions.find(
+    // (f) => f.name === "llm_selected_fuction_name"
+    (f) => f.path === "/bbs/articles/{id}" && f.method === "put",
+  );
+  if (func === undefined) throw new Error("No matched function exists.");
+
+  // actual execution is by yourself
+  const article = await HttpLlm.execute({
+    connection: {
+      host: "http://localhost:3000",
+    },
+    application,
+    function: func,
+    arguments: [
+      {
+        section: "general",
+        id: v4(),
+        query: {
+          language: "en-US",
+          format: "markdown",
+        },
+        body: {
+          title: "Hello, world!",
+          body: "Let's imagine that this argument is composed by LLM.",
+          thumbnail: null,
+        },
+      },
+    ],
+  });
+  console.log("article", article);
+};
+main().catch(console.error);

test/examples/separate.ts

@@ -0,0 +1,71 @@
+import {
+  HttpLlm,
+  IHttpLlmApplication,
+  IHttpLlmFunction,
+  LlmTypeChecker,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@samchon/openapi";
+import fs from "fs";
+import typia from "typia";
+import { v4 } from "uuid";
+
+const main = async (): Promise<void> => {
+  // read swagger document and validate it
+  const swagger:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument = JSON.parse(
+    await fs.promises.readFile("swagger.json", "utf8"),
+  );
+  typia.assert(swagger); // recommended
+
+  // convert to emended OpenAPI document,
+  // and compose LLM function calling application
+  const document: OpenApi.IDocument = OpenApi.convert(swagger);
+  const application: IHttpLlmApplication = HttpLlm.application(document, {
+    keyword: false,
+    separate: (schema) =>
+      LlmTypeChecker.isString(schema) && schema.contentMediaType !== undefined,
+  });
+
+  // Let's imagine that LLM has selected a function to call
+  const func: IHttpLlmFunction | undefined = application.functions.find(
+    // (f) => f.name === "llm_selected_fuction_name"
+    (f) => f.path === "/bbs/articles/{id}" && f.method === "put",
+  );
+  if (func === undefined) throw new Error("No matched function exists.");
+
+  // actual execution is by yourself
+  const article = await HttpLlm.execute({
+    connection: {
+      host: "http://localhost:3000",
+    },
+    application,
+    function: func,
+    arguments: HttpLlm.mergeParameters({
+      function: func,
+      llm: [
+        // LLM composed parameter values
+        "general",
+        v4(),
+        {
+          language: "en-US",
+          format: "markdown",
+        },
+        {
+          title: "Hello, world!",
+          content: "Let's imagine that this argument is composed by LLM.",
+        },
+      ],
+      human: [
+        // Human composed parameter values
+        { thumbnail: "https://example.com/thumbnail.jpg" },
+      ],
+    }),
+  });
+  console.log("article", article);
+};
+main().catch(console.error);