@agentica/core 0.7.0-dev.20250224

package/lib/structures/IAgenticaContext.d.ts

@@ -0,0 +1,106 @@
+import OpenAI from "openai";
+import { AgenticaSource } from "../typings/AgenticaSource";
+import { IAgenticaConfig } from "./IAgenticaConfig";
+import { IAgenticaEvent } from "./IAgenticaEvent";
+import { IAgenticaOperationCollection } from "./IAgenticaOperationCollection";
+import { IAgenticaOperationSelection } from "./IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+/**
+ * Context of the Nestia A.I. agent.
+ *
+ * `IAgenticaContext` is a structure defining the context of the
+ * internal agents composing the {@link Agentica}, like function
+ * selector, executor, and describer, and so on. For example, if an
+ * agent has been configured to utilize the OpenAI, the context will
+ * be delivered to the below components.
+ *
+ * - {@link ChatGptAgent}
+ *   - {@link ChatGptInitializeFunctionAgent}
+ *   - {@link ChatGptSelectFunctionAgent}
+ *   - {@link ChatGptExecuteFunctionAgent}
+ *   - {@link ChatGptDescribeFunctionAgent}
+ *   - {@link ChatGptCancelFunctionAgent}
+ *
+ * Also, as its name is context, it contains every information that
+ * is required to interact with the AI provider like OpenAI. It
+ * contains every operations for LLM function calling, and
+ * configuration used for the agent construction. And it contains
+ * the prompt histories, and facade controller functions for
+ * interacting with the {@link Agentica} like {@link dispatch}.
+ *
+ * In such reasons, if you're planning to customize some internal
+ * agents, or add new agents with new process routine, you have to
+ * understand this context structure. Otherwise you don't have any
+ * plan to customize the internal agents, this context information is
+ * not important for you.
+ *
+ * @author Samchon
+ */
+export interface IAgenticaContext {
+    /**
+     * Collection of operations.
+     *
+     * Collection of operations from every controllers, and their
+     * groups composed by the divide and conquer rule for the
+     * efficient operation selection if configured.
+     */
+    operations: IAgenticaOperationCollection;
+    /**
+     * Configuration of the agent.
+     *
+     * Configuration of the agent, that is used when constructing the
+     * {@link Agentica} instance.
+     *
+     * @todo Write detaily after supporting the agent customization feature
+     */
+    config: IAgenticaConfig | undefined;
+    /**
+     * Prompt histories.
+     */
+    histories: IAgenticaPrompt[];
+    /**
+     * Stacked operations.
+     *
+     * In other words, list of candidate operations for the LLM function calling.
+     */
+    stack: IAgenticaOperationSelection[];
+    /**
+     * Text prompt of the user.
+     *
+     * Text conversation written the by user through the
+     * {@link Agentica.conversate} function.
+     */
+    prompt: IAgenticaPrompt.IText<"user">;
+    /**
+     * Whether the agent is ready.
+     *
+     * Returns a boolean value indicates whether the agent is ready to
+     * perform the function calling.
+     *
+     * If the agent has called the {@link IAgenticaContext.initialize},
+     * it returns `true`. Otherwise the {@link initialize} has never been
+     * called, returns `false`.
+     */
+    ready: () => boolean;
+    /**
+     * Dispatch event.
+     *
+     * Dispatch event so that the agent can be handle the event
+     * through the {@link Agentica.on} function.
+     *
+     * @param event Event to deliver
+     */
+    dispatch: (event: IAgenticaEvent) => Promise<void>;
+    /**
+     * Request to the OpenAI server.
+     *
+     * @param source The source agent of the agent
+     * @param body The request body to the OpenAI server
+     * @returns Response from the OpenAI server
+     */
+    request: (source: AgenticaSource, body: Omit<OpenAI.ChatCompletionCreateParamsNonStreaming, "model">) => Promise<OpenAI.ChatCompletion>;
+    /**
+     * Initialize the agent.
+     */
+    initialize: () => Promise<void>;
+}

package/lib/structures/IAgenticaContext.js

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

package/lib/structures/IAgenticaContext.js.map

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

package/lib/structures/IAgenticaController.d.ts

