@agentica/core 0.22.0 → 0.24.0

package/lib/utils/__map_take.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/__map_take.spec.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const __map_take_1 = require("./__map_take");
+describe("__map_take", () => {
+    describe("basic functionality", () => {
+        it("should generate value for new key", () => {
+            const map = new Map();
+            const generator = () => 42;
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result).toBe(42);
+            expect(map.get("test")).toBe(42);
+        });
+        it("should return existing value for existing key", () => {
+            const map = new Map();
+            map.set("test", 100);
+            const generator = () => 42;
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result).toBe(100);
+            expect(map.get("test")).toBe(100);
+        });
+    });
+    describe("various type tests", () => {
+        it("should handle object type", () => {
+            const map = new Map();
+            const generator = () => ({ value: 42 });
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result).toEqual({ value: 42 });
+            expect(map.get("test")).toEqual({ value: 42 });
+        });
+        it("should handle array type", () => {
+            const map = new Map();
+            const generator = () => [1, 2, 3];
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result).toEqual([1, 2, 3]);
+            expect(map.get("test")).toEqual([1, 2, 3]);
+        });
+        it("should handle function type", () => {
+            var _a;
+            const map = new Map();
+            const generator = () => () => 42;
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result()).toBe(42);
+            expect((_a = map.get("test")) === null || _a === void 0 ? void 0 : _a()).toBe(42);
+        });
+    });
+    describe("edge cases", () => {
+        it("should handle null key", () => {
+            const map = new Map();
+            const generator = () => "test";
+            const result = (0, __map_take_1.__map_take)(map, null, generator);
+            expect(result).toBe("test");
+            expect(map.get(null)).toBe("test");
+        });
+        it("should handle undefined key", () => {
+            const map = new Map();
+            const generator = () => "test";
+            const result = (0, __map_take_1.__map_take)(map, undefined, generator);
+            expect(result).toBe("test");
+            expect(map.get(undefined)).toBe("test");
+        });
+        it("should handle empty string key", () => {
+            const map = new Map();
+            const generator = () => "test";
+            const result = (0, __map_take_1.__map_take)(map, "", generator);
+            expect(result).toBe("test");
+            expect(map.get("")).toBe("test");
+        });
+    });
+    describe("generator function tests", () => {
+        it("should not call generator multiple times", () => {
+            const map = new Map();
+            let callCount = 0;
+            const generator = () => {
+                callCount++;
+                return 42;
+            };
+            (0, __map_take_1.__map_take)(map, "test", generator);
+            (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(callCount).toBe(1);
+        });
+        it("should handle generator throwing error", () => {
+            const map = new Map();
+            const generator = () => {
+                throw new Error("Generator error");
+            };
+            expect(() => (0, __map_take_1.__map_take)(map, "test", generator)).toThrow("Generator error");
+        });
+        it("should handle generator returning undefined", () => {
+            const map = new Map();
+            const generator = () => undefined;
+            const result = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result).toBeUndefined();
+            expect(map.get("test")).toBeUndefined();
+        });
+    });
+    describe("concurrency tests", () => {
+        it("should handle concurrent access to same key", () => {
+            const map = new Map();
+            const generator = () => 42;
+            const result1 = (0, __map_take_1.__map_take)(map, "test", generator);
+            const result2 = (0, __map_take_1.__map_take)(map, "test", generator);
+            expect(result1).toBe(42);
+            expect(result2).toBe(42);
+            expect(map.get("test")).toBe(42);
+        });
+    });
+});
+//# sourceMappingURL=__map_take.spec.js.map

package/lib/utils/__map_take.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__map_take.spec.js","sourceRoot":"","sources":["../../src/utils/__map_take.spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentica/core",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Agentic AI Library specialized in LLM Function Calling",
   "author": "Wrtn Technologies",
   "license": "MIT",

package/src/Agentica.ts

