@agentica/core 0.21.0 → 0.22.0

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

package/src/orchestrate/call.ts

@@ -54,7 +54,7 @@ export async function call<Model extends ILlmSchema.Model>(
       // USER INPUT
       {
         role: "user",
-        content: ctx.prompt.text,
+        content: ctx.prompt.contents,
       },
       // SYSTEM PROMPT
       ...(ctx.config?.systemPrompt?.execute === null
@@ -181,13 +181,11 @@ export async function call<Model extends ILlmSchema.Model>(
       && choice.message.content.length !== 0
     ) {
       closures.push(async () => {
-        const value: AgenticaTextHistory = createTextHistory({
-          role: "assistant",
-          text: choice.message.content!,
-        });
+        const value: AgenticaTextHistory = createTextHistory(
+          { text: choice.message.content! },
+        );
         ctx.dispatch(
           createTextEvent({
-            role: "assistant",
             get: () => value.text,
             done: () => true,
             stream: toAsyncGenerator(value.text),
@@ -473,7 +471,7 @@ async function correct<Model extends ILlmSchema.Model>(
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.text,
+          content: ctx.prompt.contents,
         },
         // TYPE CORRECTION
         ...(ctx.config?.systemPrompt?.execute === null

package/src/orchestrate/cancel.ts

@@ -141,7 +141,7 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.text,
+          content: ctx.prompt.contents,
         },
         // SYSTEM PROMPT
         {

package/src/orchestrate/initialize.ts

@@ -36,7 +36,7 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.text,
+          content: ctx.prompt.contents,
         },
         {
           // SYSTEM PROMPT
@@ -108,7 +108,6 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
 
         ctx.dispatch(
           createTextEvent({
-            role: "assistant",
             stream: streamDefaultReaderToAsyncGenerator(mpsc.consumer.getReader()),
             done: () => mpsc.done(),
             get: () => textContext[choice.index]!.content,
@@ -145,10 +144,7 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
       && choice.message.content.length !== 0
     ) {
       prompts.push(
-        createTextHistory({
-          role: "assistant",
-          text: choice.message.content,
-        }),
+        createTextHistory({ text: choice.message.content }),
       );
     }
   }

package/src/orchestrate/select.ts

@@ -13,7 +13,6 @@ import type { __IChatSelectFunctionsApplication } from "../context/internal/__IC
 import type { AgenticaEvent } from "../events/AgenticaEvent";
 import type { AgenticaHistory } from "../histories/AgenticaHistory";
 import type { AgenticaSelectHistory } from "../histories/AgenticaSelectHistory";
-import type { AgenticaTextHistory } from "../histories/AgenticaTextHistory";
 
 import { AgenticaConstant } from "../constants/AgenticaConstant";
 import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
@@ -145,7 +144,7 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.text,
+          content: ctx.prompt.contents,
         },
         // SYSTEM PROMPT
         {
@@ -260,15 +259,11 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
       && choice.message.content != null
       && choice.message.content.length !== 0
     ) {
-      const text: AgenticaTextHistory = createTextHistory({
-        role: "assistant",
-        text: choice.message.content,
-      });
+      const text = createTextHistory({ text: choice.message.content });
       prompts.push(text);
 
       ctx.dispatch(
         createTextEvent({
-          role: "assistant",
           stream: toAsyncGenerator(text.text),
           join: async () => Promise.resolve(text.text),
           done: () => true,

package/src/transformers/AgenticaEventTransformer.ts

@@ -175,7 +175,6 @@ function transformText(props: {
   event: IAgenticaEventJson.IText;
 }): AgenticaTextEvent {
   return createTextEvent({
-    role: props.event.role,
     stream: toAsyncGenerator(props.event.text),
     done: () => true,
     get: () => props.event.text,