@@ -0,0 +1,110 @@
+import { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse } from "@samchon/openapi";
+import { ILlmApplicationOfValidate, ILlmFunctionOfValidate } from "typia";
+/**
+ * Controller of the Nestia Agent.
+ *
+ * `IAgenticaController` is a type represents a controller of the
+ * {@link Agentica}, which serves a set of functions to be called
+ * by A.I. chatbot from LLM function calling.
+ *
+ * Also, `IAgenticaController` is an union type which can specify
+ * a subtype by checking the {@link protocol} property.
+ *
+ * - HTTP server: {@link IAgenticaController..IHttp}
+ * - TypeScript class: {@link IAgenticaController.IClass}
+ *
+ * @author Samchon
+ */
+export type IAgenticaController = IAgenticaController.IHttp | IAgenticaController.IClass;
+export declare namespace IAgenticaController {
+    /**
+     * HTTP controller.
+     *
+     * You can make it by {@link createHttpLlmApplication} function with
+     * the Swagger or OpenAPI document.
+     */
+    export interface IHttp extends IBase<"http", IHttpLlmApplication<"chatgpt">> {
+        /**
+         * Connection to the server.
+         *
+         * Connection to the API server including the URL and headers.
+         */
+        connection: IHttpConnection;
+        /**
+         * Executor of the API function.
+         *
+         * @param props Properties of the API function call
+         * @returns HTTP response of the API function call
+         */
+        execute?: (props: {
+            /**
+             * Connection to the server.
+             */
+            connection: IHttpConnection;
+            /**
+             * Application schema.
+             */
+            application: IHttpLlmApplication<"chatgpt">;
+            /**
+             * Function schema.
+             */
+            function: IHttpLlmFunction<"chatgpt">;
+            /**
+             * Arguments of the function calling.
+             *
+             * It is an object of key-value pairs of the API function's parameters.
+             * The property keys are composed by below rules:
+             *
+             * - parameter names
+             * - query parameter as an object type if exists
+             * - body parameter if exists
+             */
+            arguments: object;
+        }) => Promise<IHttpResponse>;
+    }
+    /**
+     * TypeScript class controller.
+     *
+     * You can make it by `typia.llm.application<App, Model>()` function.
+     *
+     * - https://typia.io/docs/llm/application
+     */
+    export interface IClass extends IBase<"class", ILlmApplicationOfValidate<"chatgpt">> {
+        /**
+         * Executor of the class function.
+         *
+         * Executor of the class function, by target class instance
+         * or callback function with given schema and arguments
+         * information.
+         */
+        execute: object | ((props: {
+            /**
+             * Target application schema.
+             */
+            application: ILlmApplicationOfValidate<"chatgpt">;
+            /**
+             * Target function schema.
+             */
+            function: ILlmFunctionOfValidate<"chatgpt">;
+            /**
+             * Arguments of the function calling.
+             */
+            arguments: object;
+        }) => Promise<unknown>);
+    }
+    interface IBase<Protocol, Application> {
+        /**
+         * Protocol discrminator.
+         */
+        protocol: Protocol;
+        /**
+         * Name of the controller.
+         */
+        name: string;
+        /**
+         * Application schema of function calling.
+         */
+        application: Application;
+    }
+    export {};
+}

package/lib/structures/IAgenticaController.js

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

package/lib/structures/IAgenticaController.js.map

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

package/lib/structures/IAgenticaEvent.d.ts

