@agentica/core 0.20.0 → 0.22.0

package/src/context/internal/AgenticaOperationComposer.ts

@@ -22,7 +22,7 @@ export function compose<Model extends ILlmSchema.Model>(props: {
 }): AgenticaOperationCollection<Model> {
   const unique: boolean = (props.controllers.length === 1 || (() => {
     const names = props.controllers.map(
-      // eslint-disable-next-line ts/no-unsafe-return, ts/no-unsafe-call, ts/no-unsafe-member-access
+
       controllers => controllers.application.functions.map((func: { name: string }) => func.name),
     ).flat();
     return new Set(names).size === names.length;
@@ -133,20 +133,19 @@ export function toMcpOperations<Model extends ILlmSchema.Model>(props: {
   index: number;
   naming: (func: string, controllerIndex: number) => string;
 }): AgenticaOperation<Model>[] {
-  // eslint-disable-next-line ts/no-unsafe-call, ts/no-unsafe-member-access, ts/no-unsafe-return
   return props.controller.application.functions.map(func => ({
     protocol: "mcp",
     controller: props.controller,
-    // eslint-disable-next-line ts/no-unsafe-assignment
+
     function: func,
-    // eslint-disable-next-line ts/no-unsafe-argument, ts/no-unsafe-member-access
+
     name: props.naming(func.name, props.index),
     toJSON: () => ({
       protocol: "mcp",
       controller: props.controller.name,
-      // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
+
       function: func.name,
-      // eslint-disable-next-line ts/no-unsafe-argument, ts/no-unsafe-member-access
+
       name: props.naming(func.name, props.index),
     }),
   }));

package/src/events/AgenticaEvent.ts

@@ -9,6 +9,7 @@ import type { AgenticaRequestEvent } from "./AgenticaRequestEvent";
 import type { AgenticaResponseEvent } from "./AgenticaResponseEvent";
 import type { AgenticaSelectEvent } from "./AgenticaSelectEvent";
 import type { AgenticaTextEvent } from "./AgenticaTextEvent";
+import type { AgenticaUserInputEvent } from "./AgenticaUserInputEvent";
 import type { AgenticaValidateEvent } from "./AgenticaValidateEvent";
 
 /**
@@ -31,7 +32,8 @@ export type AgenticaEvent<Model extends ILlmSchema.Model> =
   | AgenticaResponseEvent
   | AgenticaSelectEvent<Model>
   | AgenticaTextEvent
-  | AgenticaValidateEvent<Model>;
+  | AgenticaValidateEvent<Model>
+  | AgenticaUserInputEvent;
 export namespace AgenticaEvent {
   export type Type = AgenticaEvent<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
@@ -45,6 +47,7 @@ export namespace AgenticaEvent {
     select: AgenticaSelectEvent<Model>;
     text: AgenticaTextEvent;
     validate: AgenticaValidateEvent<Model>;
+    user_input: AgenticaUserInputEvent;
   }
   export type Source =
     | "initialize"

package/src/events/AgenticaTextEvent.ts

@@ -3,10 +3,8 @@ import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
 
 import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export interface AgenticaTextEvent<
-  Role extends "assistant" | "user" = "assistant" | "user",
-> extends AgenticaEventBase<"text"> {
-  role: Role;
+export interface AgenticaTextEvent extends AgenticaEventBase<"text"> {
+  role: "assistant";
   stream: AsyncGenerator<string, undefined, undefined>;
   join: () => Promise<string>;
   toJSON: () => IAgenticaEventJson.IText;

package/src/events/AgenticaUserInputEvent.ts

@@ -0,0 +1,12 @@
+import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+
+export interface AgenticaUserInputEvent extends AgenticaEventBase<"user_input"> {
+  role: "user";
+  contents: Array<AgenticaUserInputHistory.Contents>;
+  join: () => Promise<Array<AgenticaUserInputHistory.Contents>>;
+  toJSON: () => IAgenticaEventJson.IUserInput;
+  toHistory: () => AgenticaUserInputHistory;
+}

package/src/events/MicroAgenticaEvent.ts

@@ -6,6 +6,7 @@ import type { AgenticaExecuteEvent } from "./AgenticaExecuteEvent";
 import type { AgenticaRequestEvent } from "./AgenticaRequestEvent";
 import type { AgenticaResponseEvent } from "./AgenticaResponseEvent";
 import type { AgenticaTextEvent } from "./AgenticaTextEvent";
+import type { AgenticaUserInputEvent } from "./AgenticaUserInputEvent";
 import type { AgenticaValidateEvent } from "./AgenticaValidateEvent";
 
 /**
@@ -25,7 +26,8 @@ export type MicroAgenticaEvent<Model extends ILlmSchema.Model> =
   | AgenticaRequestEvent
   | AgenticaResponseEvent
   | AgenticaTextEvent
-  | AgenticaValidateEvent<Model>;
+  | AgenticaValidateEvent<Model>
+  | AgenticaUserInputEvent;
 export namespace MicroAgenticaEvent {
   export type Type = MicroAgenticaEvent<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
@@ -36,6 +38,7 @@ export namespace MicroAgenticaEvent {
     response: AgenticaResponseEvent;
     text: AgenticaTextEvent;
     validate: AgenticaValidateEvent<Model>;
+    user_input: AgenticaUserInputEvent;
   }
   export type Source = "call" | "describe";
 }

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/assertMcpController.ts

@@ -33,7 +33,6 @@ export async function assertMcpController<Model extends ILlmSchema.Model>(props:
   // get list of tools
   const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
 
-  // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-call, ts/no-unsafe-member-access
   const application: IMcpLlmApplication<Model> = McpLlm.application<Model>({
     model: props.model,
     tools: typia.assert<Array<IMcpTool>>(tools),
@@ -43,7 +42,7 @@ export async function assertMcpController<Model extends ILlmSchema.Model>(props:
     protocol: "mcp",
     name: props.name,
     client: props.client,
-    // eslint-disable-next-line ts/no-unsafe-assignment
+
     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;
+      };
+    }
+  }
+}

package/src/histories/MicroAgenticaHistory.ts

@@ -3,11 +3,13 @@ import type { ILlmSchema } from "@samchon/openapi";
 import type { AgenticaDescribeHistory } from "./AgenticaDescribeHistory";
 import type { AgenticaExecuteHistory } from "./AgenticaExecuteHistory";
 import type { AgenticaTextHistory } from "./AgenticaTextHistory";
+import type { AgenticaUserInputHistory } from "./AgenticaUserInputHistory";
 
 export type MicroAgenticaHistory<Model extends ILlmSchema.Model> =
   | AgenticaDescribeHistory<Model>
   | AgenticaExecuteHistory<Model>
-  | AgenticaTextHistory;
+  | AgenticaTextHistory
+  | AgenticaUserInputHistory;
 export namespace MicroAgenticaHistory {
   export type Type = MicroAgenticaHistory<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {

package/src/json/IAgenticaEventJson.ts

@@ -1,6 +1,7 @@
 import type OpenAI from "openai";
 
 import type { AgenticaEventSource } from "../events/AgenticaEventSource";
+import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
 
 import type { IAgenticaHistoryJson } from "./IAgenticaHistoryJson";
 import type { IAgenticaOperationJson } from "./IAgenticaOperationJson";
@@ -39,6 +40,13 @@ export namespace IAgenticaEventJson {
     request: IRequest;
   }
 
+  /**
+   * Event of user input.
+   */
+  export interface IUserInput extends IBase<"user_input"> {
+    contents: Array<AgenticaUserInputHistory.Contents>;
+  }
+
   /**
    * Event of initializing the chatbot.
    */
@@ -140,7 +148,7 @@ export namespace IAgenticaEventJson {
     /**
      * Role of the orator.
      */
-    role: "assistant" | "user";
+    role: "assistant";
 
     /**
      * Conversation text.

package/src/json/IAgenticaHistoryJson.ts

@@ -1,3 +1,5 @@
+import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
+
 import type { IAgenticaOperationJson } from "./IAgenticaOperationJson";
 import type { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelectionJson";
 
@@ -18,12 +20,24 @@ import type { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelect
  * @author Samchon
  */
 export type IAgenticaHistoryJson =
+  | IAgenticaHistoryJson.IUserInput
   | IAgenticaHistoryJson.IText
   | IAgenticaHistoryJson.ISelect
   | IAgenticaHistoryJson.ICancel
   | IAgenticaHistoryJson.IExecute
   | IAgenticaHistoryJson.IDescribe;
 export namespace IAgenticaHistoryJson {
+  /**
+   * User input prompt.
+   *
+   * User input prompt about the user's input.
+   */
+  export interface IUserInput extends IBase<"user_input"> {
+    /**
+     * User input.
+     */
+    contents: Array<AgenticaUserInputHistory.Contents>;
+  }
   /**
    * Select prompt.
    *
@@ -107,13 +121,11 @@ export namespace IAgenticaHistoryJson {
   /**
    * Text prompt.
    */
-  export interface IText<
-    Role extends "assistant" | "user" = "assistant" | "user",
-  > extends IBase<"text"> {
+  export interface IText extends IBase<"text"> {
     /**
      * Role of the orator.
      */
-    role: Role;
+    role: "assistant";
 
     /**
      * The text content.