@agentica/core 0.24.0 → 0.25.0

package/src/json/IAgenticaEventJson.ts

@@ -1,7 +1,8 @@
 import type OpenAI from "openai";
+import type { IValidation } from "typia";
 
 import type { AgenticaEventSource } from "../events/AgenticaEventSource";
-import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
+import type { AgenticaUserMessageContent } from "../histories";
 
 import type { IAgenticaHistoryJson } from "./IAgenticaHistoryJson";
 import type { IAgenticaOperationJson } from "./IAgenticaOperationJson";
@@ -25,26 +26,38 @@ export type IAgenticaEventJson =
   | IAgenticaEventJson.IInitialize
   | IAgenticaEventJson.IRequest
   | IAgenticaEventJson.ISelect
-  | IAgenticaEventJson.IText
-  | IAgenticaEventJson.IValidate;
+  | IAgenticaEventJson.IValidate
+  | IAgenticaEventJson.IAssistantMessage
+  | IAgenticaEventJson.IUserMessage;
 export namespace IAgenticaEventJson {
   export type Type = IAgenticaEventJson["type"];
   export interface Mapper {
+    userMessage: IUserMessage;
+    assistantMessage: IAssistantMessage;
     initialize: IInitialize;
     select: ISelect;
     cancel: ICancel;
     call: ICall;
     execute: IExecute;
     describe: IDescribe;
-    text: IText;
     request: IRequest;
   }
 
   /**
-   * Event of user input.
+   * Event of assistant message.
    */
-  export interface IUserInput extends IBase<"user_input"> {
-    contents: Array<AgenticaUserInputHistory.Contents>;
+  export interface IAssistantMessage extends IBase<"assistantMessage"> {
+    /**
+     * Conversation text.
+     */
+    text: string;
+  }
+
+  /**
+   * Event of user message.
+   */
+  export interface IUserMessage extends IBase<"userMessage"> {
+    contents: Array<AgenticaUserMessageContent>;
   }
 
   /**
@@ -90,7 +103,22 @@ export namespace IAgenticaEventJson {
     arguments: Record<string, any>;
   }
 
-  export interface IValidate extends IBase<"validate"> {}
+  export interface IValidate extends IBase<"validate"> {
+    /**
+     * ID of the tool calling.
+     */
+    id: string;
+
+    /**
+     * Target operation to call.
+     */
+    operation: IAgenticaOperationJson;
+
+    /**
+     * Validation result as a failure.
+     */
+    result: IValidation.IFailure;
+  }
 
   /**
    * Event of function calling execution.
@@ -141,26 +169,6 @@ export namespace IAgenticaEventJson {
     done: boolean;
   }
 
-  /**
-   * Event of text message.
-   */
-  export interface IText extends IBase<"text"> {
-    /**
-     * Role of the orator.
-     */
-    role: "assistant";
-
-    /**
-     * Conversation text.
-     */
-    text: string;
-
-    /**
-     * Whether the streaming is completed or not.
-     */
-    done: boolean;
-  }
-
   /**
    * Request event of LLM vendor API.
    */

package/src/json/IAgenticaHistoryJson.ts

@@ -1,4 +1,4 @@
-import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
+import type { AgenticaUserMessageContent } from "../histories";
 
 import type { IAgenticaOperationJson } from "./IAgenticaOperationJson";
 import type { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelectionJson";
@@ -20,24 +20,45 @@ import type { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelect
  * @author Samchon
  */
 export type IAgenticaHistoryJson =
-  | IAgenticaHistoryJson.IUserInput
-  | IAgenticaHistoryJson.IText
+  | IAgenticaHistoryJson.IUserMessage
+  | IAgenticaHistoryJson.IAssistantMessage
   | IAgenticaHistoryJson.ISelect
   | IAgenticaHistoryJson.ICancel
   | IAgenticaHistoryJson.IExecute
   | IAgenticaHistoryJson.IDescribe;
 export namespace IAgenticaHistoryJson {
+  export type Type = IAgenticaHistoryJson["type"];
+  export interface Mapper {
+    userMessage: IUserMessage;
+    assistantMessage: IAssistantMessage;
+    select: ISelect;
+    cancel: ICancel;
+    execute: IExecute;
+    describe: IDescribe;
+  }
+
   /**
-   * User input prompt.
+   * User prompt.
    *
-   * User input prompt about the user's input.
+   * User prompt about the user's input.
    */
-  export interface IUserInput extends IBase<"user_input"> {
+  export interface IUserMessage extends IBase<"userMessage"> {
     /**
      * User input.
      */
-    contents: Array<AgenticaUserInputHistory.Contents>;
+    contents: Array<AgenticaUserMessageContent>;
   }
+
+  /**
+   * Assistant prompt.
+   */
+  export interface IAssistantMessage extends IBase<"assistantMessage"> {
+    /**
+     * The text content.
+     */
+    text: string;
+  }
+
   /**
    * Select prompt.
    *
@@ -118,21 +139,6 @@ export namespace IAgenticaHistoryJson {
     text: string;
   }
 
-  /**
-   * Text prompt.
-   */
-  export interface IText extends IBase<"text"> {
-    /**
-     * Role of the orator.
-     */
-    role: "assistant";
-
-    /**
-     * The text content.
-     */
-    text: string;
-  }
-
   interface IBase<Type extends string> {
     /**
      * Discriminator type.

package/src/json/IMicroAgenticaEventJson.ts

@@ -12,10 +12,11 @@ import type { IAgenticaEventJson } from "./IAgenticaEventJson";
  * @author Samchon
  */
 export type IMicroAgenticaEventJson =
+  | IAgenticaEventJson.IUserMessage
+  | IAgenticaEventJson.IAssistantMessage
   | IAgenticaEventJson.ICall
   | IAgenticaEventJson.IDescribe
   | IAgenticaEventJson.IExecute
   | IAgenticaEventJson.IInitialize
   | IAgenticaEventJson.IRequest
-  | IAgenticaEventJson.IText
   | IAgenticaEventJson.IValidate;

package/src/json/IMicroAgenticaHistoryJson.ts

@@ -18,6 +18,7 @@ import type { IAgenticaHistoryJson } from "./IAgenticaHistoryJson";
  * @author Samchon
  */
 export type IMicroAgenticaHistoryJson =
-  | IAgenticaHistoryJson.IText
+  | IAgenticaHistoryJson.IUserMessage
+  | IAgenticaHistoryJson.IAssistantMessage
   | IAgenticaHistoryJson.IExecute
   | IAgenticaHistoryJson.IDescribe;

package/src/json/index.ts

@@ -0,0 +1,7 @@
+export * from "./IAgenticaEventJson";
+export * from "./IAgenticaHistoryJson";
+export * from "./IAgenticaOperationJson";
+export * from "./IAgenticaOperationSelectionJson";
+export * from "./IAgenticaTokenUsageJson";
+export * from "./IMicroAgenticaEventJson";
+export * from "./IMicroAgenticaHistoryJson";

package/src/orchestrate/call.ts

@@ -17,18 +17,18 @@ import type { AgenticaContext } from "../context/AgenticaContext";
 import type { AgenticaOperation } from "../context/AgenticaOperation";
 import type { MicroAgenticaContext } from "../context/MicroAgenticaContext";
 import type { AgenticaCallEvent } from "../events/AgenticaCallEvent";
+import type { AgenticaAssistantMessageHistory } from "../histories/AgenticaAssistantMessageHistory";
 import type { AgenticaCancelHistory } from "../histories/AgenticaCancelHistory";
 import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
 import type { AgenticaHistory } from "../histories/AgenticaHistory";
-import type { AgenticaTextHistory } from "../histories/AgenticaTextHistory";
 import type { MicroAgenticaHistory } from "../histories/MicroAgenticaHistory";
 
 import { AgenticaConstant } from "../constants/AgenticaConstant";
 import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
 import { AgenticaSystemPrompt } from "../constants/AgenticaSystemPrompt";
 import { isAgenticaContext } from "../context/internal/isAgenticaContext";
-import { createCallEvent, createExecuteEvent, createTextEvent, createValidateEvent } from "../factory/events";
-import { createCancelHistory, createExecuteHistory, createTextHistory, decodeHistory } from "../factory/histories";
+import { creatAssistantEvent, createCallEvent, createExecuteEvent, createValidateEvent } from "../factory/events";
+import { createAssistantMessageHistory, createCancelHistory, createExecuteHistory, decodeHistory, decodeUserMessageContent } from "../factory/histories";
 import { createOperationSelection } from "../factory/operations";
 import { ChatGptCompletionMessageUtil } from "../utils/ChatGptCompletionMessageUtil";
 import { StreamUtil, toAsyncGenerator } from "../utils/StreamUtil";
@@ -54,7 +54,7 @@ export async function call<Model extends ILlmSchema.Model>(
       // USER INPUT
       {
         role: "user",
-        content: ctx.prompt.contents,
+        content: ctx.prompt.contents.map(decodeUserMessageContent),
       },
       // SYSTEM PROMPT
       ...(ctx.config?.systemPrompt?.execute === null
@@ -104,7 +104,7 @@ export async function call<Model extends ILlmSchema.Model>(
       Array<
         | AgenticaExecuteHistory<Model>
         | AgenticaCancelHistory<Model>
-        | AgenticaTextHistory
+        | AgenticaAssistantMessageHistory
       >
     >
   > = [];
@@ -181,11 +181,11 @@ export async function call<Model extends ILlmSchema.Model>(
       && choice.message.content.length !== 0
     ) {
       closures.push(async () => {
-        const value: AgenticaTextHistory = createTextHistory(
+        const value: AgenticaAssistantMessageHistory = createAssistantMessageHistory(
           { text: choice.message.content! },
         );
         ctx.dispatch(
-          createTextEvent({
+          creatAssistantEvent({
             get: () => value.text,
             done: () => true,
             stream: toAsyncGenerator(value.text),
@@ -471,7 +471,7 @@ async function correct<Model extends ILlmSchema.Model>(
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.contents,
+          content: ctx.prompt.contents.map(decodeUserMessageContent),
         },
         // TYPE CORRECTION
         ...(ctx.config?.systemPrompt?.execute === null

package/src/orchestrate/cancel.ts

@@ -16,7 +16,7 @@ import type { AgenticaCancelHistory } from "../histories/AgenticaCancelHistory";
 import { AgenticaConstant } from "../constants/AgenticaConstant";
 import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
 import { AgenticaSystemPrompt } from "../constants/AgenticaSystemPrompt";
-import { createCancelHistory, decodeHistory } from "../factory/histories";
+import { createCancelHistory, decodeHistory, decodeUserMessageContent } from "../factory/histories";
 import { ChatGptCompletionMessageUtil } from "../utils/ChatGptCompletionMessageUtil";
 import { StreamUtil } from "../utils/StreamUtil";
 
@@ -141,7 +141,7 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.contents,
+          content: ctx.prompt.contents.map(decodeUserMessageContent),
         },
         // SYSTEM PROMPT
         {

package/src/orchestrate/initialize.ts

@@ -9,8 +9,8 @@ import type { AgenticaHistory } from "../histories/AgenticaHistory";
 
 import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
 import { AgenticaSystemPrompt } from "../constants/AgenticaSystemPrompt";
-import { createTextEvent } from "../factory/events";
-import { createTextHistory, decodeHistory } from "../factory/histories";
+import { creatAssistantEvent } from "../factory/events";
+import { createAssistantMessageHistory, decodeHistory, decodeUserMessageContent } from "../factory/histories";
 import { ChatGptCompletionMessageUtil } from "../utils/ChatGptCompletionMessageUtil";
 import { MPSC } from "../utils/MPSC";
 import { streamDefaultReaderToAsyncGenerator, StreamUtil } from "../utils/StreamUtil";
@@ -36,7 +36,7 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.contents,
+          content: ctx.prompt.contents.map(decodeUserMessageContent),
         },
         {
           // SYSTEM PROMPT
@@ -107,7 +107,7 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
         mpsc.produce(choice.delta.content);
 
         ctx.dispatch(
-          createTextEvent({
+          creatAssistantEvent({
             stream: streamDefaultReaderToAsyncGenerator(mpsc.consumer.getReader()),
             done: () => mpsc.done(),
             get: () => textContext[choice.index]!.content,
@@ -144,7 +144,7 @@ export async function initialize<Model extends ILlmSchema.Model>(ctx: AgenticaCo
       && choice.message.content.length !== 0
     ) {
       prompts.push(
-        createTextHistory({ text: choice.message.content }),
+        createAssistantMessageHistory({ text: choice.message.content }),
       );
     }
   }

package/src/orchestrate/select.ts

@@ -17,8 +17,8 @@ import type { AgenticaSelectHistory } from "../histories/AgenticaSelectHistory";
 import { AgenticaConstant } from "../constants/AgenticaConstant";
 import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
 import { AgenticaSystemPrompt } from "../constants/AgenticaSystemPrompt";
-import { createTextEvent } from "../factory/events";
-import { createSelectHistory, createTextHistory, decodeHistory } from "../factory/histories";
+import { creatAssistantEvent } from "../factory/events";
+import { createAssistantMessageHistory, createSelectHistory, decodeHistory, decodeUserMessageContent } from "../factory/histories";
 import { createOperationSelection } from "../factory/operations";
 import { ChatGptCompletionMessageUtil } from "../utils/ChatGptCompletionMessageUtil";
 import { StreamUtil, toAsyncGenerator } from "../utils/StreamUtil";
@@ -144,7 +144,7 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
         // USER INPUT
         {
           role: "user",
-          content: ctx.prompt.contents,
+          content: ctx.prompt.contents.map(decodeUserMessageContent),
         },
         // SYSTEM PROMPT
         {
@@ -259,11 +259,11 @@ async function step<Model extends ILlmSchema.Model>(ctx: AgenticaContext<Model>,
       && choice.message.content != null
       && choice.message.content.length !== 0
     ) {
-      const text = createTextHistory({ text: choice.message.content });
+      const text = createAssistantMessageHistory({ text: choice.message.content });
       prompts.push(text);
 
       ctx.dispatch(
-        createTextEvent({
+        creatAssistantEvent({
           stream: toAsyncGenerator(text.text),
           join: async () => Promise.resolve(text.text),
           done: () => true,

package/src/structures/IAgenticaController.ts

@@ -1,4 +1,3 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
 import type {
   IHttpConnection,
   IHttpLlmApplication,
@@ -126,7 +125,10 @@ export namespace IAgenticaController {
     /**
      * MCP client for connection.
      */
-    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;
   }
 
   interface IBase<Protocol, Application> {

package/src/structures/index.ts

@@ -0,0 +1,10 @@
+export * from "./IAgenticaConfig";
+export * from "./IAgenticaController";
+export * from "./IAgenticaExecutor";
+export * from "./IAgenticaProps";
+export * from "./IAgenticaSystemPrompt";
+export * from "./IAgenticaVendor";
+export * from "./IMicroAgenticaConfig";
+export * from "./IMicroAgenticaExecutor";
+export * from "./IMicroAgenticaProps";
+export * from "./IMicroAgenticaSystemPrompt";

package/src/transformers/{AgenticaEventTransformer.ts → transformEvent.ts}

@@ -1,6 +1,8 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
 import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaUserMessageEvent, AgenticaValidateEvent } from "../events";
+import type { AgenticaAssistantMessageEvent } from "../events/AgenticaAssistantMessageEvent";
 import type { AgenticaCallEvent } from "../events/AgenticaCallEvent";
 import type { AgenticaCancelEvent } from "../events/AgenticaCancelEvent";
 import type { AgenticaDescribeEvent } from "../events/AgenticaDescribeEvent";
@@ -9,32 +11,16 @@ import type { AgenticaExecuteEvent } from "../events/AgenticaExecuteEvent";
 import type { AgenticaInitializeEvent } from "../events/AgenticaInitializeEvent";
 import type { AgenticaRequestEvent } from "../events/AgenticaRequestEvent";
 import type { AgenticaSelectEvent } from "../events/AgenticaSelectEvent";
-import type { AgenticaTextEvent } from "../events/AgenticaTextEvent";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
 
-import { createCallEvent, createCancelEvent, createDescribeEvent, createExecuteEvent, createInitializeEvent, createRequestEvent, createSelectEvent, createTextEvent } from "../factory/events";
+import { creatAssistantEvent, createCallEvent, createCancelEvent, createDescribeEvent, createExecuteEvent, createInitializeEvent, createRequestEvent, createSelectEvent, createUserMessageEvent, createValidateEvent } from "../factory/events";
 import { createOperationSelection } from "../factory/operations";
 import { toAsyncGenerator } from "../utils/StreamUtil";
 
-function findOperation<Model extends ILlmSchema.Model>(props: {
-  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
-  input: {
-    controller: string;
-    function: string;
-  };
-}): AgenticaOperation<Model> {
-  const found: AgenticaOperation<Model> | undefined = props.operations
-    .get(props.input.controller)
-    ?.get(props.input.function);
-  if (found === undefined) {
-    throw new Error(
-      `No operation found: (controller: ${props.input.controller}, function: ${props.input.function})`,
-    );
-  }
-  return found;
-}
-
-function transform<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+export function transformEvent<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson;
 }): AgenticaEvent<Model> {
@@ -76,15 +62,26 @@ function transform<Model extends ILlmSchema.Model>(props: {
       event: props.event,
     });
   }
-  else if (props.event.type === "text") {
-    return transformText({
+  else if (props.event.type === "assistantMessage") {
+    return transformAssistantMessage({
+      event: props.event,
+    });
+  }
+  else if (props.event.type === "userMessage") {
+    return transformUserMessage({
       event: props.event,
     });
   }
-  else { throw new Error("Unknown event type"); }
+  return transformValidateEvent({
+    operations: props.operations,
+    event: props.event,
+  });
 }
 
-function transformCall<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+export function transformCall<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ICall;
 }): AgenticaCallEvent<Model> {
@@ -98,7 +95,10 @@ function transformCall<Model extends ILlmSchema.Model>(props: {
   });
 }
 
-export function transformCancel<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+function transformCancel<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ICancel;
 }): AgenticaCancelEvent<Model> {
@@ -113,6 +113,9 @@ export function transformCancel<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformDescribe<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.IDescribe;
@@ -131,6 +134,9 @@ function transformDescribe<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformExecute<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.IExecute;
@@ -146,16 +152,25 @@ function transformExecute<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformInitialize(): AgenticaInitializeEvent {
   return createInitializeEvent();
 }
 
+/**
+ * @internal
+ */
 function transformRequest(props: {
   event: IAgenticaEventJson.IRequest;
 }): AgenticaRequestEvent {
   return createRequestEvent(props.event);
 }
 
+/**
+ * @internal
+ */
 function transformSelect<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ISelect;
@@ -171,10 +186,13 @@ function transformSelect<Model extends ILlmSchema.Model>(props: {
   });
 }
 
-function transformText(props: {
-  event: IAgenticaEventJson.IText;
-}): AgenticaTextEvent {
-  return createTextEvent({
+/**
+ * @internal
+ */
+function transformAssistantMessage(props: {
+  event: IAgenticaEventJson.IAssistantMessage;
+}): AgenticaAssistantMessageEvent {
+  return creatAssistantEvent({
     stream: toAsyncGenerator(props.event.text),
     done: () => true,
     get: () => props.event.text,
@@ -182,15 +200,49 @@ function transformText(props: {
   });
 }
 
-export const AgenticaEventTransformer = {
-  transform,
-  transformCall,
-  transformCancel,
-  transformDescribe,
-  transformExecute,
-  transformInitialize,
-  transformRequest,
-  transformSelect,
-  transformText,
-  findOperation,
-};
+/**
+ * @internal
+ */
+function transformUserMessage(props: {
+  event: IAgenticaEventJson.IUserMessage;
+}): AgenticaUserMessageEvent {
+  return createUserMessageEvent(props.event);
+}
+
+/**
+ * @internal
+ */
+function transformValidateEvent<Model extends ILlmSchema.Model>(props: {
+  event: IAgenticaEventJson.IValidate;
+  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
+}): AgenticaValidateEvent<Model> {
+  return createValidateEvent({
+    id: props.event.id,
+    operation: findOperation({
+      operations: props.operations,
+      input: props.event.operation,
+    }),
+    result: props.event.result,
+  });
+}
+
+/**
+ * @internal
+ */
+function findOperation<Model extends ILlmSchema.Model>(props: {
+  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
+  input: {
+    controller: string;
+    function: string;
+  };
+}): AgenticaOperation<Model> {
+  const found: AgenticaOperation<Model> | undefined = props.operations
+    .get(props.input.controller)
+    ?.get(props.input.function);
+  if (found === undefined) {
+    throw new Error(
+      `No operation found: (controller: ${props.input.controller}, function: ${props.input.function})`,
+    );
+  }
+  return found;
+}