@agentionai/agents 0.3.0-beta

package/dist/graph/GraphMetrics.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Metrics and observability for graph execution.
+ * Tracks timing, token usage, and pipeline structure for analysis and visualization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsCollector = void 0;
+exports.getMetricsCollector = getMetricsCollector;
+exports.setMetricsCollector = setMetricsCollector;
+exports.createMetricsCollector = createMetricsCollector;
+/**
+ * Collector for gathering metrics during graph execution.
+ */
+class MetricsCollector {
+    constructor() {
+        this.executions = [];
+        this.currentExecution = null;
+        this.executionStack = [];
+        this.idCounter = 0;
+    }
+    /**
+     * Generate a unique execution ID.
+     */
+    generateId() {
+        return `exec_${++this.idCounter}_${Date.now()}`;
+    }
+    /**
+     * Truncate a string for summary display.
+     */
+    truncate(value, maxLength = 100) {
+        const str = typeof value === "string" ? value : JSON.stringify(value);
+        if (str.length <= maxLength)
+            return str;
+        return str.substring(0, maxLength - 3) + "...";
+    }
+    /**
+     * Start tracking a node execution.
+     */
+    startExecution(name, type, input) {
+        const id = this.generateId();
+        const metrics = {
+            id,
+            name,
+            type,
+            startTime: Date.now(),
+            endTime: 0,
+            durationMs: 0,
+            success: false,
+            inputSummary: input !== undefined ? this.truncate(input) : undefined,
+            children: [],
+        };
+        if (this.executionStack.length > 0) {
+            // Nested execution - add as child
+            const parent = this.executionStack[this.executionStack.length - 1];
+            metrics.order = parent.children?.length ?? 0;
+            parent.children?.push(metrics);
+        }
+        else {
+            // Top-level execution
+            this.executions.push(metrics);
+        }
+        this.executionStack.push(metrics);
+        this.currentExecution = metrics;
+        return id;
+    }
+    /**
+     * Complete a node execution.
+     */
+    endExecution(id, success, output, tokenUsage, error) {
+        const metrics = this.findExecution(id);
+        if (!metrics)
+            return;
+        metrics.endTime = Date.now();
+        metrics.durationMs = metrics.endTime - metrics.startTime;
+        metrics.success = success;
+        metrics.outputSummary =
+            output !== undefined ? this.truncate(output) : undefined;
+        metrics.tokenUsage = tokenUsage;
+        metrics.error = error;
+        // Pop from stack
+        const index = this.executionStack.findIndex((e) => e.id === id);
+        if (index !== -1) {
+            this.executionStack.splice(index, 1);
+        }
+        this.currentExecution =
+            this.executionStack[this.executionStack.length - 1] ?? null;
+    }
+    /**
+     * Find an execution by ID.
+     */
+    findExecution(id) {
+        const search = (metrics) => {
+            for (const m of metrics) {
+                if (m.id === id)
+                    return m;
+                if (m.children) {
+                    const found = search(m.children);
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        return search(this.executions);
+    }
+    /**
+     * Add token usage to the current execution.
+     */
+    addTokenUsage(usage) {
+        if (this.currentExecution) {
+            if (this.currentExecution.tokenUsage) {
+                this.currentExecution.tokenUsage.inputTokens += usage.inputTokens;
+                this.currentExecution.tokenUsage.outputTokens += usage.outputTokens;
+                this.currentExecution.tokenUsage.totalTokens += usage.totalTokens;
+            }
+            else {
+                this.currentExecution.tokenUsage = { ...usage };
+            }
+        }
+    }
+    /**
+     * Get all collected metrics.
+     */
+    getExecutions() {
+        return this.executions;
+    }
+    /**
+     * Calculate aggregate metrics.
+     */
+    getAggregateMetrics() {
+        const totalTokens = {
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+        };
+        let nodeCount = 0;
+        let successCount = 0;
+        let failureCount = 0;
+        let totalDurationMs = 0;
+        const aggregate = (metrics) => {
+            for (const m of metrics) {
+                nodeCount++;
+                if (m.success)
+                    successCount++;
+                else
+                    failureCount++;
+                if (m.tokenUsage) {
+                    totalTokens.inputTokens += m.tokenUsage.inputTokens;
+                    totalTokens.outputTokens += m.tokenUsage.outputTokens;
+                    totalTokens.totalTokens += m.tokenUsage.totalTokens;
+                }
+                if (m.children) {
+                    aggregate(m.children);
+                }
+            }
+        };
+        aggregate(this.executions);
+        // Total duration is from first start to last end
+        if (this.executions.length > 0) {
+            const firstStart = Math.min(...this.executions.map((e) => e.startTime));
+            const lastEnd = Math.max(...this.executions.map((e) => e.endTime));
+            totalDurationMs = lastEnd - firstStart;
+        }
+        return {
+            totalDurationMs,
+            totalTokens,
+            nodeCount,
+            successCount,
+            failureCount,
+            stages: this.executions,
+            structure: this.buildStructure(),
+        };
+    }
+    /**
+     * Build pipeline structure for visualization.
+     */
+    buildStructure() {
+        const buildNode = (metrics) => {
+            const node = {
+                type: metrics.type,
+                name: metrics.name,
+            };
+            if (metrics.children && metrics.children.length > 0) {
+                node.children = metrics.children.map(buildNode);
+            }
+            return node;
+        };
+        if (this.executions.length === 1) {
+            return buildNode(this.executions[0]);
+        }
+        return {
+            type: "pipeline",
+            name: "root",
+            children: this.executions.map(buildNode),
+        };
+    }
+    /**
+     * Reset all collected metrics.
+     */
+    reset() {
+        this.executions = [];
+        this.currentExecution = null;
+        this.executionStack = [];
+        this.idCounter = 0;
+    }
+    /**
+     * Generate a simple text-based visualization of the pipeline.
+     */
+    toTextVisualization() {
+        const lines = [];
+        const render = (metrics, indent = 0) => {
+            const prefix = "  ".repeat(indent);
+            const status = metrics.success ? "✓" : "✗";
+            const duration = `${metrics.durationMs}ms`;
+            const tokens = metrics.tokenUsage
+                ? ` [${metrics.tokenUsage.totalTokens} tokens]`
+                : "";
+            lines.push(`${prefix}${status} ${metrics.name} (${metrics.type}) - ${duration}${tokens}`);
+            if (metrics.children) {
+                for (const child of metrics.children) {
+                    render(child, indent + 1);
+                }
+            }
+        };
+        for (const execution of this.executions) {
+            render(execution);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Generate a JSON representation suitable for external visualization tools.
+     */
+    toJSON() {
+        return JSON.stringify(this.getAggregateMetrics(), null, 2);
+    }
+}
+exports.MetricsCollector = MetricsCollector;
+/**
+ * Global metrics collector instance.
+ * Can be replaced with a custom instance if needed.
+ */
+let globalCollector = null;
+/**
+ * Get or create the global metrics collector.
+ */
+function getMetricsCollector() {
+    if (!globalCollector) {
+        globalCollector = new MetricsCollector();
+    }
+    return globalCollector;
+}
+/**
+ * Set a custom global metrics collector.
+ */
+function setMetricsCollector(collector) {
+    globalCollector = collector;
+}
+/**
+ * Create a new metrics collector (for isolated tracking).
+ */
+function createMetricsCollector() {
+    return new MetricsCollector();
+}
+//# sourceMappingURL=GraphMetrics.js.map

package/dist/graph/MapExecutor.d.ts

@@ -0,0 +1,39 @@
+import { BaseExecutor, GraphNode } from "./BaseExecutor";
+/**
+ * Options for configuring map execution behavior.
+ */
+export interface MapExecutorOptions {
+    /**
+     * Maximum number of concurrent executions.
+     * If undefined, all items are processed in parallel.
+     * @default undefined (unlimited)
+     */
+    concurrency?: number;
+}
+/**
+ * Maps a processor over each item in an array of inputs.
+ * Similar to Array.map but for async GraphNode processing.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new MapExecutor(summaryAgent);
+ * const summaries = await mapper.execute(["doc1", "doc2", "doc3"]);
+ * ```
+ */
+export declare class MapExecutor<TItem = string, TResult = string> extends BaseExecutor<TItem[], TResult[]> {
+    private processor;
+    private options;
+    constructor(processor: GraphNode<TItem, TResult>, options?: MapExecutorOptions);
+    /**
+     * Processes each item in the input array through the processor.
+     * @param input - Array of items to process
+     * @returns Array of processed results
+     * @throws Error if input is not an array
+     */
+    execute(input: TItem[]): Promise<TResult[]>;
+    /**
+     * Processes items with a concurrency limit.
+     */
+    private executeWithConcurrency;
+}
+//# sourceMappingURL=MapExecutor.d.ts.map

package/dist/graph/MapExecutor.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapExecutor = void 0;
+const BaseExecutor_1 = require("./BaseExecutor");
+/**
+ * Maps a processor over each item in an array of inputs.
+ * Similar to Array.map but for async GraphNode processing.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new MapExecutor(summaryAgent);
+ * const summaries = await mapper.execute(["doc1", "doc2", "doc3"]);
+ * ```
+ */
+class MapExecutor extends BaseExecutor_1.BaseExecutor {
+    constructor(processor, options = {}) {
+        super();
+        this.name = "MapExecutor";
+        this.nodeType = "map";
+        this.processor = processor;
+        this.options = options;
+    }
+    /**
+     * Processes each item in the input array through the processor.
+     * @param input - Array of items to process
+     * @returns Array of processed results
+     * @throws Error if input is not an array
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "map", input);
+        if (!Array.isArray(input)) {
+            const error = new Error("MapExecutor requires an array input");
+            if (execId)
+                collector?.endExecution(execId, false, undefined, undefined, error.message);
+            throw error;
+        }
+        if (input.length === 0) {
+            if (execId)
+                collector?.endExecution(execId, true, []);
+            return [];
+        }
+        try {
+            let results;
+            if (this.options.concurrency !== undefined) {
+                results = await this.executeWithConcurrency(input, this.options.concurrency);
+            }
+            else {
+                // Process all items in parallel with metrics
+                results = await Promise.all(input.map(async (item, index) => {
+                    const itemExecId = collector?.startExecution(`${this.processor.name ?? "Processor"} [${index}]`, "agent", item);
+                    try {
+                        const result = await this.processor.execute(item);
+                        if (itemExecId)
+                            collector?.endExecution(itemExecId, true, result);
+                        return result;
+                    }
+                    catch (error) {
+                        if (itemExecId) {
+                            collector?.endExecution(itemExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                        }
+                        throw error;
+                    }
+                }));
+            }
+            if (execId)
+                collector?.endExecution(execId, true, results);
+            return results;
+        }
+        catch (error) {
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Processes items with a concurrency limit.
+     */
+    async executeWithConcurrency(items, concurrency) {
+        const results = new Array(items.length);
+        const executing = [];
+        const collector = this.getCollector();
+        for (let i = 0; i < items.length; i++) {
+            const index = i;
+            const item = items[i];
+            const promise = (async () => {
+                const itemExecId = collector?.startExecution(`${this.processor.name ?? "Processor"} [${index}]`, "agent", item);
+                try {
+                    const result = await this.processor.execute(item);
+                    results[index] = result;
+                    if (itemExecId)
+                        collector?.endExecution(itemExecId, true, result);
+                }
+                catch (error) {
+                    if (itemExecId) {
+                        collector?.endExecution(itemExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                    }
+                    throw error;
+                }
+            })();
+            executing.push(promise);
+            if (executing.length >= concurrency) {
+                await Promise.race(executing);
+                // Remove completed promises
+                for (let j = executing.length - 1; j >= 0; j--) {
+                    // Check if promise is settled by racing with an immediate resolve
+                    const isSettled = await Promise.race([
+                        executing[j].then(() => true).catch(() => true),
+                        Promise.resolve(false),
+                    ]);
+                    if (isSettled) {
+                        executing.splice(j, 1);
+                    }
+                }
+            }
+        }
+        await Promise.all(executing);
+        return results;
+    }
+}
+exports.MapExecutor = MapExecutor;
+//# sourceMappingURL=MapExecutor.js.map

package/dist/graph/ParallelExecutor.d.ts

@@ -0,0 +1,51 @@
+import { BaseAgent } from "../agents/BaseAgent";
+import { BaseExecutor } from "./BaseExecutor";
+/**
+ * Options for configuring parallel execution behavior.
+ */
+export interface ParallelExecutorOptions {
+    /**
+     * If true, each agent receives only the original input.
+     * If false, agents receive the input with shared context.
+     * @default true
+     */
+    isolatedExecution?: boolean;
+    /**
+     * If true, wraps the input in a JSON object with originalQuestion.
+     * If false, passes the raw input to each agent.
+     * @default true
+     */
+    wrapInput?: boolean;
+}
+/**
+ * Executes multiple agents in parallel on the same input.
+ * Returns an array of results from all agents.
+ *
+ * @example
+ * ```typescript
+ * const executor = new ParallelExecutor({}, expertA, expertB, expertC);
+ * const results = await executor.execute("Analyze this data");
+ * // results is string[] with each expert's response
+ * ```
+ */
+export declare class ParallelExecutor extends BaseExecutor<string, string[]> {
+    private agents;
+    private options;
+    constructor(options?: ParallelExecutorOptions, ...agents: BaseAgent[]);
+    /**
+     * Executes all agents in parallel with the same input.
+     * @param input - The input string to send to all agents
+     * @returns Array of results from each agent
+     */
+    execute(input: string): Promise<string[]>;
+    /**
+     * Attempt to extract token usage from an agent.
+     * Converts from agent's snake_case format to metrics camelCase format.
+     */
+    private extractTokenUsage;
+    /**
+     * Returns the number of agents that will execute in parallel.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=ParallelExecutor.d.ts.map

package/dist/graph/ParallelExecutor.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParallelExecutor = void 0;
+const BaseExecutor_1 = require("./BaseExecutor");
+/**
+ * Executes multiple agents in parallel on the same input.
+ * Returns an array of results from all agents.
+ *
+ * @example
+ * ```typescript
+ * const executor = new ParallelExecutor({}, expertA, expertB, expertC);
+ * const results = await executor.execute("Analyze this data");
+ * // results is string[] with each expert's response
+ * ```
+ */
+class ParallelExecutor extends BaseExecutor_1.BaseExecutor {
+    constructor(options = {}, ...agents) {
+        super();
+        this.name = "ParallelExecutor";
+        this.nodeType = "parallel";
+        this.agents = agents;
+        this.options = {
+            isolatedExecution: options.isolatedExecution ?? true,
+            wrapInput: options.wrapInput ?? true,
+        };
+    }
+    /**
+     * Executes all agents in parallel with the same input.
+     * @param input - The input string to send to all agents
+     * @returns Array of results from each agent
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "parallel", input);
+        if (this.agents.length === 0) {
+            if (execId)
+                collector?.endExecution(execId, true, []);
+            return [];
+        }
+        try {
+            const executionPromises = this.agents.map(async (agent, index) => {
+                const agentName = agent.getName?.() ?? `Agent ${index + 1}`;
+                const agentExecId = collector?.startExecution(agentName, "agent", input);
+                const agentInput = this.options.wrapInput
+                    ? JSON.stringify({
+                        originalQuestion: input,
+                        ...(this.options.isolatedExecution
+                            ? {}
+                            : { sharedContext: true }),
+                    })
+                    : input;
+                try {
+                    const result = await agent.execute(agentInput);
+                    // Try to get token usage from agent
+                    const tokenUsage = this.extractTokenUsage(agent);
+                    if (agentExecId) {
+                        collector?.endExecution(agentExecId, true, result, tokenUsage);
+                    }
+                    return result;
+                }
+                catch (error) {
+                    if (agentExecId) {
+                        collector?.endExecution(agentExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                    }
+                    throw error;
+                }
+            });
+            const results = await Promise.all(executionPromises);
+            if (execId)
+                collector?.endExecution(execId, true, results);
+            return results;
+        }
+        catch (error) {
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Attempt to extract token usage from an agent.
+     * Converts from agent's snake_case format to metrics camelCase format.
+     */
+    extractTokenUsage(agent) {
+        const agentWithUsage = agent;
+        if (!agentWithUsage.lastTokenUsage)
+            return undefined;
+        // Convert from snake_case to camelCase
+        return {
+            inputTokens: agentWithUsage.lastTokenUsage.input_tokens,
+            outputTokens: agentWithUsage.lastTokenUsage.output_tokens,
+            totalTokens: agentWithUsage.lastTokenUsage.total_tokens,
+        };
+    }
+    /**
+     * Returns the number of agents that will execute in parallel.
+     */
+    get length() {
+        return this.agents.length;
+    }
+}
+exports.ParallelExecutor = ParallelExecutor;
+//# sourceMappingURL=ParallelExecutor.js.map

package/dist/graph/Pipeline.d.ts

@@ -0,0 +1,44 @@
+import { GraphNode, BaseExecutor, MetricsCollector } from "./BaseExecutor";
+/**
+ * Builds a pipeline of graph nodes that execute in sequence,
+ * where the output of each stage becomes the input of the next.
+ *
+ * Unlike SequentialExecutor which is specific to agents,
+ * Pipeline can chain any GraphNode implementations together.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   AgentGraph.sequential(researchAgent, factChecker),
+ *   AgentGraph.parallel({}, expertA, expertB),
+ *   customTransformer,
+ *   AgentGraph.votingSystem(judgeAgent)
+ * );
+ * const result = await pipeline.execute("Research topic X");
+ * ```
+ */
+export declare class Pipeline<TInput = unknown, TOutput = unknown> extends BaseExecutor<TInput, TOutput> implements GraphNode<TInput, TOutput> {
+    private stages;
+    constructor(...stages: GraphNode<unknown, unknown>[]);
+    /**
+     * Adds a stage to the end of the pipeline.
+     * @param stage - The GraphNode to add
+     * @returns The pipeline instance for chaining
+     */
+    addStage<TStageOutput>(stage: GraphNode<TOutput, TStageOutput>): Pipeline<TInput, TStageOutput>;
+    /**
+     * Executes all stages in sequence.
+     * @param input - The initial input
+     * @returns The output from the final stage
+     */
+    execute(input: TInput): Promise<TOutput>;
+    /**
+     * Returns the number of stages in the pipeline.
+     */
+    get length(): number;
+    /**
+     * Enable metrics collection and return the pipeline for chaining.
+     */
+    withMetrics(collector?: MetricsCollector): this;
+}
+//# sourceMappingURL=Pipeline.d.ts.map