@agentica/core 0.7.0-dev.20250224

package/lib/structures/internal/__IChatSelectFunctionsApplication.d.ts

@@ -0,0 +1,23 @@
+import { __IChatFunctionReference } from "./__IChatFunctionReference";
+export interface __IChatSelectFunctionsApplication {
+    /**
+     * Select proper API functions to call.
+     *
+     * If you A.I. agent has found some proper API functions to call
+     * from the conversation with user, please select the API functions
+     * just by calling this function.
+     *
+     * When user wants to call a same function multiply, you A.I. agent must
+     * list up it multiply in the `functions` property. Otherwise the user has
+     * requested to call many different functions, you A.I. agent have to assign
+     * them all into the `functions` property.
+     *
+     * Also, if you A.I. agent can't specify a specific function to call due to lack
+     * of specificity or homogeneity of candidate functions, just assign all of them
+     * by in the` functions` property` too. Instead, when you A.I. agent can specify
+     * a specific function to call, the others would be eliminated.
+     *
+     * @param props Properties of the function
+     */
+    selectFunctions(props: __IChatFunctionReference.IProps): Promise<void>;
+}

package/lib/structures/internal/__IChatSelectFunctionsApplication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=__IChatSelectFunctionsApplication.js.map

package/lib/structures/internal/__IChatSelectFunctionsApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__IChatSelectFunctionsApplication.js","sourceRoot":"","sources":["../../../src/structures/internal/__IChatSelectFunctionsApplication.ts"],"names":[],"mappings":""}

package/lib/typings/AgenticaSource.d.ts

@@ -0,0 +1 @@
+export type AgenticaSource = "initialize" | "select" | "cancel" | "execute" | "describe";

package/lib/typings/AgenticaSource.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=AgenticaSource.js.map

package/lib/typings/AgenticaSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgenticaSource.js","sourceRoot":"","sources":["../../src/typings/AgenticaSource.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@agentica/core",
+  "version": "0.7.0-dev.20250224",
+  "main": "lib/index.js",
+  "description": "Agentic AI Library specialized in LLM Function Calling",
+  "scripts": {
+    "prepare": "ts-patch install && pnpm build:prompt",
+    "build": "rimraf lib && pnpm build:prompt && tsc && rollup -c",
+    "build:prompt": "ts-node build/prompt.ts",
+    "dev": "rimraf lib && tsc --watch",
+    "eslint": "eslint ./**/*.ts",
+    "test": "pnpm build:test && node bin/test/index.js"
+  },
+  "author": "Wrtn Technologies",
+  "homepage": "https://wrtnlabs.io/agentica",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wrtnlabs/agentica"
+  },
+  "bugs": {
+    "url": "https://github.com/wrtnlabs/agentica/issues"
+  },
+  "keywords": [
+    "openai",
+    "chatgpt",
+    "anthropic",
+    "claude",
+    "ai",
+    "chatbot",
+    "nestia",
+    "swagger",
+    "openapi"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "lib",
+    "prompts",
+    "src"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@nestia/e2e": "^0.8.2",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@samchon/openapi": "^2.4.2",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/node": "^22.13.4",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.17.0",
+    "openai": "^4.80.0",
+    "prettier": "^3.5.0",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.34.8",
+    "ts-node": "^10.9.2",
+    "ts-patch": "^3.3.0",
+    "typescript": "~5.7.3",
+    "typia": "^7.6.4"
+  },
+  "dependencies": {
+    "@samchon/openapi": "^2.4.3",
+    "typia": "^7.6.4",
+    "uuid": "^11.0.4"
+  },
+  "peerDependencies": {
+    "@samchon/openapi": ">= 2.4.3",
+    "openai": ">= 4.80.0",
+    "typia": ">= 7.6.4"
+  },
+  "module": "lib/index.mjs",
+  "typings": "lib/index.d.ts"
+}

package/prompts/cancel.md

@@ -0,0 +1,5 @@
+You are a helpful assistant for cancelling functions which are prepared to call.
+
+Use the supplied tools to select some functions to cancel of `getApiFunctions()` returned.
+
+If you can't find any proper function to select, don't talk, don't do anything.

package/prompts/common.md

@@ -0,0 +1,3 @@
+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.
+
+At 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.

package/prompts/describe.md

@@ -0,0 +1,7 @@
+You are a helpful assistant describing return values of function calls.
+
+Above 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.
+
+Also, 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.
+
+At last, if user's language locale code is different with your description, please translate it to the user's language.

package/prompts/execute.md

