@aigne/core 1.14.0 → 1.16.0

package/lib/{cjs/models → dts/agents}/chat-model.d.ts

@@ -1,6 +1,6 @@
-import { Agent, type AgentProcessResult, type Message } from "../agents/agent.js";
 import type { Context } from "../aigne/context.js";
 import type { PromiseOrValue } from "../utils/type-utils.js";
+import { Agent, type AgentProcessResult, type Message } from "./agent.js";
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -10,19 +10,19 @@ import type { PromiseOrValue } from "../utils/type-utils.js";
  *
  * @example
  * Here's how to implement a custom ChatModel:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example showing streaming response with readable stream:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming}
  *
  * @example
  * Here's an example showing streaming response with async generator:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming-async-generator}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming-async-generator}
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     constructor();
@@ -44,6 +44,17 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
         supportsParallelToolCalls: boolean;
     };
     private validateToolNames;
+    /**
+     * Normalizes tool names to ensure compatibility with language models
+     *
+     * This method converts tool names to a format that complies with model requirements
+     * by replacing hyphens and whitespace characters with underscores. The normalized
+     * names are used for tool calls while preserving the original names for reference.
+     *
+     * @param name - The original tool name to normalize
+     * @returns A promise that resolves to the normalized tool name
+     */
+    protected normalizeToolName(name: string): Promise<string>;
     /**
      * Performs preprocessing operations before handling input
      *
@@ -53,7 +64,7 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
      * @param context Execution context
      * @throws Error if token usage exceeds maximum limit
      */
-    protected preprocess(input: ChatModelInput, context: Context): void;
+    protected preprocess(input: ChatModelInput, context: Context): Promise<void>;
     /**
      * Performs postprocessing operations after handling output
      *
@@ -94,11 +105,11 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
  *
  * @example
  * Here's a basic ChatModel input example:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example with tool calling:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelInput extends Message {
     /**
@@ -213,7 +224,7 @@ export type ChatModelInputResponseFormat = {
  *
  * @example
  * Here's an example showing how to use tools:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelInputTool {
     /**
@@ -249,7 +260,7 @@ export interface ChatModelInputTool {
  *
  * @example
  * Here's an example showing how to use tools:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     type: "function";
@@ -296,11 +307,11 @@ export interface ChatModelOptions {
  *
  * @example
  * Here's a basic output example:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelOutput extends Message {
     /**
@@ -331,7 +342,7 @@ export interface ChatModelOutput extends Message {
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelOutputToolCall {
     /**

package/lib/dts/agents/guide-rail-agent.d.ts

@@ -0,0 +1,62 @@
+import type { Agent, AgentOptions, Message } from "./agent.js";
+/**
+ * Input interface for GuideRail agents
+ *
+ * GuideRail agents receive both input and expected output, allowing them to
+ * validate, transform, or control the flow of messages between other agents.
+ */
+export interface GuideRailAgentInput extends Message {
+    /**
+     * The input data to be processed
+     *
+     * This is the original message that would be sent to the target agent
+     */
+    input?: unknown;
+    /**
+     * The expected output data
+     *
+     * This is what the target agent is expected to produce, allowing
+     * the GuideRail agent to validate or transform the data flow
+     */
+    output?: unknown;
+}
+/**
+ * Output interface for GuideRail agents
+ *
+ * GuideRail agents can either allow the process to continue or abort it with a reason.
+ * This provides a mechanism for enforcing rules, validating data, and controlling
+ * the execution flow of the agent system.
+ */
+export interface GuideRailAgentOutput extends Message {
+    /**
+     * Whether to abort the current process
+     *
+     * When true, the agent system should stop the current execution flow
+     * and prevent further processing based on this input/output pair
+     *
+     * @default false
+     */
+    abort?: boolean;
+    /**
+     * Reason for aborting the process
+     *
+     * When abort is true, this provides a human-readable explanation
+     * for why the process was stopped
+     */
+    reason?: string;
+}
+/**
+ * GuideRail agent type definition
+ *
+ * GuideRail agents act as validators, transformers, or controllers for the message
+ * flow between agents. They can enforce rules, perform safety checks, ensure data
+ * quality, or implement business logic validations.
+ *
+ * Use GuideRail agents when you need to:
+ * - Validate inputs or outputs against specific criteria
+ * - Enforce security or safety policies
+ * - Implement business rules that control agent interactions
+ * - Monitor and audit agent behavior
+ */
+export type GuideRailAgent = Agent<GuideRailAgentInput, GuideRailAgentOutput>;
+export declare const guideRailAgentOptions: AgentOptions<GuideRailAgentInput, GuideRailAgentOutput>;

