@aigne/core 1.72.0 → 1.74.0-beta

package/lib/cjs/aigne/aigne.d.ts

@@ -1,335 +0,0 @@
-import { AIGNEObserver } from "@aigne/observability-api";
-import type { Agent, AgentResponse, AgentResponseStream, Message } from "../agents/agent.js";
-import type { ChatModel } from "../agents/chat-model.js";
-import type { ImageModel } from "../agents/image-model.js";
-import type { UserAgent } from "../agents/user-agent.js";
-import { type LoadOptions } from "../loader/index.js";
-import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
-import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
-import type { AIGNECLIAgents, AIGNEMetadata } from "./type.js";
-import type { ContextLimits } from "./usage.js";
-/**
- * Options for the AIGNE class.
- */
-export interface AIGNEOptions {
-    /**
-     * Optional root directory for this AIGNE instance.
-     * This is used to resolve relative paths for agents and skills.
-     */
-    rootDir?: string;
-    /**
-     * The name of the AIGNE instance.
-     */
-    name?: string;
-    /**
-     * The description of the AIGNE instance.
-     */
-    description?: string;
-    /**
-     * Global model to use for all agents not specifying a model.
-     */
-    model?: ChatModel;
-    /**
-     * Optional image model to use for image processing tasks.
-     */
-    imageModel?: ImageModel;
-    /**
-     * Skills to use for the AIGNE instance.
-     */
-    skills?: Agent[];
-    /**
-     * Agents to use for the AIGNE instance.
-     */
-    agents?: Agent[];
-    mcpServer?: {
-        agents?: Agent[];
-    };
-    cli?: AIGNECLIAgents;
-    /**
-     * Limits for the AIGNE instance, such as timeout, max tokens, max invocations, etc.
-     */
-    limits?: ContextLimits;
-    /**
-     * Observer for the AIGNE instance.
-     */
-    observer?: AIGNEObserver;
-    metadata?: AIGNEMetadata;
-}
-/**
- * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
- * It serves as the central coordination point for agent interactions, message passing, and execution flow.
- *
- * @example
- * Here's a simple example of how to use AIGNE:
- * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
- *
- * @example
- * Here's an example of how to use AIGNE with streaming response:
- * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
- */
-export declare class AIGNE<U extends UserContext = UserContext> {
-    /**
-     * Loads an AIGNE instance from a directory containing an aigne.yaml file and agent definitions.
-     * This static method provides a convenient way to initialize an AIGNE system from configuration files.
-     *
-     * @param path - Path to the directory containing the aigne.yaml file.
-     * @param options - Options to override the loaded configuration.
-     * @returns A fully initialized AIGNE instance with configured agents and skills.
-     */
-    static load(path: string, options?: Omit<AIGNEOptions, keyof LoadOptions> & LoadOptions): Promise<AIGNE>;
-    /**
-     * Creates a new AIGNE instance with the specified options.
-     *
-     * @param options - Configuration options for the AIGNE instance including name, description, model, and agents.
-     */
-    constructor(options?: AIGNEOptions);
-    /**
-     * Optional root directory for this AIGNE instance.
-     */
-    rootDir?: string;
-    /**
-     * Optional name identifier for this AIGNE instance.
-     */
-    name?: string;
-    /**
-     * Optional description of this AIGNE instance's purpose or functionality.
-     */
-    description?: string;
-    /**
-     * Global model to use for all agents that don't specify their own model.
-     */
-    model?: ChatModel;
-    /**
-     * Optional image model to use for image processing tasks.
-     */
-    imageModel?: ImageModel;
-    /**
-     * Usage limits applied to this AIGNE instance's execution.
-     */
-    limits?: ContextLimits;
-    /**
-     * Message queue for handling inter-agent communication.
-     *
-     * @hidden
-     */
-    readonly messageQueue: MessageQueue;
-    /**
-     * Collection of all context IDs created by this AIGNE instance.
-     */
-    readonly contextIds: Set<string>;
-    /**
-     * Collection of skill agents available to this AIGNE instance.
-     * Provides indexed access by skill name.
-     */
-    readonly skills: Agent<any, any>[] & {
-        [key: string]: Agent<any, any>;
-    };
-    /**
-     * Collection of primary agents managed by this AIGNE instance.
-     * Provides indexed access by agent name.
-     */
-    readonly agents: Agent<any, any>[] & {
-        [key: string]: Agent<any, any>;
-    };
-    readonly mcpServer: {
-        agents: Agent<any, any>[] & {
-            [key: string]: Agent<any, any>;
-        };
-    };
-    readonly cli: AIGNECLIAgents;
-    /**
-     * Observer for the AIGNE instance.
-     */
-    readonly observer?: AIGNEObserver;
-    /**
-     * Metadata for the AIGNE instance.
-     */
-    readonly metadata: AIGNEMetadata;
-    /**
-     * Adds one or more agents to this AIGNE instance.
-     * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.
-     *
-     * @param agents - One or more Agent instances to add to this AIGNE.
-     */
-    addAgent(...agents: Agent[]): void;
-    /**
-     * Creates a new execution context for this AIGNE instance.
-     * Contexts isolate state for different flows or conversations.
-     *
-     * @returns A new AIGNEContext instance bound to this AIGNE.
-     */
-    newContext(options?: Partial<Pick<Context, "userContext" | "memories">>): AIGNEContext;
-    /**
-     * Creates a user agent for consistent interactions with a specified agent.
-     * This method allows you to create a wrapper around an agent for repeated invocations.
-     *
-     * @param agent - Target agent to be wrapped for consistent invocation
-     * @returns A user agent instance that provides a convenient interface for interacting with the target agent
-     *
-     * @example
-     * Here's an example of how to create a user agent and invoke it consistently:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-user-agent}
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>): UserAgent<I, O>;
-    /**
-     * Invokes an agent with a message and returns both the output and the active agent.
-     * This overload is useful when you need to track which agent was ultimately responsible for generating the response.
-     *
-     * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent
-     * @param options.returnActiveAgent - Must be true to return the final active agent
-     * @param options.streaming - Must be false to return a response stream
-     * @returns A promise resolving to a tuple containing the agent's response and the final active agent
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
-        returnActiveAgent: true;
-        streaming?: false;
-    }): Promise<[O, Agent]>;
-    /**
-     * Invokes an agent with a message and returns both a stream of the response and the active agent.
-     * This overload is useful when you need streaming responses while also tracking which agent provided them.
-     *
-     * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent
-     * @param options.returnActiveAgent - Must be true to return the final active agent
-     * @param options.streaming - Must be true to return a response stream
-     * @returns A promise resolving to a tuple containing the agent's response stream and a promise for the final agent
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
-        returnActiveAgent: true;
-        streaming: true;
-    }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
-    /**
-     * Invokes an agent with a message and returns just the output.
-     * This is the standard way to invoke an agent when you only need the response.
-     *
-     * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent
-     * @param options - Optional configuration parameters for the invocation
-     * @returns A promise resolving to the agent's complete response
-     *
-     * @example
-     * Here's a simple example of how to invoke an agent:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options?: InvokeOptions<U> & {
-        returnActiveAgent?: false;
-        streaming?: false;
-    }): Promise<O>;
-    /**
-     * Invokes an agent with a message and returns a stream of the response.
-     * This allows processing the response incrementally as it's being generated.
-     *
-     * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent
-     * @param options - Configuration with streaming enabled to receive incremental response chunks
-     * @returns A promise resolving to a stream of the agent's response that can be consumed incrementally
-     *
-     * @example
-     * Here's an example of how to invoke an agent with streaming response:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
-        returnActiveAgent?: false;
-        streaming: true;
-    }): Promise<AgentResponseStream<O>>;
-    /**
-     * General implementation signature that handles all overload cases.
-     * This unified signature supports all the different invocation patterns defined by the overloads.
-     *
-     * @param agent - Target agent to invoke or wrap
-     * @param message - Optional input message to send to the agent
-     * @param options - Optional configuration parameters for the invocation
-     * @returns Either a UserAgent (when no message provided) or a promise resolving to the agent's response
-     * with optional active agent information based on the provided options
-     */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I & Message, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
-    /**
-     * Publishes a message to the message queue for inter-agent communication.
-     * This method broadcasts a message to all subscribers of the specified topic(s).
-     * It creates a new context internally and delegates to the context's publish method.
-     *
-     * @param topic - The topic or array of topics to publish the message to
-     * @param payload - The message payload to be delivered to subscribers
-     * @param options - Optional configuration parameters for the publish operation
-     *
-     * @example
-     * Here's an example of how to publish a message:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
-     */
-    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message, options?: InvokeOptions<U>): void;
-    /**
-     * Subscribes to receive the next message on a specific topic.
-     * This overload returns a Promise that resolves with the next message published to the topic.
-     * It's useful for one-time message handling or when using async/await patterns.
-     *
-     * @param topic - The topic to subscribe to
-     * @returns A Promise that resolves with the next message payload published to the specified topic
-     *
-     * @example
-     * Here's an example of how to subscribe to a topic and receive the next message:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
-     */
-    subscribe(topic: string | string[], listener?: undefined): Promise<MessagePayload>;
-    /**
-     * Subscribes to messages on a specific topic with a listener callback.
-     * This overload registers a listener function that will be called for each message published to the topic.
-     * It's useful for continuous message handling or event-driven architectures.
-     *
-     * @param topic - The topic to subscribe to
-     * @param listener - Callback function that will be invoked when messages arrive on the specified topic
-     * @returns An Unsubscribe function that can be called to cancel the subscription
-     *
-     * @example
-     * Here's an example of how to subscribe to a topic with a listener:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-subscribe-topic}
-     */
-    subscribe(topic: string | string[], listener: MessageQueueListener): Unsubscribe;
-    /**
-     * Generic subscribe signature that handles both Promise and listener patterns.
-     * This is the implementation signature that supports both overloaded behaviors.
-     *
-     * @param topic - The topic to subscribe to
-     * @param listener - Optional callback function
-     * @returns Either a Promise for the next message or an Unsubscribe function
-     */
-    subscribe(topic: string | string[], listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
-    /**
-     * Unsubscribes a listener from a specific topic in the message queue.
-     * This method stops a previously registered listener from receiving further messages.
-     * It should be called when message processing is complete or when the component is no longer interested
-     * in messages published to the specified topic.
-     *
-     * @param topic - The topic to unsubscribe from
-     * @param listener - The listener function that was previously subscribed to the topic
-     *
-     * @example
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-subscribe-topic}
-     */
-    unsubscribe(topic: string | string[], listener: MessageQueueListener): void;
-    /**
-     * Gracefully shuts down the AIGNE instance and all its agents and skills.
-     * This ensures proper cleanup of resources before termination.
-     *
-     * @returns A promise that resolves when shutdown is complete.
-     *
-     * @example
-     * Here's an example of shutdown an AIGNE instance:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-shutdown}
-     */
-    shutdown(): Promise<void>;
-    /**
-     * Asynchronous dispose method for the AIGNE instance.
-     *
-     * @example
-     * Here's an example of using async dispose:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-shutdown-using}
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    /**
-     * Initializes handlers for process exit events to ensure clean shutdown.
-     * This registers handlers for SIGINT/SIGTERM to properly terminate all agents.
-     * Note: 'exit' event cannot run async code, so we handle cleanup in signal handlers.
-     */
-    private initProcessExitHandler;
-}

