@aigne/core 1.13.0 → 1.14.0

package/lib/cjs/memory/memory.d.ts

@@ -0,0 +1,89 @@
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Context } from "../aigne/context.js";
+import type { MessagePayload } from "../aigne/message-queue.js";
+import type { MemoryRecorder, MemoryRecorderInput, MemoryRecorderOutput } from "./recorder.js";
+import type { MemoryRetriever, MemoryRetrieverInput, MemoryRetrieverOutput } from "./retriever.js";
+export interface Memory {
+    id: string;
+    content: unknown;
+    createdAt: string;
+}
+export declare const newMemoryId: () => string;
+export interface MemoryAgentOptions extends Partial<Pick<MemoryAgent, "recorder" | "retriever" | "autoUpdate">>, Pick<AgentOptions, "subscribeTopic" | "skills"> {
+}
+/**
+ * A specialized agent responsible for managing, storing, and retrieving memories within the agent system.
+ *
+ * MemoryAgent serves as a bridge between application logic and memory storage/retrieval mechanisms.
+ * It delegates the actual memory operations to specialized recorder and retriever agents that
+ * are attached as skills. This agent doesn't directly process messages like other agents but
+ * instead provides memory management capabilities to the system.
+ */
+export declare class MemoryAgent extends Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options: MemoryAgentOptions);
+    private _retriever?;
+    /**
+     * Agent used for retrieving memories from storage.
+     *
+     * This retriever is automatically added to the agent's skills when set.
+     * Setting a new retriever will remove any previously set retriever from skills.
+     */
+    get retriever(): MemoryRetriever | undefined;
+    set retriever(value: MemoryRetriever | undefined);
+    private _recorder?;
+    /**
+     * Agent used for recording and storing new memories.
+     *
+     * This recorder is automatically added to the agent's skills when set.
+     * Setting a new recorder will remove any previously set recorder from skills.
+     */
+    get recorder(): MemoryRecorder | undefined;
+    set recorder(value: MemoryRecorder | undefined);
+    /**
+     * Controls whether to automatically update the memory when agent call completes.
+     *
+     * When true, the agent will automatically record any relevant information
+     * after completing operations, creating a history of interactions.
+     */
+    autoUpdate?: boolean;
+    /**
+     * Indicates whether this agent can be directly called.
+     *
+     * MemoryAgent is designed to be used as a supporting component rather than
+     * being directly invoked for processing, so this returns false.
+     */
+    get isCallable(): boolean;
+    /**
+     * The standard message processing method required by the Agent interface.
+     *
+     * MemoryAgent doesn't directly process messages like other agents, so this method
+     * throws an error when called. Use the specialized retrieve() and record() methods instead.
+     */
+    process(_input: Message, _context: Context): Promise<Message>;
+    /**
+     * Retrieves memories based on the provided input criteria.
+     *
+     * Delegates the actual retrieval operation to the configured retriever agent.
+     *
+     * @param input - The retrieval parameters (can include search terms, limits, etc.)
+     * @param context - The execution context
+     * @returns A promise resolving to the retrieved memories
+     * @throws Error - If no retriever has been initialized
+     */
+    retrieve(input: MemoryRetrieverInput, context: Context): Promise<MemoryRetrieverOutput>;
+    /**
+     * Records new memories based on the provided input content.
+     *
+     * Delegates the actual recording operation to the configured recorder agent.
+     *
+     * @param input - The content to be recorded as memories
+     * @param context - The execution context
+     * @returns A promise resolving to the recorded memories
+     * @throws Error - If no recorder has been initialized
+     */
+    record(input: MemoryRecorderInput, context: Context): Promise<MemoryRecorderOutput>;
+    onMessage({ role, source, message, context }: MessagePayload): Promise<void>;
+}

