@agentica/core 0.21.0 → 0.23.0

package/src/factory/events.ts

@@ -15,11 +15,13 @@ import type { AgenticaRequestEvent } from "../events/AgenticaRequestEvent";
 import type { AgenticaResponseEvent } from "../events/AgenticaResponseEvent";
 import type { AgenticaSelectEvent } from "../events/AgenticaSelectEvent";
 import type { AgenticaTextEvent } from "../events/AgenticaTextEvent";
+import type { AgenticaUserInputEvent } from "../events/AgenticaUserInputEvent";
 import type { AgenticaValidateEvent } from "../events/AgenticaValidateEvent";
 import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
+import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
 
-import { createExecuteHistory, createSelectHistory } from "./histories";
+import { createExecuteHistory, createSelectHistory, createUserInputHistory } from "./histories";
 
 /* -----------------------------------------------------------
   FUNCTION SELECTS
@@ -34,6 +36,23 @@ export function createInitializeEvent(): AgenticaInitializeEvent {
   };
 }
 
+export function createUserInputEvent(props: {
+  contents: Array<AgenticaUserInputHistory.Contents>;
+}): AgenticaUserInputEvent {
+  return {
+    type: "user_input",
+    role: "user",
+    contents: props.contents,
+    join: async () => props.contents,
+    toJSON: () => ({
+      type: "user_input",
+      contents: props.contents,
+    }),
+    toHistory: () => createUserInputHistory({
+      contents: props.contents,
+    }),
+  };
+}
 export function createSelectEvent<Model extends ILlmSchema.Model>(props: {
   selection: AgenticaOperationSelection<Model>;
 }): AgenticaSelectEvent<Model> {
@@ -134,31 +153,30 @@ export function createExecuteEvent<Model extends ILlmSchema.Model>(props: {
 /* -----------------------------------------------------------
   TEXT STEAMING
 ----------------------------------------------------------- */
