@agentica/core 0.7.0-dev.20250224

package/src/chatgpt/ChatGptSelectFunctionAgent.ts

@@ -0,0 +1,316 @@
+import { IHttpLlmFunction, ILlmApplication } from "@samchon/openapi";
+import OpenAI from "openai";
+import typia, { IValidation } from "typia";
+import { v4 } from "uuid";
+
+import { AgenticaConstant } from "../internal/AgenticaConstant";
+import { AgenticaDefaultPrompt } from "../internal/AgenticaDefaultPrompt";
+import { AgenticaPromptFactory } from "../internal/AgenticaPromptFactory";
+import { AgenticaSystemPrompt } from "../internal/AgenticaSystemPrompt";
+import { IAgenticaContext } from "../structures/IAgenticaContext";
+import { IAgenticaController } from "../structures/IAgenticaController";
+import { IAgenticaEvent } from "../structures/IAgenticaEvent";
+import { IAgenticaOperation } from "../structures/IAgenticaOperation";
+import { IAgenticaOperationSelection } from "../structures/IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "../structures/IAgenticaPrompt";
+import { __IChatFunctionReference } from "../structures/internal/__IChatFunctionReference";
+import { __IChatSelectFunctionsApplication } from "../structures/internal/__IChatSelectFunctionsApplication";
+import { ChatGptHistoryDecoder } from "./ChatGptHistoryDecoder";
+
+export namespace ChatGptSelectFunctionAgent {
+  export const execute = async (
+    ctx: IAgenticaContext,
+  ): Promise<IAgenticaPrompt[]> => {
+    if (ctx.operations.divided === undefined)
+      return step(ctx, ctx.operations.array, 0);
+
+    const stacks: IAgenticaOperationSelection[][] = ctx.operations.divided.map(
+      () => [],
+    );
+    const events: IAgenticaEvent[] = [];
+    const prompts: IAgenticaPrompt[][] = await Promise.all(
+      ctx.operations.divided.map((operations, i) =>
+        step(
+          {
+            ...ctx,
+            stack: stacks[i]!,
+            dispatch: async (e) => {
+              events.push(e);
+            },
+          },
+          operations,
+          0,
+        ),
+      ),
+    );
+
+    // NO FUNCTION SELECTION, SO THAT ONLY TEXT LEFT
+    if (stacks.every((s) => s.length === 0)) return prompts[0]!;
+    // ELITICISM
+    else if ((ctx.config?.eliticism ?? AgenticaConstant.ELITICISM) === true)
+      return step(
+        ctx,
+        stacks
+          .flat()
+          .map(
+            (s) =>
+              ctx.operations.group
+                .get(s.controller.name)!
+                .get(s.function.name)!,
+          ),
+        0,
+      );
+
+    // RE-COLLECT SELECT FUNCTION EVENTS
+    const collection: IAgenticaPrompt.ISelect = {
+      id: v4(),
+      type: "select",
+      operations: [],
+    };
+    for (const e of events)
+      if (e.type === "select") {
+        collection.operations.push(
+          AgenticaPromptFactory.selection({
+            protocol: e.operation.protocol as "http",
+            controller: e.operation.controller as IAgenticaController.IHttp,
+            function: e.operation.function as IHttpLlmFunction<"chatgpt">,
+            reason: e.reason,
+            name: e.operation.name,
+          }),
+        );
+        await selectFunction(ctx, {
+          name: e.operation.name,
+          reason: e.reason,
+        });
+      }
+    return [collection];
+  };
+
+  const step = async (
+    ctx: IAgenticaContext,
+    operations: IAgenticaOperation[],
+    retry: number,
+    failures?: IFailure[],
+  ): Promise<IAgenticaPrompt[]> => {
+    //----
+    // EXECUTE CHATGPT API
+    //----
+    const completion: OpenAI.ChatCompletion = await ctx.request("select", {
+      messages: [
+        // COMMON SYSTEM PROMPT
+        {
+          role: "system",
+          content: AgenticaDefaultPrompt.write(ctx.config),
+        } satisfies OpenAI.ChatCompletionSystemMessageParam,
+        // CANDIDATE FUNCTIONS
+        {
+          role: "assistant",
+          tool_calls: [
+            {
+              type: "function",
+              id: "getApiFunctions",
+              function: {
+                name: "getApiFunctions",
+                arguments: JSON.stringify({}),
+              },
+            },
+          ],
+        },
+        {
+          role: "tool",
+          tool_call_id: "getApiFunctions",
+          content: JSON.stringify(
+            operations.map((op) => ({
+              name: op.name,
+              description: op.function.description,
+              ...(op.protocol === "http"
+                ? {
+                    method: op.function.method,
+                    path: op.function.path,
+                    tags: op.function.tags,
+                  }
+                : {}),
+            })),
+          ),
+        },
+        // PREVIOUS HISTORIES
+        ...ctx.histories.map(ChatGptHistoryDecoder.decode).flat(),
+        // USER INPUT
+        {
+          role: "user",
+          content: ctx.prompt.text,
+        },
+        // SYSTEM PROMPT
+        {
+          role: "system",
+          content: AgenticaSystemPrompt.SELECT,
+        },
+        // TYPE CORRECTIONS
+        ...emendMessages(failures ?? []),
+      ],
+      // STACK FUNCTIONS
+      tools: CONTAINER.functions.map(
+        (func) =>
+          ({
+            type: "function",
+            function: {
+              name: func.name,
+              description: func.description,
+              parameters: func.parameters as any,
+            },
+          }) satisfies OpenAI.ChatCompletionTool,
+      ),
+      tool_choice: "auto",
+      parallel_tool_calls: false,
+    });
+
+    //----
+    // VALIDATION
+    //----
+    if (retry++ < (ctx.config?.retry ?? AgenticaConstant.RETRY)) {
+      const failures: IFailure[] = [];
+      for (const choice of completion.choices)
+        for (const tc of choice.message.tool_calls ?? []) {
+          if (tc.function.name !== "selectFunctions") continue;
+          const input: object = JSON.parse(tc.function.arguments);
+          const validation: IValidation<__IChatFunctionReference.IProps> =
+            typia.validate<__IChatFunctionReference.IProps>(input);
+          if (validation.success === false)
+            failures.push({
+              id: tc.id,
+              name: tc.function.name,
+              validation,
+            });
+        }
+      if (failures.length > 0) return step(ctx, operations, retry, failures);
+    }
+
+    //----
+    // PROCESS COMPLETION
+    //----
+    const prompts: IAgenticaPrompt[] = [];
+    for (const choice of completion.choices) {
+      // TOOL CALLING HANDLER
+      if (choice.message.tool_calls)
+        for (const tc of choice.message.tool_calls) {
+          if (tc.type !== "function") continue;
+
+          const input: __IChatFunctionReference.IProps = JSON.parse(
+            tc.function.arguments,
+          );
+          if (typia.is(input) === false) continue;
+          else if (tc.function.name === "selectFunctions") {
+            const collection: IAgenticaPrompt.ISelect = {
+              id: tc.id,
+              type: "select",
+              operations: [],
+            };
+            for (const reference of input.functions) {
+              const operation: IAgenticaOperation | null = await selectFunction(
+                ctx,
+                reference,
+              );
+              if (operation !== null)
+                collection.operations.push(
+                  AgenticaPromptFactory.selection({
+                    protocol: operation.protocol as "http",
+                    controller:
+                      operation.controller as IAgenticaController.IHttp,
+                    function: operation.function as IHttpLlmFunction<"chatgpt">,
+                    name: operation.name,
+                    reason: reference.reason,
+                  }),
+                );
+            }
+            if (collection.operations.length !== 0) prompts.push(collection);
+          }
+        }
+
+      // ASSISTANT MESSAGE
+      if (
+        choice.message.role === "assistant" &&
+        !!choice.message.content?.length
+      ) {
+        const text: IAgenticaPrompt.IText = {
+          type: "text",
+          role: "assistant",
+          text: choice.message.content,
+        };
+        prompts.push(text);
+        await ctx.dispatch(text);
+      }
+    }
+    return prompts;
+  };
+
+  const selectFunction = async (
+    ctx: IAgenticaContext,
+    reference: __IChatFunctionReference,
+  ): Promise<IAgenticaOperation | null> => {
+    const operation: IAgenticaOperation | undefined = ctx.operations.flat.get(
+      reference.name,
+    );
+    if (operation === undefined) return null;
+
+    ctx.stack.push(
+      AgenticaPromptFactory.selection({
+        protocol: operation.protocol as "http",
+        controller: operation.controller as IAgenticaController.IHttp,
+        function: operation.function as IHttpLlmFunction<"chatgpt">,
+        name: reference.name,
+        reason: reference.reason,
+      }),
+    );
+    await ctx.dispatch({
+      type: "select",
+      reason: reference.reason,
+      operation,
+    });
+    return operation;
+  };
+
+  const emendMessages = (
+    failures: IFailure[],
+  ): OpenAI.ChatCompletionMessageParam[] =>
+    failures
+      .map((f) => [
+        {
+          role: "assistant",
+          tool_calls: [
+            {
+              type: "function",
+              id: f.id,
+              function: {
+                name: f.name,
+                arguments: JSON.stringify(f.validation.data),
+              },
+            },
+          ],
+        } satisfies OpenAI.ChatCompletionAssistantMessageParam,
+        {
+          role: "tool",
+          content: JSON.stringify(f.validation.errors),
+          tool_call_id: f.id,
+        } satisfies OpenAI.ChatCompletionToolMessageParam,
+        {
+          role: "system",
+          content: [
+            "You A.I. assistant has composed wrong typed arguments.",
+            "",
+            "Correct it at the next function calling.",
+          ].join("\n"),
+        } satisfies OpenAI.ChatCompletionSystemMessageParam,
+      ])
+      .flat();
+}
+
+const CONTAINER: ILlmApplication<"chatgpt"> = typia.llm.application<
+  __IChatSelectFunctionsApplication,
+  "chatgpt"
+>();
+
+interface IFailure {
+  id: string;
+  name: string;
+  validation: IValidation.IFailure;
+}

