@agentionai/agents 0.3.0-beta

package/dist/ingestion/IngestionPipeline.d.ts

@@ -0,0 +1,86 @@
+import { Chunk, ChunkOptions } from "../chunkers/types";
+import { Chunker } from "../chunkers/Chunker";
+import { Embeddings } from "../vectorstore/Embeddings";
+import { VectorStore } from "../vectorstore/VectorStore";
+import { IngestionOptions, IngestionResult, DocumentInput } from "./types";
+/**
+ * Pipeline for ingesting documents into a vector store.
+ * Orchestrates the flow: chunk → batch embed → store
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new IngestionPipeline(
+ *   new RecursiveChunker({ chunkSize: 1000, chunkOverlap: 100 }),
+ *   new OpenAIEmbeddings(),
+ *   vectorStore
+ * );
+ *
+ * const result = await pipeline.ingest(documentText, {
+ *   sourceId: 'doc-123',
+ *   sourcePath: '/docs/readme.md',
+ *   batchSize: 50,
+ *   onProgress: ({ phase, processed, total }) => {
+ *     console.log(`${phase}: ${processed}/${total}`);
+ *   }
+ * });
+ *
+ * console.log(`Stored ${result.chunksStored} chunks in ${result.duration}ms`);
+ * ```
+ */
+export declare class IngestionPipeline {
+    private chunker;
+    private embeddings;
+    private store;
+    constructor(chunker: Chunker, embeddings: Embeddings, store: VectorStore);
+    /**
+     * Ingest a single document into the vector store.
+     *
+     * @param text - The document text to ingest
+     * @param options - Chunk options and ingestion options
+     * @returns Result of the ingestion operation
+     */
+    ingest(text: string, options?: ChunkOptions & IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Ingest multiple documents into the vector store.
+     *
+     * @param documents - Array of documents with their options
+     * @param options - Ingestion options
+     * @returns Aggregated result of all ingestions
+     */
+    ingestMany(documents: DocumentInput[], options?: IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Ingest pre-chunked data into the vector store.
+     * Useful when chunking is done separately.
+     *
+     * @param chunks - Array of chunks to ingest
+     * @param options - Ingestion options
+     * @returns Result of the ingestion operation
+     */
+    ingestChunks(chunks: Chunk[], options?: IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Process chunks through embedding and storage.
+     */
+    private processChunks;
+    /**
+     * Filter out chunks that already exist in the store (by hash).
+     * Checks the store for existing documents with the same content hash.
+     */
+    private filterDuplicates;
+    /**
+     * Emit a progress event if callback is provided.
+     */
+    private emitProgress;
+    /**
+     * Get the chunker used by this pipeline.
+     */
+    getChunker(): Chunker;
+    /**
+     * Get the embeddings provider used by this pipeline.
+     */
+    getEmbeddings(): Embeddings;
+    /**
+     * Get the vector store used by this pipeline.
+     */
+    getStore(): VectorStore;
+}
+//# sourceMappingURL=IngestionPipeline.d.ts.map

package/dist/ingestion/IngestionPipeline.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngestionPipeline = void 0;
+/**
+ * Pipeline for ingesting documents into a vector store.
+ * Orchestrates the flow: chunk → batch embed → store
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new IngestionPipeline(
+ *   new RecursiveChunker({ chunkSize: 1000, chunkOverlap: 100 }),
+ *   new OpenAIEmbeddings(),
+ *   vectorStore
+ * );
+ *
+ * const result = await pipeline.ingest(documentText, {
+ *   sourceId: 'doc-123',
+ *   sourcePath: '/docs/readme.md',
+ *   batchSize: 50,
+ *   onProgress: ({ phase, processed, total }) => {
+ *     console.log(`${phase}: ${processed}/${total}`);
+ *   }
+ * });
+ *
+ * console.log(`Stored ${result.chunksStored} chunks in ${result.duration}ms`);
+ * ```
+ */
+class IngestionPipeline {
+    constructor(chunker, embeddings, store) {
+        this.chunker = chunker;
+        this.embeddings = embeddings;
+        this.store = store;
+    }
+    /**
+     * Ingest a single document into the vector store.
+     *
+     * @param text - The document text to ingest
+     * @param options - Chunk options and ingestion options
+     * @returns Result of the ingestion operation
+     */
+    async ingest(text, options) {
+        const startTime = Date.now();
+        const chunkOptions = {
+            sourceId: options?.sourceId,
+            sourcePath: options?.sourcePath,
+            metadata: options?.metadata,
+        };
+        const ingestionOptions = {
+            batchSize: options?.batchSize,
+            onProgress: options?.onProgress,
+            onError: options?.onError,
+            skipDuplicates: options?.skipDuplicates,
+        };
+        // Phase 1: Chunking
+        this.emitProgress(ingestionOptions.onProgress, {
+            phase: "chunking",
+            processed: 0,
+            total: 1,
+        });
+        const chunks = await this.chunker.chunk(text, chunkOptions);
+        this.emitProgress(ingestionOptions.onProgress, {
+            phase: "chunking",
+            processed: 1,
+            total: 1,
+        });
+        // Process the chunks
+        return this.processChunks(chunks, ingestionOptions, startTime);
+    }
+    /**
+     * Ingest multiple documents into the vector store.
+     *
+     * @param documents - Array of documents with their options
+     * @param options - Ingestion options
+     * @returns Aggregated result of all ingestions
+     */
+    async ingestMany(documents, options) {
+        const startTime = Date.now();
+        // Phase 1: Chunk all documents
+        this.emitProgress(options?.onProgress, {
+            phase: "chunking",
+            processed: 0,
+            total: documents.length,
+        });
+        const allChunks = [];
+        for (let i = 0; i < documents.length; i++) {
+            const doc = documents[i];
+            const chunks = await this.chunker.chunk(doc.text, doc.options);
+            allChunks.push(...chunks);
+            this.emitProgress(options?.onProgress, {
+                phase: "chunking",
+                processed: i + 1,
+                total: documents.length,
+            });
+        }
+        // Process all chunks together
+        return this.processChunks(allChunks, options ?? {}, startTime);
+    }
+    /**
+     * Ingest pre-chunked data into the vector store.
+     * Useful when chunking is done separately.
+     *
+     * @param chunks - Array of chunks to ingest
+     * @param options - Ingestion options
+     * @returns Result of the ingestion operation
+     */
+    async ingestChunks(chunks, options) {
+        const startTime = Date.now();
+        return this.processChunks(chunks, options ?? {}, startTime);
+    }
+    /**
+     * Process chunks through embedding and storage.
+     */
+    async processChunks(chunks, options, startTime) {
+        const { batchSize = 100, onProgress, onError, skipDuplicates = false, } = options;
+        const result = {
+            success: true,
+            chunksProcessed: chunks.length,
+            chunksSkipped: 0,
+            chunksStored: 0,
+            errors: [],
+            duration: 0,
+        };
+        if (chunks.length === 0) {
+            result.duration = Date.now() - startTime;
+            return result;
+        }
+        // Filter duplicates if enabled
+        let chunksToProcess = chunks;
+        if (skipDuplicates) {
+            chunksToProcess = await this.filterDuplicates(chunks);
+            result.chunksSkipped = chunks.length - chunksToProcess.length;
+        }
+        if (chunksToProcess.length === 0) {
+            result.duration = Date.now() - startTime;
+            return result;
+        }
+        // Calculate batches
+        const totalBatches = Math.ceil(chunksToProcess.length / batchSize);
+        // Phase 2 & 3: Embed and store in batches
+        for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
+            const batchStart = batchIndex * batchSize;
+            const batchEnd = Math.min(batchStart + batchSize, chunksToProcess.length);
+            const batch = chunksToProcess.slice(batchStart, batchEnd);
+            // Embed batch
+            this.emitProgress(onProgress, {
+                phase: "embedding",
+                processed: batchStart,
+                total: chunksToProcess.length,
+                currentBatch: batchIndex + 1,
+                totalBatches,
+            });
+            let embeddings;
+            try {
+                embeddings = await this.embeddings.embed(batch.map((c) => c.content));
+            }
+            catch (error) {
+                // Handle embedding error for entire batch
+                for (const chunk of batch) {
+                    if (onError) {
+                        const action = onError(error, chunk);
+                        if (action === "abort") {
+                            result.success = false;
+                            result.duration = Date.now() - startTime;
+                            return result;
+                        }
+                    }
+                    result.errors.push({ chunk, error: error });
+                }
+                continue;
+            }
+            // Create embedded documents
+            const embeddedDocs = batch.map((chunk, i) => ({
+                id: chunk.id,
+                content: chunk.content,
+                metadata: chunk.metadata,
+                embedding: embeddings[i],
+            }));
+            // Store batch
+            this.emitProgress(onProgress, {
+                phase: "storing",
+                processed: batchStart,
+                total: chunksToProcess.length,
+                currentBatch: batchIndex + 1,
+                totalBatches,
+            });
+            try {
+                await this.store.addEmbeddedDocuments(embeddedDocs);
+                result.chunksStored += embeddedDocs.length;
+            }
+            catch (error) {
+                // Try storing one by one to identify problematic chunks
+                for (let i = 0; i < embeddedDocs.length; i++) {
+                    try {
+                        await this.store.addEmbeddedDocuments([embeddedDocs[i]]);
+                        result.chunksStored++;
+                    }
+                    catch (chunkError) {
+                        const chunk = batch[i];
+                        if (onError) {
+                            const action = onError(chunkError, chunk);
+                            if (action === "abort") {
+                                result.success = false;
+                                result.duration = Date.now() - startTime;
+                                return result;
+                            }
+                        }
+                        result.errors.push({ chunk, error: chunkError });
+                    }
+                }
+            }
+        }
+        // Final progress
+        this.emitProgress(onProgress, {
+            phase: "storing",
+            processed: chunksToProcess.length,
+            total: chunksToProcess.length,
+            currentBatch: totalBatches,
+            totalBatches,
+        });
+        result.duration = Date.now() - startTime;
+        return result;
+    }
+    /**
+     * Filter out chunks that already exist in the store (by hash).
+     * Checks the store for existing documents with the same content hash.
+     */
+    async filterDuplicates(chunks) {
+        if (chunks.length === 0) {
+            return chunks;
+        }
+        // Extract all hashes from chunks
+        const hashes = chunks.map((chunk) => chunk.metadata.hash);
+        // Check which hashes already exist in the store
+        const existingHashes = await this.store.getByHashes(hashes);
+        // Filter out chunks whose hashes exist
+        return chunks.filter((chunk) => !existingHashes.has(chunk.metadata.hash));
+    }
+    /**
+     * Emit a progress event if callback is provided.
+     */
+    emitProgress(callback, event) {
+        if (callback) {
+            callback(event);
+        }
+    }
+    /**
+     * Get the chunker used by this pipeline.
+     */
+    getChunker() {
+        return this.chunker;
+    }
+    /**
+     * Get the embeddings provider used by this pipeline.
+     */
+    getEmbeddings() {
+        return this.embeddings;
+    }
+    /**
+     * Get the vector store used by this pipeline.
+     */
+    getStore() {
+        return this.store;
+    }
+}
+exports.IngestionPipeline = IngestionPipeline;
+//# sourceMappingURL=IngestionPipeline.js.map

package/dist/ingestion/index.d.ts

@@ -0,0 +1,3 @@
+export { IngestionOptions, IngestionResult, IngestionProgressEvent, DocumentInput, } from "./types";
+export { IngestionPipeline } from "./IngestionPipeline";
+//# sourceMappingURL=index.d.ts.map

package/dist/ingestion/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngestionPipeline = void 0;
+// Pipeline
+var IngestionPipeline_1 = require("./IngestionPipeline");
+Object.defineProperty(exports, "IngestionPipeline", { enumerable: true, get: function () { return IngestionPipeline_1.IngestionPipeline; } });
+//# sourceMappingURL=index.js.map

package/dist/ingestion/types.d.ts

@@ -0,0 +1,74 @@
+import { Chunk, ChunkOptions } from "../chunkers/types";
+/**
+ * Progress event emitted during ingestion.
+ */
+export interface IngestionProgressEvent {
+    /** Current phase of ingestion */
+    phase: "chunking" | "embedding" | "storing";
+    /** Number of items processed in this phase */
+    processed: number;
+    /** Total number of items in this phase */
+    total: number;
+    /** Current batch number (for embedding/storing phases) */
+    currentBatch?: number;
+    /** Total number of batches */
+    totalBatches?: number;
+}
+/**
+ * Options for the ingestion pipeline.
+ */
+export interface IngestionOptions {
+    /**
+     * Number of chunks to process per embedding batch.
+     * Larger batches are more efficient but use more memory.
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Callback for progress updates.
+     */
+    onProgress?: (event: IngestionProgressEvent) => void;
+    /**
+     * Error handling strategy.
+     * - 'skip': Skip the failed chunk and continue
+     * - 'abort': Stop the entire ingestion process
+     * @returns The action to take
+     */
+    onError?: (error: Error, chunk: Chunk) => "skip" | "abort";
+    /**
+     * Whether to skip chunks with hashes that already exist in the store.
+     * Requires the store to support hash-based lookup.
+     * @default false
+     */
+    skipDuplicates?: boolean;
+}
+/**
+ * Result of an ingestion operation.
+ */
+export interface IngestionResult {
+    /** Whether the ingestion completed without aborting */
+    success: boolean;
+    /** Total number of chunks that were processed */
+    chunksProcessed: number;
+    /** Number of chunks skipped (duplicates or filtered) */
+    chunksSkipped: number;
+    /** Number of chunks successfully stored */
+    chunksStored: number;
+    /** Array of errors encountered during ingestion */
+    errors: Array<{
+        chunk: Chunk;
+        error: Error;
+    }>;
+    /** Total time taken in milliseconds */
+    duration: number;
+}
+/**
+ * Document input for batch ingestion.
+ */
+export interface DocumentInput {
+    /** The text content to ingest */
+    text: string;
+    /** Options for this specific document */
+    options?: ChunkOptions;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ingestion/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/team/Team.d.ts

@@ -0,0 +1,46 @@
+import { Tool } from "../tools/Tool";
+import { BaseAgent, BaseAgentConfig } from "../agents/BaseAgent";
+import EventEmitter from "node:events";
+export type TeamConfig = {
+    name: string;
+    agents: BaseAgent[];
+    leadAgent: BaseAgent;
+    delegationPrompt?: string;
+};
+/**
+ * A team consists of a number of agents.
+ *
+ * Todo:
+ * [] events from a team for tools and agents.
+ * [x] add a team lead agent who delegates work
+ * [x] Option for team members to work together. Tool.fomAgent
+ * [] add agents purely from text config
+ * [] keep track of the number of tokens being used
+ */
+export declare class Team extends EventEmitter {
+    protected tools: Tool<any>[];
+    protected leadAgent: BaseAgent;
+    protected agents: BaseAgent[];
+    protected delegationPrompt: string;
+    protected name: string;
+    constructor(config: TeamConfig);
+    private get memberAgents();
+    private setupTeam;
+    addAgent(newAgent: BaseAgent): void;
+    /**
+     * Execute a task with the team by delegating to the lead agent
+     * @param input The input for the task
+     * @returns The result from the lead agent
+     */
+    execute(input: string): Promise<any>;
+    /**
+     * Get the lead agent
+     */
+    getLeadAgent(): BaseAgent;
+    /**
+     * Get all tools available to the team
+     */
+    getTools(): Tool<any>[];
+    fromConfig(config: BaseAgentConfig[]): void;
+}
+//# sourceMappingURL=Team.d.ts.map

package/dist/team/Team.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Team = void 0;
+const Tool_1 = require("../tools/Tool");
+const node_events_1 = __importDefault(require("node:events"));
+const Agent_1 = require("../agents/Agent");
+/**
+ * A team consists of a number of agents.
+ *
+ * Todo:
+ * [] events from a team for tools and agents.
+ * [x] add a team lead agent who delegates work
+ * [x] Option for team members to work together. Tool.fomAgent
+ * [] add agents purely from text config
+ * [] keep track of the number of tokens being used
+ */
+class Team extends node_events_1.default {
+    constructor(config) {
+        super();
+        this.tools = [];
+        this.agents = [];
+        this.leadAgent = config.leadAgent;
+        this.agents = config.agents || [];
+        this.name = config.name;
+        this.delegationPrompt =
+            config.delegationPrompt ||
+                "You are the team leader. You can delegate tasks to your team members when appropriate. " +
+                    "Analyze the task and decide whether to handle it yourself or delegate to a team member with the right expertise.";
+        this.setupTeam();
+        // this.emit("agentsUpdated", [...this.agents]);
+        // this.emit("toolsUpdated", [...this.tools]);
+        this.tools.forEach((tool) => tool.addListener(Tool_1.ToolResultEvent.RESULT, (...args) => {
+            this.emit(Tool_1.ToolResultEvent.RESULT, ...args);
+        }));
+    }
+    get memberAgents() {
+        return this.agents.filter((agent) => agent.getId() !== this.leadAgent.getId());
+    }
+    setupTeam() {
+        // Convert member agents to tools that the lead agent can use
+        const memberTools = this.memberAgents.map((agent) => Tool_1.Tool.fromAgent(agent, `Delegate to this team member`));
+        this.tools.push(...memberTools);
+        this.leadAgent.addTools(memberTools);
+        // Add all tools from all agents
+        this.agents.forEach((agent) => {
+            agent.getTools().forEach((tool) => {
+                if (!this.tools.includes(tool)) {
+                    this.tools.push(tool);
+                }
+            });
+        });
+        // Set up event forwarding
+        // this.setupEventForwarding();
+        // Emit initial events
+        this.emit("leadAgentSet", this.leadAgent);
+        this.emit("memberAgentsUpdated", [...this.memberAgents]);
+        this.emit("toolsUpdated", [...this.tools]);
+    }
+    addAgent(newAgent) {
+        if (this.agents.find((agent) => agent.getId() === newAgent.getId())) {
+            this.agents.push(newAgent);
+        }
+        this.emit("agentsUpdated", [...this.agents]);
+    }
+    /**
+     * Execute a task with the team by delegating to the lead agent
+     * @param input The input for the task
+     * @returns The result from the lead agent
+     */
+    async execute(input) {
+        // this.emit("teamTaskStarted", { input, teamName: this.name });
+        try {
+            const result = await this.leadAgent.execute(input);
+            // this.emit("teamTaskCompleted", { input, result, teamName: this.name });
+            return result;
+        }
+        catch (error) {
+            // this.emit("teamTaskError", { input, error, teamName: this.name });
+            throw error;
+        }
+    }
+    /**
+     * Get the lead agent
+     */
+    getLeadAgent() {
+        return this.leadAgent;
+    }
+    /**
+     * Get all tools available to the team
+     */
+    getTools() {
+        return [...this.tools];
+    }
+    fromConfig(config) {
+        config.forEach((agentConfig) => {
+            this.addAgent(Agent_1.Agent.create(agentConfig));
+        });
+    }
+}
+exports.Team = Team;
+//# sourceMappingURL=Team.js.map

package/dist/tools/Tool.d.ts

@@ -0,0 +1,75 @@
+import EventEmitter from "events";
+import { BaseAgent, AgentVendor } from "../agents/BaseAgent";
+export interface ToolInputSchema {
+    type: "object";
+    properties: Record<string, any>;
+    required?: string[] | undefined;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+export interface ToolConfig<T> {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    execute: (input: any, context?: Record<string, any> | null) => Promise<T>;
+    context?: Record<string, any>;
+}
+export declare class ToolEvent {
+    target: Tool<any>;
+    input: Record<string, any>;
+    id: string;
+    agentId: string;
+    agentName: string;
+    static EXECUTE: string;
+    private defaultPrevented;
+    constructor(target: Tool<any>, input: Record<string, any>, id: string, agentId: string, agentName: string);
+    preventDefault(): void;
+    get isDefaultPrevented(): boolean;
+}
+export declare class ToolResultEvent extends ToolEvent {
+    target: Tool<any>;
+    input: Record<string, any>;
+    id: string;
+    result: any;
+    agentId: string;
+    agentName: string;
+    eventName: string;
+    static RESULT: string;
+    constructor(target: Tool<any>, input: Record<string, any>, id: string, result: any, agentId: string, agentName: string);
+}
+/**
+ * Tools are used to retrieve additional information for LLMs, so they can provide better results. Examples could be
+ * Retrieving weather information, stock prices or specific price information.
+ *
+ * @param T Generic. Format of the tool result
+
+ */
+export declare class Tool<T> extends EventEmitter {
+    protected executeFn: (input: unknown, context: Record<string, any> | null) => Promise<T>;
+    name: string;
+    protected description: string;
+    protected context: Record<string, any> | null;
+    protected schema: ToolInputSchema;
+    /**
+     * Agents can act as assistants to other agents. This static method creates a tool
+     * @param agent The agent that will act as an assistant
+     * @param description Th
+     * @returns Tool
+     */
+    static fromAgent(agent: BaseAgent, description: string): Tool<string>;
+    constructor(config: ToolConfig<T>);
+    execute(agentId: string, agentName: string, input: Record<string, any>, id: string, agentModel?: string, agentVendor?: AgentVendor): Promise<T>;
+    getPrompt(_vendor?: string): {
+        name: string;
+        description: string;
+        input_schema: ToolInputSchema;
+    };
+}
+//# sourceMappingURL=Tool.d.ts.map