@aigne/core 1.12.0 → 1.14.0

package/lib/esm/memory/memory.js

@@ -0,0 +1,127 @@
+import { v7 } from "uuid";
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+import { checkArguments, remove } from "../utils/type-utils.js";
+export const newMemoryId = () => v7();
+/**
+ * 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 class MemoryAgent extends Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options) {
+        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)
+            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)
+            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);
+    }
+}
+const memoryAgentOptionsSchema = z.object({
+    retriever: z.custom().optional(),
+    recorder: z.custom().optional(),
+    autoUpdate: z.boolean().optional(),
+    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
+    skills: z.array(z.custom()).optional(),
+});

package/lib/esm/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/esm/memory/recorder.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+/**
+ * @hidden
+ */
+export const memoryRecorderInputSchema = z.object({
+    content: z.array(z.unknown()),
+});
+/**
+ * @hidden
+ */
+export const memoryRecorderOutputSchema = z.object({
+    memories: z.array(z.object({
+        id: z.string(),
+        content: z.custom(),
+        createdAt: 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.
+ */
+export class MemoryRecorder extends 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: memoryRecorderInputSchema,
+            outputSchema: memoryRecorderOutputSchema,
+        });
+    }
+}

package/lib/esm/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/esm/memory/retriever.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+/**
+ * @hidden
+ */
+export const memoryRetrieverInputSchema = z.object({
+    limit: z.number().optional(),
+    search: z.string().optional(),
+});
+/**
+ * @hidden
+ */
+export const memoryRetrieverOutputSchema = z.object({
+    memories: z.array(z.object({
+        id: z.string(),
+        content: z.custom(),
+        createdAt: 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.
+ */
+export class MemoryRetriever extends 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: memoryRetrieverInputSchema,
+            outputSchema: memoryRetrieverOutputSchema,
+        });
+    }
+}

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

@@ -0,0 +1,79 @@
+import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
+import { z } from "zod";
+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;
+    secretAccessKey?: string;
+    region?: string;
+    model?: string;
+    modelOptions?: ChatModelOptions;
+}
+/**
+ * @hidden
+ */
+export declare const bedrockChatModelOptionsSchema: z.ZodObject<{
+    region: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    modelOptions: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        parallelToolCalls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    }, {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    modelOptions?: {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    } | undefined;
+    model?: string | undefined;
+    region?: string | undefined;
+}, {
+    modelOptions?: {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    } | undefined;
+    model?: string | undefined;
+    region?: string | undefined;
+}>;
+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): Promise<AgentResponse<ChatModelOutput>>;
+    private extractResultFromStream;
+    private requestStructuredOutput;
+}