package/src/functional/createHttpLlmApplication.ts

@@ -0,0 +1,63 @@
+import {
+  HttpLlm,
+  IHttpLlmApplication,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@samchon/openapi";
+import typia, { IValidation } from "typia";
+
+/**
+ * Create an HTTP LLM application instance.
+ * 
+ * Create an {@link IHttpLlmApplication} instance which represents
+ * the LLM (Large Language Model) function calling application schema 
+ * from the given Swagger/OpenAPI document and the target LLM model.
+ * 
+ * By the way, even though this `createHttpLlmApplication` 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 LLM application instance
+ * @returns Validation result of the HTTP LLM application composition
+ * @author Samchon
+ */
+export const createHttpLlmApplication = (props: {
+  /**
+   * Target LLM model.
+   */
+  model: "chatgpt";
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<"chatgpt">>;
+}): IValidation<IHttpLlmApplication<"chatgpt">> => {
+  const inspect: IValidation<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  > = typia.validate(props.document);
+  if (inspect.success === false) return inspect;
+  return {
+    success: true,
+    data: HttpLlm.application({
+      model: props.model,
+      document: OpenApi.convert(props.document),
+      options: props.options,
+    }),
+  };
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+// TYPES
+export * from "./structures/IAgenticaConfig";
+export * from "./structures/IAgenticaContext";
+export * from "./structures/IAgenticaController";
+export * from "./structures/IAgenticaEvent";
+export * from "./structures/IAgenticaExecutor";
+export * from "./structures/IAgenticaOperation";
+export * from "./structures/IAgenticaOperationCollection";
+export * from "./structures/IAgenticaOperationSelection";
+export * from "./structures/IAgenticaPrompt";
+export * from "./structures/IAgenticaProps";
+export * from "./structures/IAgenticaProvider";
+export * from "./structures/IAgenticaSystemPrompt";
+export * from "./structures/IAgenticaTokenUsage";
+export * from "./typings/AgenticaSource";
+
+// FACADE CLASS
+export * from "./functional/createHttpLlmApplication";
+export * from "./Agentica";

package/src/internal/AgenticaConstant.ts

@@ -0,0 +1,4 @@
+export namespace AgenticaConstant {
+  export const RETRY = 3;
+  export const ELITICISM = true;
+}

package/src/internal/AgenticaCostAggregator.ts

@@ -0,0 +1,35 @@
+import OpenAI from "openai";
+
+import { IAgenticaTokenUsage } from "../structures/IAgenticaTokenUsage";
+
+export namespace AgenticaCostAggregator {
+  export const aggregate = (
+    cost: IAgenticaTokenUsage,
+    completion: OpenAI.ChatCompletion,
+  ): void => {
+    if (!completion.usage) return;
+
+    // TOTAL
+    cost.total += completion.usage.total_tokens;
+
+    // PROMPT
+    cost.prompt.total += completion.usage.prompt_tokens;
+    cost.prompt.audio +=
+      completion.usage.prompt_tokens_details?.audio_tokens ?? 0;
+    cost.prompt.cached +=
+      completion.usage.prompt_tokens_details?.cached_tokens ?? 0;
+
+    // COMPLETION
+    cost.completion.total += completion.usage.total_tokens;
+    cost.completion.accepted_prediction +=
+      completion.usage.completion_tokens_details?.accepted_prediction_tokens ??
+      0;
+    cost.completion.audio +=
+      completion.usage.completion_tokens_details?.audio_tokens ?? 0;
+    cost.completion.reasoning +=
+      completion.usage.completion_tokens_details?.reasoning_tokens ?? 0;
+    cost.completion.rejected_prediction +=
+      completion.usage.completion_tokens_details?.rejected_prediction_tokens ??
+      0;
+  };
+}

package/src/internal/AgenticaDefaultPrompt.ts

@@ -0,0 +1,39 @@
+import { IAgenticaConfig } from "../structures/IAgenticaConfig";
+import { AgenticaSystemPrompt } from "./AgenticaSystemPrompt";
+import { Singleton } from "./Singleton";
+
+export namespace AgenticaDefaultPrompt {
+  export const write = (config?: IAgenticaConfig): string => {
+    if (config?.systemPrompt?.common)
+      return config?.systemPrompt?.common(config);
+
+    const locale: string = config?.locale ?? getLocale.get();
+    const timezone: string = config?.timezone ?? getTimezone.get();
+
+    return AgenticaSystemPrompt.COMMON.replace("${locale}", locale).replace(
+      "${timezone}",
+      timezone,
+    );
+  };
+}
+
+const getLocale = new Singleton(() =>
+  isNode.get()
+    ? (process.env.LANG?.split(".")[0] ?? "en-US")
+    : navigator.language,
+);
+
+const getTimezone = new Singleton(
+  () => Intl.DateTimeFormat().resolvedOptions().timeZone,
+);
+
+const isNode = new Singleton(() => {
+  const isObject = (obj: any) => typeof obj === "object" && obj !== null;
+  return (
+    typeof global === "object" &&
+    isObject(global) &&
+    isObject(global.process) &&
+    isObject(global.process.versions) &&
+    typeof global.process.versions.node !== "undefined"
+  );
+});

package/src/internal/AgenticaOperationComposer.ts

@@ -0,0 +1,82 @@
+import { IAgenticaConfig } from "../structures/IAgenticaConfig";
+import { IAgenticaController } from "../structures/IAgenticaController";
+import { IAgenticaOperation } from "../structures/IAgenticaOperation";
+import { IAgenticaOperationCollection } from "../structures/IAgenticaOperationCollection";
+import { __map_take } from "./__map_take";
+
+export namespace AgenticaOperationComposer {
+  export const compose = (props: {
+    controllers: IAgenticaController[];
+    config?: IAgenticaConfig | undefined;
+  }): IAgenticaOperationCollection => {
+    const unique: boolean =
+      props.controllers.length === 1 ||
+      (() => {
+        const names: string[] = props.controllers
+          .map((controller) =>
+            controller.application.functions.map((func) => func.name),
+          )
+          .flat();
+        return new Set(names).size === names.length;
+      })();
+    const naming = (func: string, ci: number) =>
+      unique ? func : `_${ci}_${func}`;
+
+    const array: IAgenticaOperation[] = props.controllers
+      .map((controller, ci) =>
+        controller.protocol === "http"
+          ? controller.application.functions.map(
+              (func) =>
+                ({
+                  protocol: "http",
+                  controller,
+                  function: func,
+                  name: naming(func.name, ci),
+                }) satisfies IAgenticaOperation.IHttp,
+            )
+          : controller.application.functions.map(
+              (func) =>
+                ({
+                  protocol: "class",
+                  controller,
+                  function: func,
+                  name: naming(func.name, ci),
+                }) satisfies IAgenticaOperation.IClass,
+            ),
+      )
+      .flat();
+    const divided: IAgenticaOperation[][] | undefined =
+      !!props.config?.capacity && array.length > props.config.capacity
+        ? divideOperations({
+            array,
+            capacity: props.config.capacity,
+          })
+        : undefined;
+
+    const flat: Map<string, IAgenticaOperation> = new Map();
+    const group: Map<string, Map<string, IAgenticaOperation>> = new Map();
+    for (const item of array) {
+      flat.set(item.name, item);
+      __map_take(group, item.controller.name, () => new Map()).set(
+        item.name,
+        item,
+      );
+    }
+    return {
+      array,
+      divided,
+      flat,
+      group,
+    };
+  };
+
+  const divideOperations = (props: {
+    array: IAgenticaOperation[];
+    capacity: number;
+  }): IAgenticaOperation[][] => {
+    const size: number = Math.ceil(props.array.length / props.capacity);
+    const capacity: number = Math.ceil(props.array.length / size);
+    const replica: IAgenticaOperation[] = props.array.slice();
+    return new Array(size).fill(0).map(() => replica.splice(0, capacity));
+  };
+}

package/src/internal/AgenticaPromptFactory.ts

@@ -0,0 +1,30 @@
+import { IAgenticaOperationSelection } from "../structures/IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "../structures/IAgenticaPrompt";
+
+export namespace AgenticaPromptFactory {
+  export const execute = (
+    props: Omit<IAgenticaPrompt.IExecute, "toJSON">,
+  ): IAgenticaPrompt.IExecute =>
+    ({
+      ...props,
+      toJSON: () =>
+        ({
+          ...props,
+          controller: props.controller.name,
+          function: props.function.name,
+        }) as any,
+    }) as IAgenticaPrompt.IExecute;
+
+  export const selection = (
+    props: Omit<IAgenticaOperationSelection, "toJSON">,
+  ): IAgenticaOperationSelection =>
+    ({
+      ...props,
+      toJSON: () =>
+        ({
+          ...props,
+          controller: props.controller.name,
+          function: props.function.name,
+        }) as any,
+    }) as IAgenticaOperationSelection;
+}

package/src/internal/AgenticaPromptTransformer.ts

@@ -0,0 +1,83 @@
+import { Primitive } from "typia";
+
+import { IAgenticaOperation } from "../structures/IAgenticaOperation";
+import { IAgenticaPrompt } from "../structures/IAgenticaPrompt";
+import { AgenticaPromptFactory } from "./AgenticaPromptFactory";
+
+export namespace AgenticaPromptTransformer {
+  export const transform = (props: {
+    operations: Map<string, Map<string, IAgenticaOperation>>;
+    input: Primitive<IAgenticaPrompt>;
+  }): IAgenticaPrompt => {
+    // TEXT
+    if (props.input.type === "text") return props.input;
+    // SELECT & CANCEL
+    else if (props.input.type === "select" || props.input.type === "cancel")
+      return {
+        ...props.input,
+        operations: props.input.operations.map((func) =>
+          AgenticaPromptFactory.selection({
+            ...findOperation({
+              operations: props.operations,
+              input: func,
+            }),
+            reason: func.reason,
+          }),
+        ),
+      } satisfies IAgenticaPrompt.ISelect | IAgenticaPrompt.ICancel;
+    // EXECUTE
+    else if (props.input.type === "execute")
+      return transformExecute({
+        operations: props.operations,
+        input: props.input,
+      }) satisfies IAgenticaPrompt.IExecute;
+    // DESCRIBE
+    return {
+      type: "describe",
+      text: props.input.text,
+      executions: props.input.executions.map((next) =>
+        transformExecute({
+          operations: props.operations,
+          input: next,
+        }),
+      ),
+    } satisfies IAgenticaPrompt.IDescribe;
+  };
+
+  const transformExecute = (props: {
+    operations: Map<string, Map<string, IAgenticaOperation>>;
+    input: Primitive<IAgenticaPrompt.IExecute>;
+  }): IAgenticaPrompt.IExecute => {
+    const operation = findOperation({
+      operations: props.operations,
+      input: props.input,
+    });
+    return AgenticaPromptFactory.execute({
+      type: "execute",
+      protocol: operation.protocol as "http",
+      controller: operation.controller,
+      function: operation.function,
+      id: props.input.id,
+      name: props.input.name,
+      arguments: props.input.arguments,
+      value: props.input.value,
+    });
+  };
+
+  const findOperation = (props: {
+    operations: Map<string, Map<string, IAgenticaOperation>>;
+    input: {
+      controller: string;
+      function: string;
+    };
+  }): IAgenticaOperation.IHttp => {
+    const found: IAgenticaOperation | 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 as IAgenticaOperation.IHttp;
+  };
+}

package/src/internal/AgenticaSystemPrompt.ts

@@ -0,0 +1,14 @@
+export namespace AgenticaSystemPrompt {
+  export const CANCEL =
+    "You are a helpful assistant for cancelling functions which are prepared to call.\n\nUse the supplied tools to select some functions to cancel of `getApiFunctions()` returned.\n\nIf you can't find any proper function to select, don't talk, don't do anything.";
+  export const COMMON =
+    "At first, the user's language locale code is \"${locale}\". When you are conversating with the user or describing the function calling result, consider it and always translate to the target locale language. Never conversate with different locale language text with the user.\n\nAt second, the user's timezone is \"${timezone}\", and ISO datetime is ${datetime}. When you are conversating with the user, consider current time and user belonged timezone.";
+  export const DESCRIBE =
+    "You are a helpful assistant describing return values of function calls.\n\nAbove messages are the list of function call histories. When describing the return values, please do not too much shortly summarize them. Instead, provide detailed descriptions as much as.\n\nAlso, its content format must be markdown. If required, utilize the mermaid syntax for drawing some diagrams. When image contents are, just put them through the markdown image syntax.\n\nAt last, if user's language locale code is different with your description, please translate it to the user's language.";
+  export const EXECUTE =
+    "You are a helpful assistant for tool calling.\n\nUse the supplied tools to assist the user.\n\nIf previous messages are not enough to compose the arguments, you can ask the user to write more information. By the way, when asking the user to write more information, make the text concise and clear.\n\nFor reference, in the \"tool\" role message content, the `function` property means metadata of the API operation. In other words, it is the function schema describing its purpose, parameters and return value types. And then the `data` property is the return value from the target function calling.";
+  export const INITIALIZE =
+    "You are a helpful assistant.\n\nUse the supplied tools to assist the user.";
+  export const SELECT =
+    "You are a helpful assistant for selecting functions to call.\n\nUse the supplied tools to select some functions of `getApiFunctions()` returned.\n\nWhen selecting functions to call, pay attention to the relationship between functions. In particular, check the prerequisites between each function.\n\nIf you can't find any proper function to select, just type your own message. By the way, when typing your own message, please consider the user's language locale code. If your message is different with the user's language, please translate it to the user's.";
+}