@@ -0,0 +1,7 @@
+You are a helpful assistant for tool calling.
+
+Use the supplied tools to assist the user.
+
+If 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.
+
+For 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.

package/prompts/initialize.md

@@ -0,0 +1,3 @@
+You are a helpful assistant.
+
+Use the supplied tools to assist the user.

package/prompts/select.md

@@ -0,0 +1,7 @@
+You are a helpful assistant for selecting functions to call.
+
+Use the supplied tools to select some functions of `getApiFunctions()` returned.
+
+When selecting functions to call, pay attention to the relationship between functions. In particular, check the prerequisites between each function.
+
+If 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.

package/src/Agentica.ts

@@ -0,0 +1,322 @@
+import OpenAI from "openai";
+
+import { ChatGptAgent } from "./chatgpt/ChatGptAgent";
+import { AgenticaCostAggregator } from "./internal/AgenticaCostAggregator";
+import { AgenticaOperationComposer } from "./internal/AgenticaOperationComposer";
+import { AgenticaPromptTransformer } from "./internal/AgenticaPromptTransformer";
+import { __map_take } from "./internal/__map_take";
+import { IAgenticaConfig } from "./structures/IAgenticaConfig";
+import { IAgenticaContext } from "./structures/IAgenticaContext";
+import { IAgenticaController } from "./structures/IAgenticaController";
+import { IAgenticaEvent } from "./structures/IAgenticaEvent";
+import { IAgenticaOperation } from "./structures/IAgenticaOperation";
+import { IAgenticaOperationCollection } from "./structures/IAgenticaOperationCollection";
+import { IAgenticaOperationSelection } from "./structures/IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "./structures/IAgenticaPrompt";
+import { IAgenticaProps } from "./structures/IAgenticaProps";
+import { IAgenticaProvider } from "./structures/IAgenticaProvider";
+import { IAgenticaTokenUsage } from "./structures/IAgenticaTokenUsage";
+
+/**
+ * Nestia A.I. chatbot agent.
+ *
+ * `Agentica` is a facade class for the super A.I. chatbot agent
+ * which performs the {@link converstate user's conversation function}
+ * with LLM (Large Language Model) function calling and manages the
+ * {@link getPromptHistories prompt histories}.
+ *
+ * To understand and compose the `Agentica` class exactly, reference
+ * below types concentrating on the documentation comments please.
+ * Especially, you have to be careful about the {@link IAgenticaProps}
+ * type which is used in the {@link constructor} function.
+ *
+ * - Constructors
+ *   - {@link IAgenticaProps}
+ *   - {@link IAgenticaProvider}
+ *   - {@link IAgenticaController}
+ *   - {@link IAgenticaConfig}
+ *   - {@link IAgenticaSystemPrompt}
+ * - Accessors
+ *   - {@link IAgenticaOperation}
+ *   - {@link IAgenticaPrompt}
+ *   - {@link IAgenticaEvent}
+ *   - {@link IAgenticaTokenUsage}
+ *
+ * @author Samchon
+ */
+export class Agentica {
+  // THE OPERATIONS
+  private readonly operations_: IAgenticaOperationCollection;
+
+  // STACK
+  private readonly stack_: IAgenticaOperationSelection[];
+  private readonly prompt_histories_: IAgenticaPrompt[];
+  private readonly listeners_: Map<string, Set<Function>>;
+
+  // STATUS
+  private readonly token_usage_: IAgenticaTokenUsage;
+  private ready_: boolean;
+  private readonly executor_: (
+    ctx: IAgenticaContext,
+  ) => Promise<IAgenticaPrompt[]>;
+
+  /* -----------------------------------------------------------
+    CONSTRUCTOR
+  ----------------------------------------------------------- */
+  /**
+   * Initializer constructor.
+   *
+   * @param props Properties to construct the agent
+   */
+  public constructor(private readonly props: IAgenticaProps) {
+    // OPERATIONS
+    this.operations_ = AgenticaOperationComposer.compose({
+      controllers: props.controllers,
+      config: props.config,
+    });
+
+    // STATUS
+    this.stack_ = [];
+    this.listeners_ = new Map();
+    this.prompt_histories_ = (props.histories ?? []).map((input) =>
+      AgenticaPromptTransformer.transform({
+        operations: this.operations_.group,
+        input,
+      }),
+    );
+
+    // STATUS
+    this.token_usage_ = {
+      total: 0,
+      prompt: {
+        total: 0,
+        audio: 0,
+        cached: 0,
+      },
+      completion: {
+        total: 0,
+        accepted_prediction: 0,
+        audio: 0,
+        reasoning: 0,
+        rejected_prediction: 0,
+      },
+    };
+    this.ready_ = false;
+    this.executor_ =
+      typeof props.config?.executor === "function"
+        ? props.config.executor
+        : ChatGptAgent.execute(props.config?.executor ?? null);
+  }
+
+  /**
+   * @internal
+   */
+  public clone(): Agentica {
+    return new Agentica({
+      ...this.props,
+      histories: this.props.histories?.slice(),
+    });
+  }
+
+  /* -----------------------------------------------------------
+    ACCESSORS
+  ----------------------------------------------------------- */
+  /**
+   * Conversate with the A.I. chatbot.
+   *
+   * User talks to the A.I. chatbot with the content.
+   *
+   * When the user's conversation implies the A.I. chatbot to execute a
+   * function calling, the returned chat prompts will contain the
+   * function calling information like {@link IAgenticaPrompt.IExecute}.
+   *
+   * @param content The content to talk
+   * @returns List of newly created chat prompts
+   */
+  public async conversate(content: string): Promise<IAgenticaPrompt[]> {
+    const prompt: IAgenticaPrompt.IText<"user"> = {
+      type: "text",
+      role: "user",
+      text: content,
+    };
+    await this.dispatch(prompt);
+
+    const newbie: IAgenticaPrompt[] = await this.executor_(
+      this.getContext({
+        prompt,
+        usage: this.token_usage_,
+      }),
+    );
+    this.prompt_histories_.push(prompt, ...newbie);
+    return [prompt, ...newbie];
+  }
+
+  /**
+   * Get configuration.
+   */
+  public getConfig(): IAgenticaConfig | undefined {
+    return this.props.config;
+  }
+
+  /**
+   * Get LLM Provider.
+   */
+  public getProvider(): IAgenticaProvider {
+    return this.props.provider;
+  }
+
+  /**
+   * Get controllers.
+   *
+   * Get list of controllers, which are the collection of functions that
+   * the "Super A.I. Chatbot" can execute.
+   */
+  public getControllers(): ReadonlyArray<IAgenticaController> {
+    return this.props.controllers;
+  }
+
+  /**
+   * Get operations.
+   *
+   * Get list of operations, which has capsuled the pair of controller
+   * and function from the {@link getControllers controllers}.
+   *
+   * @returns
+   */
+  public getOperations(): ReadonlyArray<IAgenticaOperation> {
+    return this.operations_.array;
+  }
+
+  /**
+   * Get the chatbot's prompt histories.
+   *
+   * Get list of chat prompts that the chatbot has been conversated.
+   *
+   * @returns List of chat prompts
+   */
+  public getPromptHistories(): IAgenticaPrompt[] {
+    return this.prompt_histories_;
+  }
+
+  /**
+   * Get token usage of the A.I. chatbot.
+   *
+   * Entire token usage of the A.I. chatbot during the conversating
+   * with the user by {@link conversate} method callings.
+   *
+   * @returns Cost of the A.I. chatbot
+   */
+  public getTokenUsage(): IAgenticaTokenUsage {
+    return this.token_usage_;
+  }
+
+  /**
+   * @internal
+   */
+  public getContext(props: {
+    prompt: IAgenticaPrompt.IText<"user">;
+    usage: IAgenticaTokenUsage;
+  }): IAgenticaContext {
+    const dispatch = (event: IAgenticaEvent) => this.dispatch(event);
+    return {
+      // APPLICATION
+      operations: this.operations_,
+      config: this.props.config,
+
+      // STATES
+      histories: this.prompt_histories_,
+      stack: this.stack_,
+      ready: () => this.ready_,
+      prompt: props.prompt,
+
+      // HANDLERS
+      dispatch,
+      request: async (source, body) => {
+        // request information
+        const event: IAgenticaEvent.IRequest = {
+          type: "request",
+          source,
+          body: {
+            ...body,
+            model: this.props.provider.model,
+          },
+          options: this.props.provider.options,
+        };
+        await dispatch(event);
+
+        // completion
+        const value: OpenAI.ChatCompletion =
+          await this.props.provider.api.chat.completions.create(
+            event.body,
+            event.options,
+          );
+        AgenticaCostAggregator.aggregate(props.usage, value);
+        await dispatch({
+          type: "response",
+          source,
+          body: event.body,
+          options: event.options,
+          value,
+        });
+        return value;
+      },
+      initialize: async () => {
+        this.ready_ = true;
+        await dispatch({
+          type: "initialize",
+        });
+      },
+    };
+  }
+
+  /* -----------------------------------------------------------
+    EVENT HANDLERS
+  ----------------------------------------------------------- */
+  /**
+   * Add an event listener.
+   *
+   * Add an event listener to be called whenever the event is emitted.
+   *
+   * @param type Type of event
+   * @param listener Callback function to be called whenever the event is emitted
+   */
+  public on<Type extends IAgenticaEvent.Type>(
+    type: Type,
+    listener: (event: IAgenticaEvent.Mapper[Type]) => void | Promise<void>,
+  ): void {
+    __map_take(this.listeners_, type, () => new Set()).add(listener);
+  }
+
+  /**
+   * Erase an event listener.
+   *
+   * Erase an event listener to stop calling the callback function.
+   *
+   * @param type Type of event
+   * @param listener Callback function to erase
+   */
+  public off<Type extends IAgenticaEvent.Type>(
+    type: Type,
+    listener: (event: IAgenticaEvent.Mapper[Type]) => void | Promise<void>,
+  ): void {
+    const set: Set<Function> | undefined = this.listeners_.get(type);
+    if (set) {
+      set.delete(listener);
+      if (set.size === 0) this.listeners_.delete(type);
+    }
+  }
+
+  private async dispatch<Event extends IAgenticaEvent>(
+    event: Event,
+  ): Promise<void> {
+    const set: Set<Function> | undefined = this.listeners_.get(event.type);
+    if (set)
+      await Promise.all(
+        Array.from(set).map(async (listener) => {
+          try {
+            await listener(event);
+          } catch {}
+        }),
+      );
+  }
+}