-export function createTextEvent<Role extends "user" | "assistant">(props: {
-  role: Role;
+export function createTextEvent(props: {
   stream: AsyncGenerator<string, undefined, undefined>;
   done: () => boolean;
   get: () => string;
   join: () => Promise<string>;
-}): AgenticaTextEvent<Role> {
+}): AgenticaTextEvent {
   return {
     type: "text",
-    role: props.role,
+    role: "assistant",
     stream: props.stream,
     join: props.join,
     toJSON: () => ({
       type: "text",
-      role: props.role,
+      role: "assistant",
       done: props.done(),
       text: props.get(),
     }),
     toHistory: () => ({
       type: "text",
-      role: props.role,
+      role: "assistant",
       text: props.get(),
       toJSON: () => ({
         type: "text",
-        role: props.role,
+        role: "assistant",
         text: props.get(),
       }),
     }),

package/src/factory/histories.ts

@@ -9,6 +9,7 @@ import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory
 import type { AgenticaHistory } from "../histories/AgenticaHistory";
 import type { AgenticaSelectHistory } from "../histories/AgenticaSelectHistory";
 import type { AgenticaTextHistory } from "../histories/AgenticaTextHistory";
+import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
 import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
 
 export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaHistory<Model>): OpenAI.ChatCompletionMessageParam[] {
@@ -16,7 +17,8 @@ export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaH
   if (history.type === "describe") {
     return [];
   }
-  else if (history.type === "text") {
+
+  if (history.type === "text") {
     return [
       {
         role: history.role,
@@ -24,7 +26,8 @@ export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaH
       },
     ];
   }
-  else if (history.type === "select" || history.type === "cancel") {
+
+  if (history.type === "select" || history.type === "cancel") {
     return [
       {
         role: "assistant",
@@ -52,59 +55,89 @@ export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaH
     ];
   }
 
-  return [
-    {
-      role: "assistant",
-      tool_calls: [
-        {
-          type: "function",
-          id: history.id,
+  if (history.type === "execute") {
+    return [
+      {
+        role: "assistant",
+        tool_calls: [
+          {
+            type: "function",
+            id: history.id,
+            function: {
+              name: history.operation.name,
+              arguments: JSON.stringify(history.arguments),
+            },
+          },
+        ],
+      },
+      {
+        role: "tool",
+        tool_call_id: history.id,
+        content: JSON.stringify({
           function: {
-            name: history.operation.name,
-            arguments: JSON.stringify(history.arguments),
+            protocol: history.operation.protocol,
+            description: history.operation.function.description,
+            parameters: history.operation.function.parameters,
+            output: history.operation.function.output,
+            ...(history.operation.protocol === "http"
+              ? {
+                  method: history.operation.function.method,
+                  path: history.operation.function.path,
+                }
+              : {}),
           },
-        },
-      ],
-    },
-    {
-      role: "tool",
-      tool_call_id: history.id,
-      content: JSON.stringify({
-        function: {
-          protocol: history.operation.protocol,
-          description: history.operation.function.description,
-          parameters: history.operation.function.parameters,
-          output: history.operation.function.output,
           ...(history.operation.protocol === "http"
             ? {
-                method: history.operation.function.method,
-                path: history.operation.function.path,
+                status: (history.value as IHttpResponse).status,
+                data: (history.value as IHttpResponse).body,
               }
-            : {}),
-        },
-        ...(history.operation.protocol === "http"
-          ? {
-              status: (history.value as IHttpResponse).status,
-              data: (history.value as IHttpResponse).body,
-            }
-          : {
-              value: history.value,
-            }),
-      }),
-    },
-  ];
+            : {
+                value: history.value,
+              }),
+        }),
+      },
+    ];
+  }
+
+  if (history.type === "user_input") {
+    return [
+      {
+        role: "user",
+        content: history.contents,
+      },
+    ];
+  }
+
+  history satisfies never;
+  throw new Error("Invalid history type");
+}
+
+/* -----------------------------------------------------------
+  USER INPUT PROMPTS
+----------------------------------------------------------- */
+export function createUserInputHistory(props: {
+  contents: Array<AgenticaUserInputHistory.Contents>;
+}): AgenticaUserInputHistory {
+  return {
+    type: "user_input",
+    role: "user",
+    contents: props.contents,
+    toJSON: () => ({
+      type: "user_input",
+      contents: props.contents,
+    }),
+  };
 }
 
 /* -----------------------------------------------------------
   TEXT PROMPTS
 ----------------------------------------------------------- */
-export function createTextHistory<Role extends "assistant" | "user" = "assistant" | "user">(props: {
-  role: Role;
+export function createTextHistory(props: {
   text: string;
-}): AgenticaTextHistory<Role> {
-  const prompt: IAgenticaHistoryJson.IText<Role> = {
+}): AgenticaTextHistory {
+  const prompt: IAgenticaHistoryJson.IText = {
     type: "text",
-    role: props.role,
+    role: "assistant",
     text: props.text,
   };
   return {

package/src/functional/assertHttpController.ts

@@ -0,0 +1,112 @@
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmSchema, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
+
+import { HttpLlm, OpenApi } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an HTTP controller with type assertion.
+ *
+ * Create an {@link IAgenticaController.IHttp} instance which represents
+ * the HTTP controller from the given Swagger/OpenAPI document and the
+ * target LLM model with connection information.
+ *
+ * By the way, even though this `assertHttpController` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will throw an error with detailed type error tracing information.
+ *
+ * @param props Properties to create the HTTP controller instance
+ * @returns HTTP controller instance
+ * @throws {@link TypeGuardError} when the given document is invalid
+ * @author Samchon
+ */
+export function assertHttpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Target LLM model.
+   */
+  model: Model;
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<Model>>;
+
+  /**
+   * Executor of the API function.
+   *
+   * @param props Properties of the API function call
+   * @returns HTTP response of the API function call
+   */
+  execute?: (props: {
+    /**
+     * Connection to the server.
+     */
+    connection: IHttpConnection;
+
+    /**
+     * Application schema.
+     */
+    application: IHttpLlmApplication<Model>;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction<Model>;
+
+    /**
+     * Arguments of the function calling.
+     *
+     * It is an object of key-value pairs of the API function's parameters.
+     * The property keys are composed by below rules:
+     *
+     * - parameter names
+     * - query parameter as an object type if exists
+     * - body parameter if exists
+     */
+    arguments: object;
+  }) => Promise<IHttpResponse>;
+}): IAgenticaController.IHttp<Model> {
+  const document = OpenApi.convert(typia.assert<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  >(props.document));
+  return {
+    protocol: "http",
+    name: props.name,
+    application: HttpLlm.application({
+      model: props.model,
+      document,
+      options: props.options,
+    }),
+    execute: props.execute,
+    connection: props.connection,
+  };
+}

package/src/functional/assertHttpLlmApplication.ts

@@ -28,6 +28,7 @@ import typia from "typia";
  * @returns  HTTP LLM application instance
  * @throws {@link TypeGuardError} when the given document is invalid
  * @author Samchon
+ * @deprecated Use {@link assertHttpController} instead.
  */
 export function assertHttpLlmApplication<
   Model extends ILlmSchema.Model,

package/src/functional/assertMcpController.ts

@@ -19,7 +19,7 @@ import type { IAgenticaController } from "../structures/IAgenticaController";
  * @param props.model Model schema of the LLM function calling.
  * @param props.options Options to create the MCP controller.
  * @returns MCP LLM application instance
- * @author Samchon
+ * @author sunrabbit123
  */
 export async function assertMcpController<Model extends ILlmSchema.Model>(props: {
   name: string;
@@ -42,7 +42,6 @@ export async function assertMcpController<Model extends ILlmSchema.Model>(props:
     protocol: "mcp",
     name: props.name,
     client: props.client,
-
     application,
   };
 }

package/src/functional/validateHttpController.ts

@@ -0,0 +1,118 @@
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmSchema, IValidation, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
+
+import { HttpLlm, OpenApi } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an HTTP controller with type validation.
+ *
+ * Create an {@link IAgenticaController.IHttp} instance which represents
+ * the HTTP controller from the given Swagger/OpenAPI document and the
+ * target LLM model with connection information.
+ *
+ * By the way, even though this `validateHttpController` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will return {@link IValidation.IFailure} instance with detailed
+ * type error tracing information.
+ *
+ * @param props Properties to create the HTTP controller instance
+ * @returns Validation result of the HTTP controller composition
+ * @author Samchon
+ */
+export function validateHttpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Target LLM model.
+   */
+  model: Model;
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<Model>>;
+
+  /**
+   * Executor of the API function.
+   *
+   * @param props Properties of the API function call
+   * @returns HTTP response of the API function call
+   */
+  execute?: (props: {
+    /**
+     * Connection to the server.
+     */
+    connection: IHttpConnection;
+
+    /**
+     * Application schema.
+     */
+    application: IHttpLlmApplication<Model>;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction<Model>;
+
+    /**
+     * Arguments of the function calling.
+     *
+     * It is an object of key-value pairs of the API function's parameters.
+     * The property keys are composed by below rules:
+     *
+     * - parameter names
+     * - query parameter as an object type if exists
+     * - body parameter if exists
+     */
+    arguments: object;
+  }) => Promise<IHttpResponse>;
+}): IValidation<IAgenticaController.IHttp<Model>> {
+  const inspect = typia.validate<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  >(props.document);
+  if (inspect.success === false) {
+    return inspect;
+  }
+  return {
+    success: true,
+    data: {
+      protocol: "http",
+      name: props.name,
+      application: HttpLlm.application({
+        model: props.model,
+        document: OpenApi.convert(inspect.data),
+        options: props.options,
+      }),
+      execute: props.execute,
+      connection: props.connection,
+    },
+  };
+}

package/src/functional/validateHttpLlmApplication.ts

@@ -29,6 +29,7 @@ import typia from "typia";
  * @param props Properties to create the HTTP LLM application instance
  * @returns Validation result of the HTTP LLM application composition
  * @author Samchon
+ * @deprecated Use {@link validateHttpController} instead.
  */
 export function validateHttpLlmApplication<
   Model extends ILlmSchema.Model,
@@ -67,7 +68,6 @@ export function validateHttpLlmApplication<
   if (inspect.success === false) {
     return inspect;
   }
-
   return {
     success: true,
     data: HttpLlm.application({

package/src/functional/validateMcpController.ts

@@ -0,0 +1,56 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
+import type { ILlmSchema, IMcpLlmApplication, IMcpTool, IValidation } from "@samchon/openapi";
+
+import { McpLlm } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an MCP controller with type validation.
+ *
+ * Create an {@link IAgenticaController.IMcp} instance which represents
+ * an MCP (Model Context Protocol) controller with LLM function calling
+ * schemas and client connection.
+ *
+ * @param props Properties to create the MCP controller
+ * @param props.name Name of the MCP implementation.
+ * @param props.client Client connection to the MCP implementation.
+ * @param props.model Model schema of the LLM function calling.
+ * @param props.options Options to create the MCP controller.
+ * @returns MCP LLM application instance
+ * @author SunRabbit
+ */
+export async function validateMcpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  name: string;
+  client: Client;
+  model: Model;
+  options?: Partial<IMcpLlmApplication.IOptions<Model>>;
+}): Promise<IValidation<IAgenticaController.IMcp<Model>>> {
+  // for peerDependencies
+  const { ListToolsResultSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+  // get list of tools
+  const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
+  const inspect = typia.validate<Array<IMcpTool>>(tools);
+  if (inspect.success === false) {
+    return inspect;
+  }
+
+  const application: IMcpLlmApplication<Model> = McpLlm.application<Model>({
+    model: props.model,
+    tools: typia.assert<Array<IMcpTool>>(tools),
+  });
+
+  return {
+    success: true,
+    data: {
+      protocol: "mcp",
+      name: props.name,
+      client: props.client,
+      application,
+    },
+  };
+}

package/src/histories/AgenticaHistory.ts

@@ -5,13 +5,15 @@ import type { AgenticaDescribeHistory } from "./AgenticaDescribeHistory";
 import type { AgenticaExecuteHistory } from "./AgenticaExecuteHistory";
 import type { AgenticaSelectHistory } from "./AgenticaSelectHistory";
 import type { AgenticaTextHistory } from "./AgenticaTextHistory";
+import type { AgenticaUserInputHistory } from "./AgenticaUserInputHistory";
 
 export type AgenticaHistory<Model extends ILlmSchema.Model> =
   | AgenticaCancelHistory<Model>
   | AgenticaDescribeHistory<Model>
   | AgenticaExecuteHistory<Model>
   | AgenticaSelectHistory<Model>
-  | AgenticaTextHistory;
+  | AgenticaTextHistory
+  | AgenticaUserInputHistory;
 export namespace AgenticaHistory {
   export type Type = AgenticaHistory<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
@@ -20,5 +22,6 @@ export namespace AgenticaHistory {
     execute: AgenticaExecuteHistory<Model>;
     select: AgenticaSelectHistory<Model>;
     text: AgenticaTextHistory;
+    user_input: AgenticaUserInputHistory;
   }
 }

package/src/histories/AgenticaTextHistory.ts

@@ -2,9 +2,7 @@ import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
 
 import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
 
-export interface AgenticaTextHistory<
-  Role extends "assistant" | "user" = "assistant" | "user",
-> extends AgenticaHistoryBase<"text", IAgenticaHistoryJson.IText> {
-  role: Role;
+export interface AgenticaTextHistory extends AgenticaHistoryBase<"text", IAgenticaHistoryJson.IText> {
+  role: "assistant";
   text: string;
 }

package/src/histories/AgenticaUserInputHistory.ts

@@ -0,0 +1,88 @@
+import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
+
+import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
+
+export interface AgenticaUserInputHistory extends AgenticaHistoryBase<"user_input", IAgenticaHistoryJson.IUserInput> {
+  role: "user";
+  contents: Array<AgenticaUserInputHistory.Contents>;
+}
+
+export namespace AgenticaUserInputHistory {
+  export type Contents = Contents.File | Contents.Image | Contents.InputAudio | Contents.Text;
+  export namespace Contents {
+    interface ContentsBase<Type extends string> {
+      /**
+       * The type of the content part.
+       */
+      type: Type;
+    }
+    /**
+     * Learn about
+     * [text inputs](https://platform.openai.com/docs/guides/text-generation).
+     */
+    export interface Text extends ContentsBase<"text"> {
+      /**
+       * The text content.
+       */
+      text: string;
+    }
+
+    /**
+     * Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
+     */
+    export interface Image extends ContentsBase<"image_url"> {
+      image_url: {
+        /**
+         * Either a URL of the image or the base64 encoded image data.
+         */
+        url: string;
+        /**
+         * Specifies the detail level of the image. Learn more in the
+         * [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
+         */
+        detail?: "auto" | "high" | "low";
+      };
+    }
+
+    /**
+     * Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
+     */
+    export interface InputAudio extends ContentsBase<"input_audio"> {
+      input_audio: {
+        /**
+         * Base64 encoded audio data.
+         */
+        data: string;
+
+        /**
+         * The format of the encoded audio data. Currently supports "wav" and "mp3".
+         */
+        format: "wav" | "mp3";
+      };
+    }
+
+    /**
+     * Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text
+     * generation.
+     */
+    export interface File extends ContentsBase<"file"> {
+      file: {
+        /**
+         * The base64 encoded file data, used when passing the file to the model as a
+         * string.
+         */
+        file_data?: string;
+
+        /**
+         * The ID of an uploaded file to use as input.
+         */
+        file_id?: string;
+
+        /**
+         * The name of the file, used when passing the file to the model as a string.
+         */
+        filename?: string;
+      };
+    }
+  }
+}