package/lib/cjs/memory/memory.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryAgent = exports.newMemoryId = void 0;
+const uuid_1 = require("uuid");
+const zod_1 = require("zod");
+const agent_js_1 = require("../agents/agent.js");
+const type_utils_js_1 = require("../utils/type-utils.js");
+const newMemoryId = () => (0, uuid_1.v7)();
+exports.newMemoryId = newMemoryId;
+/**
+ * A specialized agent responsible for managing, storing, and retrieving memories within the agent system.
+ *
+ * MemoryAgent serves as a bridge between application logic and memory storage/retrieval mechanisms.
+ * It delegates the actual memory operations to specialized recorder and retriever agents that
+ * are attached as skills. This agent doesn't directly process messages like other agents but
+ * instead provides memory management capabilities to the system.
+ */
+class MemoryAgent extends agent_js_1.Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options) {
+        (0, type_utils_js_1.checkArguments)("MemoryAgent", memoryAgentOptionsSchema, options);
+        super({
+            subscribeTopic: options.subscribeTopic,
+            skills: options.skills,
+        });
+        this.recorder = options.recorder;
+        this.retriever = options.retriever;
+        this.autoUpdate = options.autoUpdate;
+    }
+    _retriever;
+    /**
+     * Agent used for retrieving memories from storage.
+     *
+     * This retriever is automatically added to the agent's skills when set.
+     * Setting a new retriever will remove any previously set retriever from skills.
+     */
+    get retriever() {
+        return this._retriever;
+    }
+    set retriever(value) {
+        if (this._retriever)
+            (0, type_utils_js_1.remove)(this.skills, [this._retriever]);
+        this._retriever = value;
+        if (value)
+            this.skills.push(value);
+    }
+    _recorder;
+    /**
+     * Agent used for recording and storing new memories.
+     *
+     * This recorder is automatically added to the agent's skills when set.
+     * Setting a new recorder will remove any previously set recorder from skills.
+     */
+    get recorder() {
+        return this._recorder;
+    }
+    set recorder(value) {
+        if (this._recorder)
+            (0, type_utils_js_1.remove)(this.skills, [this._recorder]);
+        this._recorder = value;
+        if (value)
+            this.skills.push(value);
+    }
+    /**
+     * Controls whether to automatically update the memory when agent call completes.
+     *
+     * When true, the agent will automatically record any relevant information
+     * after completing operations, creating a history of interactions.
+     */
+    autoUpdate;
+    /**
+     * Indicates whether this agent can be directly called.
+     *
+     * MemoryAgent is designed to be used as a supporting component rather than
+     * being directly invoked for processing, so this returns false.
+     */
+    get isCallable() {
+        return false;
+    }
+    /**
+     * The standard message processing method required by the Agent interface.
+     *
+     * MemoryAgent doesn't directly process messages like other agents, so this method
+     * throws an error when called. Use the specialized retrieve() and record() methods instead.
+     */
+    async process(_input, _context) {
+        throw new Error("Method not implemented.");
+    }
+    /**
+     * Retrieves memories based on the provided input criteria.
+     *
+     * Delegates the actual retrieval operation to the configured retriever agent.
+     *
+     * @param input - The retrieval parameters (can include search terms, limits, etc.)
+     * @param context - The execution context
+     * @returns A promise resolving to the retrieved memories
+     * @throws Error - If no retriever has been initialized
+     */
+    async retrieve(input, context) {
+        if (!this.retriever)
+            throw new Error("MemoryAgent retriever not initialized");
+        return context.invoke(this.retriever, input);
+    }
+    /**
+     * Records new memories based on the provided input content.
+     *
+     * Delegates the actual recording operation to the configured recorder agent.
+     *
+     * @param input - The content to be recorded as memories
+     * @param context - The execution context
+     * @returns A promise resolving to the recorded memories
+     * @throws Error - If no recorder has been initialized
+     */
+    async record(input, context) {
+        if (!this.recorder)
+            throw new Error("MemoryAgent recorder not initialized");
+        return context.invoke(this.recorder, input);
+    }
+    async onMessage({ role, source, message, context }) {
+        this.record({ content: [{ role, source, content: message }] }, context);
+    }
+}
+exports.MemoryAgent = MemoryAgent;
+const memoryAgentOptionsSchema = zod_1.z.object({
+    retriever: zod_1.z.custom().optional(),
+    recorder: zod_1.z.custom().optional(),
+    autoUpdate: zod_1.z.boolean().optional(),
+    subscribeTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
+    skills: zod_1.z.array(zod_1.z.custom()).optional(),
+});