@@ -0,0 +1,191 @@
+import OpenAI from "openai";
+import { AgenticaSource } from "../typings/AgenticaSource";
+import { IAgenticaOperation } from "./IAgenticaOperation";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+/**
+ * Nestia A.I. chatbot event.
+ *
+ * `IAgenticaEvent` is an union type of all possible events that can
+ * be emitted by the A.I. chatbot of the {@link Agentica} class. You
+ * can discriminate the subtype by checking the {@link type} property.
+ *
+ * @author Samchon
+ */
+export type IAgenticaEvent = IAgenticaEvent.IInitialize | IAgenticaEvent.ISelect | IAgenticaEvent.ICancel | IAgenticaEvent.ICall | IAgenticaEvent.IExecute | IAgenticaEvent.IDescribe | IAgenticaEvent.IText | IAgenticaEvent.IRequest | IAgenticaEvent.IResponse;
+export declare namespace IAgenticaEvent {
+    export type Type = IAgenticaEvent["type"];
+    export type Mapper = {
+        initialize: IInitialize;
+        select: ISelect;
+        cancel: ICancel;
+        call: ICall;
+        execute: IExecute;
+        describe: IDescribe;
+        text: IText;
+        request: IRequest;
+        response: IResponse;
+    };
+    /**
+     * Event of initializing the chatbot.
+     */
+    export interface IInitialize extends IBase<"initialize"> {
+    }
+    /**
+     * Event of selecting a function to call.
+     */
+    export interface ISelect extends IBase<"select"> {
+        /**
+         * Selected operation.
+         *
+         * Operation that has been selected to prepare LLM function calling.
+         */
+        operation: IAgenticaOperation;
+        /**
+         * Reason of selecting the function.
+         *
+         * The A.I. chatbot will fill this property describing why the function
+         * has been selected.
+         */
+        reason: string;
+    }
+    /**
+     * Event of canceling a function calling.
+     */
+    export interface ICancel extends IBase<"cancel"> {
+        /**
+         * Selected operation to cancel.
+         *
+         * Operation that has been selected to prepare LLM function calling,
+         * but canceled due to no more required.
+         */
+        operation: IAgenticaOperation;
+        /**
+         * Reason of selecting the function.
+         *
+         * The A.I. chatbot will fill this property describing why the function
+         * has been cancelled.
+         *
+         * For reference, if the A.I. chatbot successfully completes the LLM
+         * function calling, the reason of the function cancellation will be
+         * "complete".
+         */
+        reason: string;
+    }
+    /**
+     * Event of calling a function.
+     */
+    export interface ICall extends IBase<"call"> {
+        /**
+         * ID of the tool calling.
+         */
+        id: string;
+        /**
+         * Target operation to call.
+         */
+        operation: IAgenticaOperation;
+        /**
+         * Arguments of the function calling.
+         *
+         * If you modify this {@link arguments} property, it actually modifies
+         * the backend server's request. Therefore, be careful when you're
+         * trying to modify this property.
+         */
+        arguments: object;
+    }
+    /**
+     * Event of function calling execution.
+     */
+    export interface IExecute extends IBase<"execute"> {
+        /**
+         * ID of the tool calling.
+         */
+        id: string;
+        /**
+         * Target operation had called.
+         */
+        operation: IAgenticaOperation;
+        /**
+         * Arguments of the function calling.
+         */
+        arguments: object;
+        /**
+         * Return value.
+         */
+        value: any;
+    }
+    /**
+     * Event of description.
+     *
+     * Event describing return values of LLM function callings.
+     */
+    export interface IDescribe extends IBase<"describe"> {
+        /**
+         * Executions of the LLM function calling.
+         *
+         * This prompt describes the return value of them.
+         */
+        executions: IAgenticaPrompt.IExecute[];
+        /**
+         * Description text.
+         */
+        text: string;
+    }
+    /**
+     * Event of text message.
+     */
+    export interface IText extends IBase<"text"> {
+        /**
+         * Role of the orator.
+         */
+        role: "assistant" | "user";
+        /**
+         * The text content.
+         */
+        text: string;
+    }
+    /**
+     * Request event of LLM provider API.
+     */
+    export interface IRequest extends IBase<"request"> {
+        /**
+         * The source agent of the request.
+         */
+        source: AgenticaSource;
+        /**
+         * Request body.
+         */
+        body: OpenAI.ChatCompletionCreateParamsNonStreaming;
+        /**
+         * Options for the request.
+         */
+        options?: OpenAI.RequestOptions | undefined;
+    }
+    /**
+     * Response event of LLM provider API.
+     */
+    export interface IResponse extends IBase<"response"> {
+        /**
+         * The source agent of the response.
+         */
+        source: AgenticaSource;
+        /**
+         * Request body.
+         */
+        body: OpenAI.ChatCompletionCreateParamsNonStreaming;
+        /**
+         * Options for the request.
+         */
+        options?: OpenAI.RequestOptions | undefined;
+        /**
+         * Return value from the LLM provider API.
+         */
+        value: OpenAI.ChatCompletion;
+    }
+    interface IBase<Type extends string> {
+        /**
+         * Discriminator type.
+         */
+        type: Type;
+    }
+    export {};
+}

