@agentica/core 0.24.0 → 0.26.0

package/src/factory/events.ts

@@ -5,6 +5,7 @@ import { v4 } from "uuid";
 
 import type { AgenticaOperation } from "../context/AgenticaOperation";
 import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import type { AgenticaAssistantMessageEvent } from "../events/AgenticaAssistantMessageEvent";
 import type { AgenticaCallEvent } from "../events/AgenticaCallEvent";
 import type { AgenticaCancelEvent } from "../events/AgenticaCancelEvent";
 import type { AgenticaDescribeEvent } from "../events/AgenticaDescribeEvent";
@@ -14,14 +15,13 @@ import type { AgenticaInitializeEvent } from "../events/AgenticaInitializeEvent"
 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 { AgenticaUserMessageEvent } from "../events/AgenticaUserMessageEvent";
 import type { AgenticaValidateEvent } from "../events/AgenticaValidateEvent";
+import type { AgenticaUserMessageContent } from "../histories";
 import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
-import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
 
-import { createExecuteHistory, createSelectHistory, createUserInputHistory } from "./histories";
+import { createExecuteHistory, createSelectHistory, createUserMessageHistory } from "./histories";
 
 /* -----------------------------------------------------------
   FUNCTION SELECTS
@@ -36,23 +36,6 @@ 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> {
@@ -151,32 +134,44 @@ export function createExecuteEvent<Model extends ILlmSchema.Model>(props: {
 }
 
 /* -----------------------------------------------------------
-  TEXT STEAMING
+  CONTENTS
 ----------------------------------------------------------- */