package/lib/cjs/memory/recorder.d.ts

@@ -0,0 +1,86 @@
+import { type ZodType, z } from "zod";
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Memory } from "./memory.js";
+/**
+ * Input for memory recording operations.
+ *
+ * This interface represents the data needed to record new memories
+ * in the system. The content array can contain any type of data that
+ * should be stored as memories.
+ */
+export interface MemoryRecorderInput extends Message {
+    /**
+     * Array of content items to record as memories.
+     * Each item in this array will typically be converted into a separate memory entry.
+     */
+    content: unknown[];
+}
+/**
+ * @hidden
+ */
+export declare const memoryRecorderInputSchema: ZodType<MemoryRecorderInput>;
+/**
+ * Output from memory recording operations.
+ *
+ * This interface represents the result of recording new memories,
+ * including the newly created memory objects with their IDs and timestamps.
+ */
+export interface MemoryRecorderOutput extends Message {
+    /**
+     * Array of newly created memory objects.
+     * Each memory includes a unique ID, the stored content, and a creation timestamp.
+     */
+    memories: Memory[];
+}
+/**
+ * @hidden
+ */
+export declare const memoryRecorderOutputSchema: z.ZodObject<{
+    memories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: ZodType<{}, z.ZodTypeDef, {}>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}>;
+/**
+ * Abstract base class for agents that record and store memories.
+ *
+ * The MemoryRecorder serves as a foundation for implementing specific memory storage
+ * mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Converting input content into standardized memory objects
+ * 2. Assigning unique IDs to new memories
+ * 3. Storing memories in an appropriate backend (database, file system, etc.)
+ * 4. Ensuring proper timestamping of memories
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual storage logic.
+ */
+export declare abstract class MemoryRecorder extends Agent<MemoryRecorderInput, MemoryRecorderOutput> {
+    /**
+     * Creates a new MemoryRecorder instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory recorder agent
+     */
+    constructor(options: Omit<AgentOptions<MemoryRecorderInput, MemoryRecorderOutput>, "inputSchema" | "outputSchema">);
+}

package/lib/cjs/memory/recorder.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRecorder = exports.memoryRecorderOutputSchema = exports.memoryRecorderInputSchema = void 0;
+const zod_1 = require("zod");
+const agent_js_1 = require("../agents/agent.js");
+/**
+ * @hidden
+ */
+exports.memoryRecorderInputSchema = zod_1.z.object({
+    content: zod_1.z.array(zod_1.z.unknown()),
+});
+/**
+ * @hidden
+ */
+exports.memoryRecorderOutputSchema = zod_1.z.object({
+    memories: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        content: zod_1.z.custom(),
+        createdAt: zod_1.z.string().datetime(),
+    })),
+});
+/**
+ * Abstract base class for agents that record and store memories.
+ *
+ * The MemoryRecorder serves as a foundation for implementing specific memory storage
+ * mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Converting input content into standardized memory objects
+ * 2. Assigning unique IDs to new memories
+ * 3. Storing memories in an appropriate backend (database, file system, etc.)
+ * 4. Ensuring proper timestamping of memories
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual storage logic.
+ */
+class MemoryRecorder extends agent_js_1.Agent {
+    /**
+     * Creates a new MemoryRecorder instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory recorder agent
+     */
+    constructor(options) {
+        super({
+            ...options,
+            inputSchema: exports.memoryRecorderInputSchema,
+            outputSchema: exports.memoryRecorderOutputSchema,
+        });
+    }
+}
+exports.MemoryRecorder = MemoryRecorder;

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

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Memory } from "./memory.js";
+/**
+ * Input for memory retrieval operations.
+ *
+ * This interface defines the parameters that can be used to query and filter
+ * memories when retrieving them from storage.
+ */
+export interface MemoryRetrieverInput extends Message {
+    /**
+     * Maximum number of memories to retrieve.
+     * Used for pagination or limiting result set size.
+     */
+    limit?: number;
+    /**
+     * Search term to filter memories by.
+     * How the search is implemented depends on the specific retriever implementation.
+     */
+    search?: string;
+}
+/**
+ * Output from memory retrieval operations.
+ *
+ * This interface represents the result of retrieving memories from storage,
+ * containing an array of memory objects that match the query criteria.
+ */
+export interface MemoryRetrieverOutput extends Message {
+    /**
+     * Array of retrieved memory objects.
+     * Each memory includes its ID, content, and creation timestamp.
+     */
+    memories: Memory[];
+}
+/**
+ * @hidden
+ */
+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;
+}>;
+/**
+ * @hidden
+ */
+export declare const memoryRetrieverOutputSchema: z.ZodObject<{
+    memories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodType<{}, z.ZodTypeDef, {}>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}>;
+/**
+ * Abstract base class for agents that retrieve memories from storage.
+ *
+ * The MemoryRetriever serves as a foundation for implementing specific memory
+ * retrieval mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Querying a memory storage backend to find relevant memories
+ * 2. Filtering memories based on search criteria
+ * 3. Limiting the number of results returned
+ * 4. Potentially implementing sorting, ranking, or relevance-based retrieval
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual retrieval logic.
+ */
+export declare abstract class MemoryRetriever extends Agent<MemoryRetrieverInput, MemoryRetrieverOutput> {
+    /**
+     * Creates a new MemoryRetriever instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory retriever agent
+     */
+    constructor(options: Omit<AgentOptions<MemoryRetrieverInput, MemoryRetrieverOutput>, "inputSchema" | "outputSchema">);
+}