@@ -124,9 +124,17 @@ export class Agentica<Model extends ILlmSchema.Model> {
    * function calling information like {@link AgenticaExecuteHistory}.
    *
    * @param content The content to talk
+   * @param options Options
+   * @param options.abortSignal Abort signal
+   * @throws AbortError
    * @returns List of newly created chat prompts
    */
-  public async conversate(content: string | AgenticaUserInputHistory.Contents | Array<AgenticaUserInputHistory.Contents>): Promise<AgenticaHistory<Model>[]> {
+  public async conversate(
+    content: string | AgenticaUserInputHistory.Contents | Array<AgenticaUserInputHistory.Contents>,
+    options: {
+      abortSignal?: AbortSignal;
+    } = {},
+  ): Promise<AgenticaHistory<Model>[]> {
     const prompt: AgenticaUserInputHistory = createUserInputHistory({
       contents: Array.isArray(content)
         ? content
@@ -147,6 +155,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
     const newbie: AgenticaHistory<Model>[] = await this.executor_(
       this.getContext({
         prompt,
+        abortSignal: options.abortSignal,
         usage: this.token_usage_,
       }),
     );
@@ -219,6 +228,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
   public getContext(props: {
     prompt: AgenticaUserInputHistory;
     usage: AgenticaTokenUsage;
+    abortSignal?: AbortSignal;
   }): AgenticaContext<Model> {
     const dispatch = async (event: AgenticaEvent<Model>) => this.dispatch(event);
     return {
@@ -231,6 +241,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
       stack: this.stack_,
       ready: () => this.ready_,
       prompt: props.prompt,
+      abortSignal: props.abortSignal,
 
       // HANDLERS
       dispatch: async event => this.dispatch(event),
@@ -246,7 +257,10 @@ export class Agentica<Model extends ILlmSchema.Model> {
               include_usage: true,
             },
           },
-          options: this.props.vendor.options,
+          options: {
+            ...this.props.vendor.options,
+            signal: props.abortSignal,
+          },
         });
         await dispatch(event);
 

package/src/MicroAgentica.ts

@@ -1,5 +1,6 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
+import type { AgenticaOperation } from "./context/AgenticaOperation";
 import type { AgenticaOperationCollection } from "./context/AgenticaOperationCollection";
 import type { MicroAgenticaContext } from "./context/MicroAgenticaContext";
 import type { AgenticaRequestEvent } from "./events/AgenticaRequestEvent";
@@ -157,6 +158,18 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
     return this.props.vendor;
   }
 
+  /**
+   * Get operations.
+   *
+   * Get list of operations, which has capsuled the pair of controller
+   * and function from the {@link getControllers controllers}.
+   *
+   * @returns List of operations
+   */
+  public getOperations(): ReadonlyArray<AgenticaOperation<Model>> {
+    return this.operations_.array;
+  }
+
   /**
    * Get controllers.
    *

package/src/context/AgenticaContext.ts

@@ -87,6 +87,11 @@ export interface AgenticaContext<Model extends ILlmSchema.Model> {
    */
   prompt: AgenticaUserInputHistory;
 
+  /**
+   * Abort signal.
+   */
+  abortSignal?: AbortSignal;
+
   /**
    * Whether the agent is ready.
    *

package/src/functional/assertHttpController.ts

@@ -0,0 +1,112 @@
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmSchema, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
+
+import { HttpLlm, OpenApi } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an HTTP controller with type assertion.
+ *
+ * Create an {@link IAgenticaController.IHttp} instance which represents
+ * the HTTP controller from the given Swagger/OpenAPI document and the
+ * target LLM model with connection information.
+ *
+ * By the way, even though this `assertHttpController` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will throw an error with detailed type error tracing information.
+ *
+ * @param props Properties to create the HTTP controller instance
+ * @returns HTTP controller instance
+ * @throws {@link TypeGuardError} when the given document is invalid
+ * @author Samchon
+ */
+export function assertHttpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Target LLM model.
+   */
+  model: Model;
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<Model>>;
+
+  /**
+   * 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<Model>;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction<Model>;
+
+    /**
+     * 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>;
+}): IAgenticaController.IHttp<Model> {
+  const document = OpenApi.convert(typia.assert<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  >(props.document));
+  return {
+    protocol: "http",
+    name: props.name,
+    application: HttpLlm.application({
+      model: props.model,
+      document,
+      options: props.options,
+    }),
+    execute: props.execute,
+    connection: props.connection,
+  };
+}

package/src/functional/assertHttpLlmApplication.ts

@@ -28,6 +28,7 @@ import typia from "typia";
  * @returns  HTTP LLM application instance
  * @throws {@link TypeGuardError} when the given document is invalid
  * @author Samchon
+ * @deprecated Use {@link assertHttpController} instead.
  */
 export function assertHttpLlmApplication<
   Model extends ILlmSchema.Model,

package/src/functional/assertMcpController.ts

@@ -19,7 +19,7 @@ import type { IAgenticaController } from "../structures/IAgenticaController";
  * @param props.model Model schema of the LLM function calling.
  * @param props.options Options to create the MCP controller.
  * @returns MCP LLM application instance
- * @author Samchon
+ * @author sunrabbit123
  */
 export async function assertMcpController<Model extends ILlmSchema.Model>(props: {
   name: string;
@@ -42,7 +42,6 @@ export async function assertMcpController<Model extends ILlmSchema.Model>(props:
     protocol: "mcp",
     name: props.name,
     client: props.client,
-
     application,
   };
 }

package/src/functional/validateHttpController.ts

@@ -0,0 +1,118 @@
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmSchema, IValidation, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
+
+import { HttpLlm, OpenApi } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an HTTP controller with type validation.
+ *
+ * Create an {@link IAgenticaController.IHttp} instance which represents
+ * the HTTP controller from the given Swagger/OpenAPI document and the
+ * target LLM model with connection information.
+ *
+ * By the way, even though this `validateHttpController` 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 controller instance
+ * @returns Validation result of the HTTP controller composition
+ * @author Samchon
+ */
+export function validateHttpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Target LLM model.
+   */
+  model: Model;
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<Model>>;
+
+  /**
+   * 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<Model>;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction<Model>;
+
+    /**
+     * 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>;
+}): IValidation<IAgenticaController.IHttp<Model>> {
+  const inspect = typia.validate<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  >(props.document);
+  if (inspect.success === false) {
+    return inspect;
+  }
+  return {
+    success: true,
+    data: {
+      protocol: "http",
+      name: props.name,
+      application: HttpLlm.application({
+        model: props.model,
+        document: OpenApi.convert(inspect.data),
+        options: props.options,
+      }),
+      execute: props.execute,
+      connection: props.connection,
+    },
+  };
+}

package/src/functional/validateHttpLlmApplication.ts

@@ -29,6 +29,7 @@ import typia from "typia";
  * @param props Properties to create the HTTP LLM application instance
  * @returns Validation result of the HTTP LLM application composition
  * @author Samchon
+ * @deprecated Use {@link validateHttpController} instead.
  */
 export function validateHttpLlmApplication<
   Model extends ILlmSchema.Model,
@@ -67,7 +68,6 @@ export function validateHttpLlmApplication<
   if (inspect.success === false) {
     return inspect;
   }
-
   return {
     success: true,
     data: HttpLlm.application({

package/src/functional/validateMcpController.ts

@@ -0,0 +1,56 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
+import type { ILlmSchema, IMcpLlmApplication, IMcpTool, IValidation } from "@samchon/openapi";
+
+import { McpLlm } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an MCP controller with type validation.
+ *
+ * Create an {@link IAgenticaController.IMcp} instance which represents
+ * an MCP (Model Context Protocol) controller with LLM function calling
+ * schemas and client connection.
+ *
+ * @param props Properties to create the MCP controller
+ * @param props.name Name of the MCP implementation.
+ * @param props.client Client connection to the MCP implementation.
+ * @param props.model Model schema of the LLM function calling.
+ * @param props.options Options to create the MCP controller.
+ * @returns MCP LLM application instance
+ * @author SunRabbit
+ */
+export async function validateMcpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  name: string;
+  client: Client;
+  model: Model;
+  options?: Partial<IMcpLlmApplication.IOptions<Model>>;
+}): Promise<IValidation<IAgenticaController.IMcp<Model>>> {
+  // for peerDependencies
+  const { ListToolsResultSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+  // get list of tools
+  const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
+  const inspect = typia.validate<Array<IMcpTool>>(tools);
+  if (inspect.success === false) {
+    return inspect;
+  }
+
+  const application: IMcpLlmApplication<Model> = McpLlm.application<Model>({
+    model: props.model,
+    tools: typia.assert<Array<IMcpTool>>(tools),
+  });
+
+  return {
+    success: true,
+    data: {
+      protocol: "mcp",
+      name: props.name,
+      client: props.client,
+      application,
+    },
+  };
+}

package/src/histories/AgenticaUserInputHistory.ts

@@ -1,3 +1,5 @@
+import type typia from "typia";
+
 import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
 
 import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
@@ -35,7 +37,7 @@ export namespace AgenticaUserInputHistory {
         /**
          * Either a URL of the image or the base64 encoded image data.
          */
-        url: string;
+        url: string & typia.tags.Format<"url">;
         /**
          * Specifies the detail level of the image. Learn more in the
          * [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
@@ -46,6 +48,8 @@ export namespace AgenticaUserInputHistory {
 
     /**
      * Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
+     *
+     * Note: we not recommend it because audio input data only support base64 so it's too big data.
      */
     export interface InputAudio extends ContentsBase<"input_audio"> {
       input_audio: {
@@ -64,24 +68,26 @@ export namespace AgenticaUserInputHistory {
     /**
      * Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text
      * generation.
+     *
+     * Note: we recommend use `file_id` instead of `file_data` because it's too big data.
      */
     export interface File extends ContentsBase<"file"> {
       file: {
         /**
-         * The base64 encoded file data, used when passing the file to the model as a
-         * string.
+         * The ID of an uploaded file to use as input.
          */
-        file_data?: string;
-
+        file_id: string;
+      } | {
         /**
-         * The ID of an uploaded file to use as input.
+         * The base64 encoded file data, used when passing the file to the model as a
+         * string.
          */
-        file_id?: string;
+        file_data: string;
 
         /**
          * The name of the file, used when passing the file to the model as a string.
          */
-        filename?: string;
+        filename: string;
       };
     }
   }

package/src/index.ts

@@ -22,9 +22,12 @@ export * from "./events/MicroAgenticaEvent";
 
 export * as factory from "./factory";
 
+export * from "./functional/assertHttpController";
 export * from "./functional/assertHttpLlmApplication";
 export * from "./functional/assertMcpController";
+export * from "./functional/validateHttpController";
 export * from "./functional/validateHttpLlmApplication";
+export * from "./functional/validateMcpController";
 // @TODO: implement validateMcpLlmApplication
 
 export * from "./histories/AgenticaCancelHistory";