package/lib/structures/IAgenticaEvent.js

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

package/lib/structures/IAgenticaEvent.js.map

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

package/lib/structures/IAgenticaExecutor.d.ts

@@ -0,0 +1,144 @@
+import { IAgenticaContext } from "./IAgenticaContext";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+/**
+ * Executor of the Agentic AI.
+ *
+ * `IAgenticaExecutor` represents an executor of the {@link Agentica},
+ * composing its internal agents to accomplish the Agentic AI through
+ * the LLM (Large Language Model) function calling.
+ *
+ * You can customize one of these internal agents by configuring
+ * properties of the `IAgenticaExecutor` type, and assigning it to the
+ * {@link IAgenticaConfig.executor} property. If you set the
+ * {@link initialize} as `null` value, the {@link Agentica} will skip
+ * the initialize process and directly go to the {@link select} process.
+ *
+ * By the way, when customizing the executor member, it would better to
+ * reference the guide documents of `@agentica/core`, and internal
+ * agents' implementation code. It's because if you take some mistake on
+ * the executor logic, it can entirely break the {@link Agentica}'s
+ * operation.
+ *
+ * @reference https://github.com/wrtnlabs/agentica?tab=readme-ov-file#principles
+ * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/agent/src/chatgpt/ChatGptAgent.ts
+ * @author Samchon
+ */
+export interface IAgenticaExecutor {
+    /**
+     * Initializer agent listing up functions.
+     *
+     * `initialize` agent is the first agent that {@link Agentica}
+     * would meet  which judges whether the user's conversation implies
+     * to call some function or not.
+     *
+     * And if the `initialize` agent judges the user's conversation
+     * implies to call some function, the `initialize` agent will
+     * call the {@link IAgenticaContext.initialize} function, and
+     * inform every functions enrolled in the {@link IAgenticaController}
+     * to the AI agent. And then, the `initialize` agent will not never
+     * be called again, and let {@link Agentica} to go to the next
+     * {@link select} agent.
+     *
+     * Otherwise the user's conversation does not imply the request of
+     * function calling, it would just work like plain chatbot, and just
+     * conversate with the user.
+     *
+     * By the way, if you wanna skip the `initialize` agent, you can
+     * do it by configuring the {@link IAgenticaConfig.executor} as
+     * `null` value. In that case, the `initialize` agent will never be
+     * called, and {@link Agentica} just starts from the {@link select}
+     * agent.
+     *
+     * @param ctx Context of the agent
+     * @returns List of prompts generated by the initializer
+     */
+    initialize: null | ((ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>);
+    /**
+     * Function selector agent.
+     *
+     * `Select` agent finds candidate functions to call from the
+     * conversation context with the user. And the candidate functions
+     * would be enrolled to the {@link IAgenticaContext.stack}, and the
+     * next {@link call} agent will perform the LLM (Large Language Model)
+     * function calling.
+     *
+     * Note that, the `select` agent does not perform the LLM function
+     * calling. It ends with just finding the candidate functions to call.
+     *
+     * By the way, if the `select` agent can't specify a certain function
+     * to call due to lack of conversation context or homogeneity between
+     * heterogeneous functions, how `select` agent works? In that case,
+     * `select` agent it will just enroll every candidate functions to
+     * the stack, and let the next {@link call} agent to determine the
+     * proper function to call. And then let {@link cancel} agent to erase
+     * the other candidate functions from the stack.
+     *
+     * Additionally, if `select` agent could not find any candidate
+     * function from the conversation context with user, it would just
+     * act like plain chatbot conversating with the user.
+     *
+     * @param ctx Context of the agent
+     * @returns List of prompts generated by the selector
+     */
+    select: (ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+    /**
+     * Function caller agent.
+     *
+     * `Call` agent performs the LLM (Large Language Model) function
+     * calling from the candidate functions enrolled in the
+     * {@link IAgenticaContext.stack}. And the scope of function calling
+     * is, not only just arguments filling, but also actual executing
+     * the function and returning the result.
+     *
+     * By the way, conversation context with user can be not enough to
+     * filling the arguments of the candidate functions. In that case,
+     * the `call` agent will ask the user to fill the missing arguments.
+     *
+     * Otherwise the cpnversation context is enough, so that succeeded
+     * to call some candidate functions, the `call` agent will step to
+     * the {@link describe} agent to explain the result of the function
+     * calling to the user as markdown content.
+     *
+     * @param ctx Context of the agent
+     * @returns List of prompts generated by the caller
+     * @warning Recommend not to customize, due to its validation
+     *          feedback strategy is working very well, and the `call`
+     *          agent is the most general topic which can be universally
+     *          applied to all domain fields.
+     */
+    call: (ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+    /**
+     * Describer agent of the function calling result.
+     *
+     * `Describe` agent explains the results of the function callings
+     * to the user as markdown content.
+     *
+     * @param ctx Context of the agent
+     * @param executes List of function calling results
+     * @returns List of prompts generated by the describer
+     */
+    describe: (ctx: IAgenticaContext, executes: IAgenticaPrompt.IExecute[]) => Promise<IAgenticaPrompt[]>;
+    /**
+     * Function canceler agent.
+     *
+     * `Cancel` agent erases the candidate functions from the
+     * {@link IAgenticaContext.stack} by analyzing the conversation
+     * context with the user.
+     *
+     * For reference, the first reason of the cancelation is explicit
+     * order from user to the previous requested function. For example,
+     * user had requested to send an email to the agent, but suddenly
+     * user says to cancel the email sending.
+     *
+     * The seconod reason n of the cancelation is the multiple candidate
+     * functions had been selected at once by the {@link select} agent
+     * due to lack of conversation context or homogeneity between the
+     * heterogeneous functions. And in the multiple candidate functions,
+     * one thing is clearly determined by the {@link call} agent, so that
+     * drop the other candidate functions.
+     *
+     * @param ctx Context of the agent
+     * @returns List of prompts generated by the canceler
+     */
+    cancel: (ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+}

package/lib/structures/IAgenticaExecutor.js

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

package/lib/structures/IAgenticaExecutor.js.map

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

package/lib/structures/IAgenticaOperation.d.ts

@@ -0,0 +1,48 @@
+import { IHttpLlmFunction } from "@samchon/openapi";
+import { ILlmFunctionOfValidate } from "typia";
+import { IAgenticaController } from "./IAgenticaController";
+/**
+ * Operation information in the Nestia Agent.
+ *
+ * `IAgenticaOperation` is a type represents an operation that would
+ * be selected by the A.I. chatbot of {@link Agentica} class to
+ * perform the LLM (Large Language Model) function calling.
+ *
+ * Also, it is an union type that is discriminated by the {@link protocol}
+ * property. If the protocol value is `http`, it means that the HTTP API
+ * operation would be called by the A.I. chatbot. Otherwise, if the protocol
+ * value is `class`, it means that the operation has come from a
+ * TypeScript class.
+ *
+ * @author Samchon
+ */
+export type IAgenticaOperation = IAgenticaOperation.IHttp | IAgenticaOperation.IClass;
+export declare namespace IAgenticaOperation {
+    /**
+     * HTTP API operation.
+     */
+    export type IHttp = IBase<"http", IAgenticaController.IHttp, IHttpLlmFunction<"chatgpt">>;
+    /**
+     * TypeScript class operation.
+     */
+    export type IClass = IBase<"class", IAgenticaController.IClass, ILlmFunctionOfValidate<"chatgpt">>;
+    interface IBase<Protocol, Application, Function> {
+        /**
+         * Protocol discriminator.
+         */
+        protocol: Protocol;
+        /**
+         * Belonged controller of the target function.
+         */
+        controller: Application;
+        /**
+         * Target function to call.
+         */
+        function: Function;
+        /**
+         * Identifier name.
+         */
+        name: string;
+    }
+    export {};
+}

package/lib/structures/IAgenticaOperation.js

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

package/lib/structures/IAgenticaOperation.js.map

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