-export function createTextEvent(props: {
+export function createUserMessageEvent(props: {
+  contents: Array<AgenticaUserMessageContent>;
+}): AgenticaUserMessageEvent {
+  return {
+    type: "userMessage",
+    contents: props.contents,
+    toJSON: () => ({
+      type: "userMessage",
+      contents: props.contents,
+    }),
+    toHistory: () => createUserMessageHistory({
+      contents: props.contents,
+    }),
+  };
+}
+
+export function creatAssistantEvent(props: {
   stream: AsyncGenerator<string, undefined, undefined>;
   done: () => boolean;
   get: () => string;
   join: () => Promise<string>;
-}): AgenticaTextEvent {
+}): AgenticaAssistantMessageEvent {
   return {
-    type: "text",
-    role: "assistant",
+    type: "assistantMessage",
     stream: props.stream,
     join: props.join,
     toJSON: () => ({
-      type: "text",
-      role: "assistant",
+      type: "assistantMessage",
       done: props.done(),
       text: props.get(),
     }),
     toHistory: () => ({
-      type: "text",
-      role: "assistant",
+      type: "assistantMessage",
       text: props.get(),
       toJSON: () => ({
-        type: "text",
-        role: "assistant",
+        type: "assistantMessage",
         text: props.get(),
       }),
     }),
@@ -215,8 +210,8 @@ export function createDescribeEvent<Model extends ILlmSchema.Model>(props: {
 }
 
 /* -----------------------------------------------------------
-    API REQUESTS
-  ----------------------------------------------------------- */
+  API REQUESTS
+----------------------------------------------------------- */
 export function createRequestEvent(props: {
   source: AgenticaEventSource;
   body: OpenAI.ChatCompletionCreateParamsStreaming;

package/src/factory/histories.ts

@@ -3,31 +3,26 @@ import type OpenAI from "openai";
 
 import type { AgenticaOperation } from "../context/AgenticaOperation";
 import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import type { AgenticaUserMessageContent } from "../histories";
+import type { AgenticaAssistantMessageHistory } from "../histories/AgenticaAssistantMessageHistory";
 import type { AgenticaCancelHistory } from "../histories/AgenticaCancelHistory";
 import type { AgenticaDescribeHistory } from "../histories/AgenticaDescribeHistory";
 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 { AgenticaSystemMessageHistory } from "../histories/AgenticaSystemMessageHistory";
+import type { AgenticaUserMessageHistory } from "../histories/AgenticaUserMessageHistory";
 import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
 
+/**
+ * @internal
+ */
 export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaHistory<Model>): OpenAI.ChatCompletionMessageParam[] {
   // NO NEED TO DECODE DESCRIBE
   if (history.type === "describe") {
     return [];
   }
-
-  if (history.type === "text") {
-    return [
-      {
-        role: history.role,
-        content: history.text,
-      },
-    ];
-  }
-
-  if (history.type === "select" || history.type === "cancel") {
+  else if (history.type === "select" || history.type === "cancel") {
     return [
       {
         role: "assistant",
@@ -54,8 +49,7 @@ export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaH
       },
     ];
   }
-
-  if (history.type === "execute") {
+  else if (history.type === "execute") {
     return [
       {
         role: "assistant",
@@ -99,31 +93,98 @@ export function decodeHistory<Model extends ILlmSchema.Model>(history: AgenticaH
     ];
   }
 
-  if (history.type === "user_input") {
+  if (history.type === "assistantMessage") {
+    return [
+      {
+        role: "assistant",
+        content: history.text,
+      },
+    ];
+  }
+
+  if (history.type === "systemMessage") {
+    return [
+      {
+        role: "system",
+        content: history.text,
+      },
+    ];
+  }
+
+  if (history.type === "userMessage") {
+    const contents = history.contents;
     return [
       {
         role: "user",
-        content: history.contents,
+        content: contents.map(decodeUserMessageContent),
       },
     ];
   }
 
   history satisfies never;
-  throw new Error("Invalid history type");
+  throw new Error(`Unsupported history type, value: ${JSON.stringify(history)}`);
+}
+
+/**
+ * @internal
+ */
+export function decodeUserMessageContent(content: AgenticaUserMessageContent): OpenAI.ChatCompletionContentPart {
+  if (content.type === "text") {
+    return content;
+  }
+
+  if (content.type === "audio") {
+    return {
+      type: "input_audio",
+      input_audio: {
+        data: content.data,
+        format: content.format,
+      },
+    };
+  }
+
+  if (content.type === "file") {
+    return {
+      type: "file",
+      file: content.file.type === "data"
+        ? {
+            file_data: content.file.data,
+            filename: content.file.name,
+          }
+        : {
+            file_id: content.file.id,
+          },
+    };
+  }
+
+  if (content.type === "image") {
+    return {
+      type: "image_url",
+      image_url: {
+        url: content.url,
+        detail: content.detail,
+      },
+    };
+  }
+
+  content satisfies never;
+  throw new Error(`Unsupported user message content type, value: ${JSON.stringify(content)}`);
 }
 
 /* -----------------------------------------------------------
   USER INPUT PROMPTS
 ----------------------------------------------------------- */
-export function createUserInputHistory(props: {
-  contents: Array<AgenticaUserInputHistory.Contents>;
-}): AgenticaUserInputHistory {
+/**
+ * @internal
+ */
+export function createUserMessageHistory(props: {
+  contents: Array<AgenticaUserMessageContent>;
+}): AgenticaUserMessageHistory {
   return {
-    type: "user_input",
-    role: "user",
+    type: "userMessage",
     contents: props.contents,
     toJSON: () => ({
-      type: "user_input",
+      type: "userMessage",
       contents: props.contents,
     }),
   };
@@ -132,12 +193,30 @@ export function createUserInputHistory(props: {
 /* -----------------------------------------------------------
   TEXT PROMPTS
 ----------------------------------------------------------- */
-export function createTextHistory(props: {
+/**
+ * @internal
+ */
+export function createAssistantMessageHistory(props: {
+  text: string;
+}): AgenticaAssistantMessageHistory {
+  const prompt: IAgenticaHistoryJson.IAssistantMessage = {
+    type: "assistantMessage",
+    text: props.text,
+  };
+  return {
+    ...prompt,
+    toJSON: () => prompt,
+  };
+}
+
+/**
+ * @internal
+ */
+export function createSystemMessageHistory(props: {
   text: string;
-}): AgenticaTextHistory {
-  const prompt: IAgenticaHistoryJson.IText = {
-    type: "text",
-    role: "assistant",
+}): AgenticaSystemMessageHistory {
+  const prompt: IAgenticaHistoryJson.ISystemMessage = {
+    type: "systemMessage",
     text: props.text,
   };
   return {
@@ -146,6 +225,9 @@ export function createTextHistory(props: {
   };
 }
 
+/**
+ * @internal
+ */
 export function createDescribeHistory<Model extends ILlmSchema.Model>(props: {
   executes: AgenticaExecuteHistory<Model>[];
   text: string;
@@ -165,6 +247,9 @@ export function createDescribeHistory<Model extends ILlmSchema.Model>(props: {
 /* -----------------------------------------------------------
   FUNCTION CALLING PROMPTS
 ----------------------------------------------------------- */
+/**
+ * @internal
+ */
 export function createSelectHistory<Model extends ILlmSchema.Model>(props: {
   id: string;
   selections: AgenticaOperationSelection<Model>[];
@@ -181,6 +266,9 @@ export function createSelectHistory<Model extends ILlmSchema.Model>(props: {
   };
 }
 
+/**
+ * @internal
+ */
 export function createCancelHistory<Model extends ILlmSchema.Model>(props: {
   id: string;
   selections: AgenticaOperationSelection<Model>[];
@@ -197,6 +285,9 @@ export function createCancelHistory<Model extends ILlmSchema.Model>(props: {
   };
 }
 
+/**
+ * @internal
+ */
 export function createExecuteHistory<
   Model extends ILlmSchema.Model,
 >(props: {

package/src/functional/assertMcpController.ts

@@ -1,4 +1,3 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
 import type { ILlmSchema, IMcpLlmApplication, IMcpTool } from "@samchon/openapi";
 
 import { McpLlm } from "@samchon/openapi";
@@ -23,8 +22,11 @@ import type { IAgenticaController } from "../structures/IAgenticaController";
  */
 export async function assertMcpController<Model extends ILlmSchema.Model>(props: {
   name: string;
-  client: Client;
   model: Model;
+  // @ts-ignore Type checking only when `@modelcontextprotocol/sdk` is installed.
+  //            This strategy is useful for someone who does not need MCP,
+  //            for someone who has not installed `@modelcontextprotocol/sdk`.
+  client: import("@modelcontextprotocol/sdk/client/index.d.ts").Client;
   options?: Partial<IMcpLlmApplication.IOptions<Model>>;
 }): Promise<IAgenticaController.IMcp<Model>> {
   // for peerDependencies

package/src/functional/index.ts

@@ -0,0 +1,7 @@
+export * from "./assertHttpController";
+export * from "./assertHttpLlmApplication"; // deprecated
+export * from "./assertMcpController";
+export * from "./validateHttpController"; // deprecated
+
+export * from "./validateHttpLlmApplication";
+export * from "./validateMcpController";

package/src/functional/validateMcpController.ts

@@ -1,4 +1,3 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
 import type { ILlmSchema, IMcpLlmApplication, IMcpTool, IValidation } from "@samchon/openapi";
 
 import { McpLlm } from "@samchon/openapi";
@@ -25,7 +24,10 @@ export async function validateMcpController<
   Model extends ILlmSchema.Model,
 >(props: {
   name: string;
-  client: Client;
+  // @ts-ignore Type checking only when `@modelcontextprotocol/sdk` is installed.
+  //            This strategy is useful for someone who does not need MCP,
+  //            for someone who has not installed `@modelcontextprotocol/sdk`.
+  client: import("@modelcontextprotocol/sdk/client/index.d.ts").Client;
   model: Model;
   options?: Partial<IMcpLlmApplication.IOptions<Model>>;
 }): Promise<IValidation<IAgenticaController.IMcp<Model>>> {

package/src/histories/AgenticaAssistantMessageHistory.ts

@@ -0,0 +1,10 @@
+import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
+
+import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
+
+export interface AgenticaAssistantMessageHistory extends AgenticaHistoryBase<
+  "assistantMessage",
+  IAgenticaHistoryJson.IAssistantMessage
+> {
+  text: string;
+}

package/src/histories/AgenticaHistory.ts

@@ -1,27 +1,30 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
+import type { AgenticaAssistantMessageHistory } from "./AgenticaAssistantMessageHistory";
 import type { AgenticaCancelHistory } from "./AgenticaCancelHistory";
 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";
+import type { AgenticaSystemMessageHistory } from "./AgenticaSystemMessageHistory";
+import type { AgenticaUserMessageHistory } from "./AgenticaUserMessageHistory";
 
 export type AgenticaHistory<Model extends ILlmSchema.Model> =
   | AgenticaCancelHistory<Model>
   | AgenticaDescribeHistory<Model>
   | AgenticaExecuteHistory<Model>
   | AgenticaSelectHistory<Model>
-  | AgenticaTextHistory
-  | AgenticaUserInputHistory;
+  | AgenticaAssistantMessageHistory
+  | AgenticaUserMessageHistory
+  | AgenticaSystemMessageHistory;
 export namespace AgenticaHistory {
   export type Type = AgenticaHistory<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
+    select: AgenticaSelectHistory<Model>;
     cancel: AgenticaCancelHistory<Model>;
-    describe: AgenticaDescribeHistory<Model>;
     execute: AgenticaExecuteHistory<Model>;
-    select: AgenticaSelectHistory<Model>;
-    text: AgenticaTextHistory;
-    user_input: AgenticaUserInputHistory;
+    describe: AgenticaDescribeHistory<Model>;
+    assistantMessage: AgenticaAssistantMessageHistory;
+    systemMessage: AgenticaSystemMessageHistory;
+    userMessage: AgenticaUserMessageHistory;
   }
 }

package/src/histories/{AgenticaTextHistory.ts → AgenticaSystemMessageHistory.ts}

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

package/src/histories/AgenticaUserMessageHistory.ts

@@ -0,0 +1,11 @@
+import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
+
+import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
+import type { AgenticaUserMessageContent } from "./contents/AgenticaUserMessageContent";
+
+export interface AgenticaUserMessageHistory extends AgenticaHistoryBase<
+  "userMessage",
+  IAgenticaHistoryJson.IUserMessage
+> {
+  contents: AgenticaUserMessageContent[];
+}

package/src/histories/MicroAgenticaHistory.ts

@@ -1,20 +1,21 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
+import type { AgenticaAssistantMessageHistory } from "./AgenticaAssistantMessageHistory";
 import type { AgenticaDescribeHistory } from "./AgenticaDescribeHistory";
 import type { AgenticaExecuteHistory } from "./AgenticaExecuteHistory";
-import type { AgenticaTextHistory } from "./AgenticaTextHistory";
-import type { AgenticaUserInputHistory } from "./AgenticaUserInputHistory";
+import type { AgenticaUserMessageHistory } from "./AgenticaUserMessageHistory";
 
 export type MicroAgenticaHistory<Model extends ILlmSchema.Model> =
   | AgenticaDescribeHistory<Model>
   | AgenticaExecuteHistory<Model>
-  | AgenticaTextHistory
-  | AgenticaUserInputHistory;
+  | AgenticaAssistantMessageHistory
+  | AgenticaUserMessageHistory;
 export namespace MicroAgenticaHistory {
   export type Type = MicroAgenticaHistory<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
     describe: AgenticaDescribeHistory<Model>;
     execute: AgenticaExecuteHistory<Model>;
-    text: AgenticaTextHistory;
+    userMessage: AgenticaUserMessageHistory;
+    assistantMessage: AgenticaAssistantMessageHistory;
   }
 }

package/src/histories/contents/AgenticaUserMessageAudioContent.ts

@@ -0,0 +1,21 @@
+import type { AgenticaUserMessageContentBase } from "./AgenticaUserMessageContentBase";
+
+/**
+ * Audio content by user.
+ *
+ * @reference https://platform.openai.com/docs/guides/audio
+ * @warning We not recommend it because audio data only support base64
+ *          so it's too big data
+ * @author SunRabbit
+ */
+export interface AgenticaUserMessageAudioContent extends AgenticaUserMessageContentBase<"audio"> {
+  /**
+   * Base64 encoded audio data.
+   */
+  data: string;
+
+  /**
+   * The format of the encoded audio data. Currently supports "wav" and "mp3".
+   */
+  format: "wav" | "mp3";
+}

package/src/histories/contents/AgenticaUserMessageContent.ts

@@ -0,0 +1,19 @@
+import type { AgenticaUserMessageAudioContent } from "./AgenticaUserMessageAudioContent";
+import type { AgenticaUserMessageFileContent } from "./AgenticaUserMessageFileContent";
+import type { AgenticaUserMessageImageContent } from "./AgenticaUserMessageImageContent";
+import type { AgenticaUserMessageTextContent } from "./AgenticaUserMessageTextContent";
+
+export type AgenticaUserMessageContent =
+  | AgenticaUserMessageAudioContent
+  | AgenticaUserMessageFileContent
+  | AgenticaUserMessageImageContent
+  | AgenticaUserMessageTextContent;
+export namespace AgenticaUserMessageContent {
+  export type Type = AgenticaUserMessageContent["type"];
+  export interface Mapper {
+    audio: AgenticaUserMessageAudioContent;
+    file: AgenticaUserMessageFileContent;
+    image: AgenticaUserMessageImageContent;
+    text: AgenticaUserMessageTextContent;
+  }
+}

package/src/histories/contents/AgenticaUserMessageContentBase.ts

@@ -0,0 +1,6 @@
+export interface AgenticaUserMessageContentBase<Type extends string> {
+  /**
+   * Discriminator for the type of content.
+   */
+  type: Type;
+}

package/src/histories/contents/AgenticaUserMessageFileContent.ts

@@ -0,0 +1,27 @@
+import type { AgenticaUserMessageContentBase } from "./AgenticaUserMessageContentBase";
+
+/**
+ * File content by user.
+ *
+ * @reference https://platform.openai.com/docs/api-reference/uploads/create
+ * @author SunRabbit
+ */
+export interface AgenticaUserMessageFileContent extends AgenticaUserMessageContentBase<"file"> {
+  /**
+   * Reference to the pre-uploaded file or the data itself.
+   *
+   * @todo Properly define independent interface
+   */
+  file: AgenticaUserMessageFileContent.IReference | AgenticaUserMessageFileContent.IData;
+}
+export namespace AgenticaUserMessageFileContent {
+  export interface IReference {
+    type: "reference";
+    id: string;
+  }
+  export interface IData {
+    type: "data";
+    name: string;
+    data: string;
+  }
+}

package/src/histories/contents/AgenticaUserMessageImageContent.ts

@@ -0,0 +1,23 @@
+import type { tags } from "typia";
+
+import type { AgenticaUserMessageContentBase } from "./AgenticaUserMessageContentBase";
+
+/**
+ * Image content by user.
+ *
+ * @reference https://platform.openai.com/docs/guides/vision
+ * @author SunRabbit
+ */
+export interface AgenticaUserMessageImageContent extends AgenticaUserMessageContentBase<"image"> {
+  /**
+   * Image URL.
+   */
+  url: string & tags.Format<"url">;
+
+  /**
+   * Specifies the detail level of the image.
+   *
+   * @reference https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding
+   */
+  detail?: "auto" | "high" | "low" | undefined;
+}

package/src/histories/contents/AgenticaUserMessageTextContent.ts

@@ -0,0 +1,15 @@
+import type { AgenticaUserMessageContentBase } from "./AgenticaUserMessageContentBase";
+
+/**
+ * Text content by user.
+ *
+ * @reference https://platform.openai.com/docs/guides/text-generation
+ * @author Samchon
+ * @author SunRabbit
+ */
+export interface AgenticaUserMessageTextContent extends AgenticaUserMessageContentBase<"text"> {
+  /**
+   * The text content.
+   */
+  text: string;
+}

package/src/histories/contents/index.ts

@@ -0,0 +1,5 @@
+export * from "./AgenticaUserMessageAudioContent";
+export * from "./AgenticaUserMessageContent";
+export * from "./AgenticaUserMessageFileContent";
+export * from "./AgenticaUserMessageImageContent";
+export * from "./AgenticaUserMessageTextContent";

package/src/histories/index.ts

@@ -0,0 +1,10 @@
+export * from "./AgenticaAssistantMessageHistory";
+export * from "./AgenticaCancelHistory";
+export * from "./AgenticaDescribeHistory";
+export * from "./AgenticaExecuteHistory";
+export * from "./AgenticaHistory";
+export * from "./AgenticaSelectHistory";
+export * from "./AgenticaSystemMessageHistory";
+export * from "./AgenticaUserMessageHistory";
+export * from "./contents";
+export * from "./MicroAgenticaHistory";