package/lib/dts/aigne/aigne.d.ts

@@ -1,6 +1,7 @@
 import { Agent, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
+import { ChatModel } from "../agents/chat-model.js";
 import type { UserAgent } from "../agents/user-agent.js";
-import { ChatModel } from "../models/chat-model.js";
+import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type InvokeOptions } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
 import type { ContextLimits } from "./usage.js";
@@ -54,7 +55,7 @@ export declare class AIGNE {
      * @param options - Options to override the loaded configuration.
      * @returns A fully initialized AIGNE instance with configured agents and skills.
      */
-    static load(path: string, options?: AIGNEOptions): Promise<AIGNE>;
+    static load(path: string, options: AIGNEOptions & Pick<LoadOptions, "models">): Promise<AIGNE>;
     /**
      * Creates a new AIGNE instance with the specified options.
      *

package/lib/dts/aigne/context.d.ts

@@ -1,7 +1,7 @@
 import EventEmitter from "node:events";
 import { Agent, type AgentInvokeOptions, type AgentProcessAsyncGenerator, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
+import type { ChatModel } from "../agents/chat-model.js";
 import { UserAgent } from "../agents/user-agent.js";
-import type { ChatModel } from "../models/chat-model.js";
 import { type OmitPropertiesFromArrayFirstElement } from "../utils/type-utils.js";
 import type { Args, Listener, TypedEventEmitter } from "../utils/typed-event-emtter.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
@@ -41,6 +41,7 @@ export type ContextEmitEventMap = {
 export interface InvokeOptions extends AgentInvokeOptions {
     returnActiveAgent?: boolean;
     disableTransfer?: boolean;
+    sourceAgent?: Agent;
 }
 /**
  * @hidden

package/lib/dts/index.d.ts

@@ -5,6 +5,6 @@ export * from "./agents/team-agent.js";
 export * from "./agents/types.js";
 export * from "./agents/user-agent.js";
 export * from "./aigne/index.js";
-export * from "./models/chat-model.js";
+export * from "./agents/chat-model.js";
 export * from "./prompt/prompt-builder.js";
 export * from "./prompt/template.js";

package/lib/dts/loader/agent-yaml.d.ts

@@ -14,13 +14,13 @@ export declare function loadAgentFromYamlFile(path: string): Promise<{
     }, {
         [x: string]: any;
     }> | undefined;
-    toolChoice?: AIAgentToolChoice | undefined;
     outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
     }> | undefined;
     outputKey?: string | undefined;
+    toolChoice?: AIAgentToolChoice | undefined;
 } | {
     type: "mcp";
     url?: string | undefined;

package/lib/dts/loader/index.d.ts

@@ -1,7 +1,14 @@
+import type { Camelize } from "camelize-ts";
 import { z } from "zod";
 import { type Agent } from "../agents/agent.js";
-import type { ChatModel, ChatModelOptions } from "../models/chat-model.js";
+import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
 export interface LoadOptions {
+    models: {
+        new (parameters: {
+            model?: string;
+            modelOptions?: ChatModelOptions;
+        }): ChatModel;
+    }[];
     path: string;
 }
 export declare function load(options: LoadOptions): Promise<{
@@ -15,12 +22,12 @@ export declare function load(options: LoadOptions): Promise<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
 }>;
 export declare function loadAgent(path: string): Promise<Agent>;
-export declare function loadModel(model?: z.infer<typeof aigneFileSchema>["chat_model"], modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
+export declare function loadModel(models: LoadOptions["models"], model?: Camelize<z.infer<typeof aigneFileSchema>["chat_model"]>, modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -29,35 +36,35 @@ declare const aigneFileSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         top_p: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        frequent_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        frequency_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         presence_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     }, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     }>]>>>, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined, string | {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined>;
     agents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
@@ -71,7 +78,7 @@ declare const aigneFileSchema: z.ZodObject<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;
@@ -84,7 +91,7 @@ declare const aigneFileSchema: z.ZodObject<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;
@@ -98,7 +105,7 @@ export declare function loadAIGNEFile(path: string): Promise<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;

package/lib/dts/memory/retriever.d.ts

@@ -39,11 +39,11 @@ export declare const memoryRetrieverInputSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    limit?: number | undefined;
     search?: string | undefined;
-}, {
     limit?: number | undefined;
+}, {
     search?: string | undefined;
+    limit?: number | undefined;
 }>;
 /**
  * @hidden

package/lib/dts/prompt/prompt-builder.d.ts

@@ -1,9 +1,9 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
+import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import type { Context } from "../aigne/context.js";
 import type { MemoryAgent } from "../memory/memory.js";
-import type { ChatModel, ChatModelInput } from "../models/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
 export declare function createMessage<I extends Message>(message: string | I): I;
@@ -11,7 +11,7 @@ export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuilderBuildOptions {
+export interface PromptBuildOptions {
     memory?: MemoryAgent | MemoryAgent[];
     context: Context;
     agent?: AIAgent;
@@ -32,7 +32,7 @@ export declare class PromptBuilder {
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
-    build(options: PromptBuilderBuildOptions): Promise<ChatModelInput & {
+    build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
     private buildMessages;

package/lib/dts/prompt/template.d.ts

@@ -1,4 +1,4 @@
-import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../models/chat-model.js";
+import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
@@ -24,7 +24,7 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCalls: ChatModelOutputToolCall[] | undefined;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
@@ -36,7 +36,7 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content: object | string, toolCallId: string, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCallId: string;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCalls?: {
             id: string;

package/lib/dts/utils/logger.d.ts

@@ -1,8 +1,33 @@
-import debug from "debug";
-export declare const logger: debug.Debug & {
-    debug: debug.Debug;
-    default: debug.Debug;
-} & {
-    core: debug.Debugger;
-    mcp: debug.Debugger;
-};
+export declare enum LogLevel {
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    DEBUG = "debug"
+}
+export declare class Logger {
+    constructor(options: {
+        level: LogLevel;
+        ns: string;
+    });
+    level: LogLevel;
+    private debugLogger;
+    private infoLogger;
+    private warnLogger;
+    private errorLogger;
+    logMessage: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    logError: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    enabled(level: LogLevel): boolean;
+}
+export declare const logger: Logger;

package/lib/dts/utils/model-utils.d.ts

@@ -1,3 +1,3 @@
-import type { ChatModelOutputUsage } from "../models/chat-model.js";
+import type { ChatModelOutputUsage } from "../agents/chat-model.js";
 import type { Nullish } from "./type-utils.js";
 export declare function mergeUsage(...usages: Nullish<ChatModelOutputUsage>[]): ChatModelOutputUsage;

package/lib/dts/utils/stream-utils.d.ts

@@ -6,7 +6,7 @@ export declare function mergeAgentResponseChunk<T extends Message>(output: T, ch
 export declare function agentResponseStreamToObject<T extends Message>(stream: AgentResponseStream<T> | AgentProcessAsyncGenerator<T>): Promise<T>;
 export declare function asyncGeneratorToReadableStream<T extends Message>(generator: AgentProcessAsyncGenerator<T>): AgentResponseStream<T>;
 export declare function onAgentResponseStreamEnd<T extends Message>(stream: AgentResponseStream<T>, callback: (result: T) => PromiseOrValue<Partial<T> | void>, options?: {
-    errorCallback?: (error: Error) => Error;
+    errorCallback?: (error: Error) => PromiseOrValue<Error>;
     processChunk?: (chunk: AgentResponseChunk<T>) => AgentResponseChunk<T>;
 }): ReadableStream<any>;
 export declare function isAsyncGenerator<T extends AsyncGenerator>(value: AsyncGenerator | unknown): value is T;
@@ -18,5 +18,6 @@ export declare function readableStreamToArray<T>(stream: ReadableStream<T>, opti
 export declare function readableStreamToArray<T>(stream: ReadableStream<T>, options?: {
     catchError?: false;
 }): Promise<T[]>;
-export declare function readableStreamToAsyncIterator<T>(stream: ReadableStream<T>): AsyncIterable<T>;
 export declare function stringToAgentResponseStream(str: string, key?: "text" | typeof MESSAGE_KEY | string): AgentResponseStream<Message>;
+export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
+export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;

package/lib/dts/utils/type-utils.d.ts

@@ -2,6 +2,11 @@ import { type ZodType } from "zod";
 export type PromiseOrValue<T> = T | Promise<T>;
 export type Nullish<T> = T | null | undefined | void;
 export type OmitPropertiesFromArrayFirstElement<T extends unknown[], K extends string | number | symbol> = T extends [infer U, ...infer Rest] ? [Omit<U, K>, ...Rest] : never;
+export type XOr<T, K extends keyof T, O extends keyof T> = (Omit<T, O> & {
+    [key in O]?: undefined;
+}) | (Omit<T, K> & {
+    [key in K]?: undefined;
+});
 export declare function isNil(value: unknown): value is null | undefined;
 export declare function isRecord<T>(value: unknown): value is Record<string, T>;
 export declare function isEmpty(obj: unknown): boolean;