package/lib/cjs/aigne/aigne.js

@@ -1,248 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIGNE = void 0;
-const observability_api_1 = require("@aigne/observability-api");
-const zod_1 = require("zod");
-const index_js_1 = require("../loader/index.js");
-const type_utils_js_1 = require("../utils/type-utils.js");
-const context_js_1 = require("./context.js");
-const message_queue_js_1 = require("./message-queue.js");
-/**
- * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
- * It serves as the central coordination point for agent interactions, message passing, and execution flow.
- *
- * @example
- * Here's a simple example of how to use AIGNE:
- * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
- *
- * @example
- * Here's an example of how to use AIGNE with streaming response:
- * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
- */
-class AIGNE {
-    /**
-     * Loads an AIGNE instance from a directory containing an aigne.yaml file and agent definitions.
-     * This static method provides a convenient way to initialize an AIGNE system from configuration files.
-     *
-     * @param path - Path to the directory containing the aigne.yaml file.
-     * @param options - Options to override the loaded configuration.
-     * @returns A fully initialized AIGNE instance with configured agents and skills.
-     */
-    static async load(path, options = {}) {
-        const { agents = [], skills = [], model, imageModel, ...aigne } = await (0, index_js_1.load)(path, options);
-        return new AIGNE({
-            ...aigne,
-            ...options,
-            model,
-            imageModel,
-            agents: agents.concat(options?.agents ?? []),
-            skills: skills.concat(options?.skills ?? []),
-            metadata: options?.metadata,
-        });
-    }
-    /**
-     * Creates a new AIGNE instance with the specified options.
-     *
-     * @param options - Configuration options for the AIGNE instance including name, description, model, and agents.
-     */
-    constructor(options) {
-        if (options)
-            (0, type_utils_js_1.checkArguments)("AIGNE", aigneOptionsSchema, options);
-        this.rootDir = options?.rootDir;
-        this.name = options?.name;
-        this.description = options?.description;
-        this.model = options?.model;
-        this.imageModel = options?.imageModel;
-        this.limits = options?.limits;
-        this.observer =
-            process.env.AIGNE_OBSERVABILITY_DISABLED === "true"
-                ? undefined
-                : (options?.observer ?? new observability_api_1.AIGNEObserver());
-        if (options?.skills?.length)
-            this.skills.push(...options.skills);
-        if (options?.agents?.length)
-            this.addAgent(...options.agents);
-        if (options?.mcpServer?.agents?.length)
-            this.mcpServer.agents.push(...options.mcpServer.agents);
-        this.cli = options?.cli ?? {};
-        this.observer?.serve();
-        this.initProcessExitHandler();
-        this.metadata = options?.metadata ?? {};
-    }
-    /**
-     * Optional root directory for this AIGNE instance.
-     */
-    rootDir;
-    /**
-     * Optional name identifier for this AIGNE instance.
-     */
-    name;
-    /**
-     * Optional description of this AIGNE instance's purpose or functionality.
-     */
-    description;
-    /**
-     * Global model to use for all agents that don't specify their own model.
-     */
-    model;
-    /**
-     * Optional image model to use for image processing tasks.
-     */
-    imageModel;
-    /**
-     * Usage limits applied to this AIGNE instance's execution.
-     */
-    limits;
-    /**
-     * Message queue for handling inter-agent communication.
-     *
-     * @hidden
-     */
-    messageQueue = new message_queue_js_1.MessageQueue();
-    /**
-     * Collection of all context IDs created by this AIGNE instance.
-     */
-    contextIds = new Set();
-    /**
-     * Collection of skill agents available to this AIGNE instance.
-     * Provides indexed access by skill name.
-     */
-    skills = (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name));
-    /**
-     * Collection of primary agents managed by this AIGNE instance.
-     * Provides indexed access by agent name.
-     */
-    agents = (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name));
-    mcpServer = {
-        agents: (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name)),
-    };
-    cli = {};
-    /**
-     * Observer for the AIGNE instance.
-     */
-    observer;
-    /**
-     * Metadata for the AIGNE instance.
-     */
-    metadata = {};
-    /**
-     * Adds one or more agents to this AIGNE instance.
-     * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.
-     *
-     * @param agents - One or more Agent instances to add to this AIGNE.
-     */
-    addAgent(...agents) {
-        (0, type_utils_js_1.checkArguments)("AIGNE.addAgent", aigneAddAgentArgsSchema, agents);
-        for (const agent of agents) {
-            this.agents.push(agent);
-            agent.attach(this);
-        }
-    }
-    /**
-     * Creates a new execution context for this AIGNE instance.
-     * Contexts isolate state for different flows or conversations.
-     *
-     * @returns A new AIGNEContext instance bound to this AIGNE.
-     */
-    newContext(options) {
-        const context = new context_js_1.AIGNEContext(this);
-        if (options?.userContext)
-            context.userContext = options.userContext;
-        if (options?.memories)
-            context.memories = options.memories;
-        return context;
-    }
-    invoke(agent, message, options) {
-        this.observer?.serve();
-        const context = new context_js_1.AIGNEContext(this);
-        return context.invoke(agent, message, { ...options, newContext: false });
-    }
-    /**
-     * Publishes a message to the message queue for inter-agent communication.
-     * This method broadcasts a message to all subscribers of the specified topic(s).
-     * It creates a new context internally and delegates to the context's publish method.
-     *
-     * @param topic - The topic or array of topics to publish the message to
-     * @param payload - The message payload to be delivered to subscribers
-     * @param options - Optional configuration parameters for the publish operation
-     *
-     * @example
-     * Here's an example of how to publish a message:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
-     */
-    publish(topic, payload, options) {
-        this.observer?.serve();
-        return new context_js_1.AIGNEContext(this).publish(topic, payload, options);
-    }
-    subscribe(topic, listener) {
-        return this.messageQueue.subscribe(topic, listener);
-    }
-    /**
-     * Unsubscribes a listener from a specific topic in the message queue.
-     * This method stops a previously registered listener from receiving further messages.
-     * It should be called when message processing is complete or when the component is no longer interested
-     * in messages published to the specified topic.
-     *
-     * @param topic - The topic to unsubscribe from
-     * @param listener - The listener function that was previously subscribed to the topic
-     *
-     * @example
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-subscribe-topic}
-     */
-    unsubscribe(topic, listener) {
-        this.messageQueue.unsubscribe(topic, listener);
-    }
-    /**
-     * Gracefully shuts down the AIGNE instance and all its agents and skills.
-     * This ensures proper cleanup of resources before termination.
-     *
-     * @returns A promise that resolves when shutdown is complete.
-     *
-     * @example
-     * Here's an example of shutdown an AIGNE instance:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-shutdown}
-     */
-    async shutdown() {
-        // Close observer first to flush any pending traces
-        await this.observer?.close(Array.from(this.contextIds));
-        for (const tool of this.skills) {
-            await tool.shutdown();
-        }
-        for (const agent of this.agents) {
-            await agent.shutdown();
-        }
-    }
-    /**
-     * Asynchronous dispose method for the AIGNE instance.
-     *
-     * @example
-     * Here's an example of using async dispose:
-     * {@includeCode ../../test/aigne/aigne.test.ts#example-shutdown-using}
-     */
-    async [Symbol.asyncDispose]() {
-        await this.shutdown();
-    }
-    /**
-     * Initializes handlers for process exit events to ensure clean shutdown.
-     * This registers handlers for SIGINT/SIGTERM to properly terminate all agents.
-     * Note: 'exit' event cannot run async code, so we handle cleanup in signal handlers.
-     */
-    initProcessExitHandler() {
-        const originalExit = process.exit;
-        // @ts-ignore
-        process.exit = (...args) => {
-            this.shutdown().finally(() => originalExit(...args));
-        };
-        const shutdownAndExit = () => this.shutdown().finally(() => originalExit(0));
-        process.on("SIGINT", shutdownAndExit);
-    }
-}
-exports.AIGNE = AIGNE;
-const aigneOptionsSchema = zod_1.z.object({
-    model: zod_1.z.custom().optional(),
-    imageModel: zod_1.z.custom().optional(),
-    skills: zod_1.z.array(zod_1.z.custom()).optional(),
-    agents: zod_1.z.array(zod_1.z.custom()).optional(),
-    observer: zod_1.z.custom().optional(),
-});
-const aigneAddAgentArgsSchema = zod_1.z.array(zod_1.z.custom());