package/lib/cjs/memory/retriever.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRetriever = exports.memoryRetrieverOutputSchema = exports.memoryRetrieverInputSchema = void 0;
+const zod_1 = require("zod");
+const agent_js_1 = require("../agents/agent.js");
+/**
+ * @hidden
+ */
+exports.memoryRetrieverInputSchema = zod_1.z.object({
+    limit: zod_1.z.number().optional(),
+    search: zod_1.z.string().optional(),
+});
+/**
+ * @hidden
+ */
+exports.memoryRetrieverOutputSchema = zod_1.z.object({
+    memories: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        content: zod_1.z.custom(),
+        createdAt: zod_1.z.string().datetime(),
+    })),
+});
+/**
+ * Abstract base class for agents that retrieve memories from storage.
+ *
+ * The MemoryRetriever serves as a foundation for implementing specific memory
+ * retrieval mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Querying a memory storage backend to find relevant memories
+ * 2. Filtering memories based on search criteria
+ * 3. Limiting the number of results returned
+ * 4. Potentially implementing sorting, ranking, or relevance-based retrieval
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual retrieval logic.
+ */
+class MemoryRetriever extends agent_js_1.Agent {
+    /**
+     * Creates a new MemoryRetriever instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory retriever agent
+     */
+    constructor(options) {
+        super({
+            ...options,
+            inputSchema: exports.memoryRetrieverInputSchema,
+            outputSchema: exports.memoryRetrieverOutputSchema,
+        });
+    }
+}
+exports.MemoryRetriever = MemoryRetriever;

package/lib/cjs/models/bedrock-chat-model.d.ts

@@ -1,8 +1,10 @@
 import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
 import { z } from "zod";
-import type { AgentInvokeOptions, AgentResponse } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
+import type { AgentResponse } from "../agents/agent.js";
 import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+/**
+ * @hidden
+ */
 export declare function extractLastJsonObject(text: string): string | null;
 export interface BedrockChatModelOptions {
     accessKeyId?: string;
@@ -11,6 +13,9 @@ export interface BedrockChatModelOptions {
     model?: string;
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const bedrockChatModelOptionsSchema: z.ZodObject<{
     region: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
@@ -62,9 +67,13 @@ export declare const bedrockChatModelOptionsSchema: z.ZodObject<{
 export declare class BedrockChatModel extends ChatModel {
     options?: BedrockChatModelOptions | undefined;
     constructor(options?: BedrockChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: BedrockRuntimeClient;
     get client(): BedrockRuntimeClient;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    process(input: ChatModelInput): Promise<AgentResponse<ChatModelOutput>>;
     private extractResultFromStream;
+    private requestStructuredOutput;
 }