package/src/chatgpt/ChatGptAgent.ts

@@ -0,0 +1,71 @@
+import { IAgenticaContext } from "../structures/IAgenticaContext";
+import { IAgenticaExecutor } from "../structures/IAgenticaExecutor";
+import { IAgenticaPrompt } from "../structures/IAgenticaPrompt";
+import { ChatGptCallFunctionAgent } from "./ChatGptCallFunctionAgent";
+import { ChatGptCancelFunctionAgent } from "./ChatGptCancelFunctionAgent";
+import { ChatGptDescribeFunctionAgent } from "./ChatGptDescribeFunctionAgent";
+import { ChatGptInitializeFunctionAgent } from "./ChatGptInitializeFunctionAgent";
+import { ChatGptSelectFunctionAgent } from "./ChatGptSelectFunctionAgent";
+
+export namespace ChatGptAgent {
+  export const execute =
+    (executor: Partial<IAgenticaExecutor> | null) =>
+    async (ctx: IAgenticaContext): Promise<IAgenticaPrompt[]> => {
+      const histories: IAgenticaPrompt[] = [];
+
+      // FUNCTIONS ARE NOT LISTED YET
+      if (ctx.ready() === false) {
+        if (executor?.initialize === null) await ctx.initialize();
+        else {
+          histories.push(
+            ...(await (
+              executor?.initialize ?? ChatGptInitializeFunctionAgent.execute
+            )(ctx)),
+          );
+          if (ctx.ready() === false) return histories;
+        }
+      }
+
+      // CANCEL CANDIDATE FUNCTIONS
+      if (ctx.stack.length !== 0)
+        histories.push(
+          ...(await (executor?.cancel ?? ChatGptCancelFunctionAgent.execute)(
+            ctx,
+          )),
+        );
+
+      // SELECT CANDIDATE FUNCTIONS
+      histories.push(
+        ...(await (executor?.select ?? ChatGptSelectFunctionAgent.execute)(
+          ctx,
+        )),
+      );
+      if (ctx.stack.length === 0) return histories;
+
+      // FUNCTION CALLING LOOP
+      while (true) {
+        // EXECUTE FUNCTIONS
+        const prompts: IAgenticaPrompt[] = await (
+          executor?.call ?? ChatGptCallFunctionAgent.execute
+        )(ctx);
+        histories.push(...prompts);
+
+        // EXPLAIN RETURN VALUES
+        const executes: IAgenticaPrompt.IExecute[] = prompts.filter(
+          (prompt) => prompt.type === "execute",
+        );
+        for (const e of executes)
+          await ChatGptCancelFunctionAgent.cancelFunction(ctx, {
+            reason: "completed",
+            name: e.function.name,
+          });
+        histories.push(
+          ...(await (
+            executor?.describe ?? ChatGptDescribeFunctionAgent.execute
+          )(ctx, executes)),
+        );
+        if (executes.length === 0 || ctx.stack.length === 0) break;
+      }
+      return histories;
+    };
+}