@agentionai/agents 0.3.0-beta

package/dist/graph/AgentGraph.d.ts

@@ -0,0 +1,99 @@
+import { BaseAgent } from "../agents/BaseAgent";
+import { GraphNode } from "./BaseExecutor";
+import { MapExecutor, MapExecutorOptions } from "./MapExecutor";
+import { ParallelExecutor, ParallelExecutorOptions } from "./ParallelExecutor";
+import { Pipeline } from "./Pipeline";
+import { RouterExecutor, RouterExecutorOptions, Route } from "./RouterExecutor";
+import { SequentialExecutor, SequentialExecutorOptions } from "./SequentialExecutor";
+import { VotingSystem, VotingSystemOptions } from "./VotingSystem";
+export { GraphNode } from "./BaseExecutor";
+export { SequentialExecutor, SequentialExecutorOptions, } from "./SequentialExecutor";
+export { ParallelExecutor, ParallelExecutorOptions } from "./ParallelExecutor";
+export { Pipeline } from "./Pipeline";
+export { MapExecutor, MapExecutorOptions } from "./MapExecutor";
+export { VotingSystem, VotingSystemOptions, VotingInput } from "./VotingSystem";
+export { RouterExecutor, RouterExecutorOptions, Route } from "./RouterExecutor";
+export { BaseExecutor, PipelineContext, ContextualInput, NodeInput, NodeOutput, MetricsCollector, NodeExecutionMetrics, MetricsTokenUsage, GraphNodeType, } from "./BaseExecutor";
+export { PipelineMetrics, PipelineStructure, getMetricsCollector, setMetricsCollector, createMetricsCollector, } from "./GraphMetrics";
+/**
+ * Factory class for building agent graphs and workflows.
+ * Provides static methods to create various execution patterns.
+ *
+ * @example
+ * ```typescript
+ * // Simple sequential workflow
+ * const workflow = AgentGraph.sequential(researchAgent, summaryAgent);
+ *
+ * // Parallel experts with voting
+ * const pipeline = AgentGraph.pipeline(
+ *   AgentGraph.parallel({}, expertA, expertB, expertC),
+ *   { execute: async (results) => ({ originalInput: query, solutions: results }) },
+ *   AgentGraph.votingSystem(judgeAgent)
+ * );
+ * ```
+ */
+export declare class AgentGraph {
+    /**
+     * Creates a sequential executor that chains agents together.
+     * Output of each agent becomes input to the next.
+     *
+     * @param agents - Agents to execute in sequence
+     * @returns SequentialExecutor instance
+     */
+    static sequential(...agents: BaseAgent[]): SequentialExecutor;
+    static sequential(options: SequentialExecutorOptions, ...agents: BaseAgent[]): SequentialExecutor;
+    /**
+     * Creates a parallel executor that runs agents concurrently.
+     * All agents receive the same input and results are collected.
+     *
+     * @param options - Configuration options
+     * @param agents - Agents to execute in parallel
+     * @returns ParallelExecutor instance
+     */
+    static parallel(options?: ParallelExecutorOptions, ...agents: BaseAgent[]): ParallelExecutor;
+    /**
+     * Creates a voting system with a judge agent.
+     * Used to select or synthesize the best answer from multiple solutions.
+     *
+     * @param judge - Agent that will evaluate and select the best answer
+     * @param options - Configuration options
+     * @returns VotingSystem instance
+     */
+    static votingSystem(judge: BaseAgent, options?: VotingSystemOptions): VotingSystem;
+    /**
+     * Creates a map executor that applies a processor to each item in an array.
+     *
+     * @param processor - GraphNode to apply to each item
+     * @param options - Configuration options
+     * @returns MapExecutor instance
+     */
+    static map<TItem = string, TResult = string>(processor: GraphNode<TItem, TResult>, options?: MapExecutorOptions): MapExecutor<TItem, TResult>;
+    /**
+     * Creates a pipeline that chains multiple graph nodes together.
+     * Output of each stage becomes input to the next.
+     *
+     * @param stages - GraphNodes to execute in sequence
+     * @returns Pipeline instance
+     */
+    static pipeline<TInput = unknown, TOutput = unknown>(...stages: GraphNode<unknown, unknown>[]): Pipeline<TInput, TOutput>;
+    /**
+     * Creates a router executor that routes input to one of several handlers.
+     * A router agent analyzes the input and selects the most appropriate route.
+     *
+     * @param router - Agent that decides which route to select
+     * @param routes - Array of available routes with names, descriptions, and handlers
+     * @param options - Configuration options
+     * @returns RouterExecutor instance
+     *
+     * @example
+     * ```typescript
+     * const router = AgentGraph.router(routerAgent, [
+     *   { name: "technical", description: "Technical questions", handler: techAgent },
+     *   { name: "general", description: "General questions", handler: generalAgent },
+     * ]);
+     * const result = await router.execute("How do I fix this bug?");
+     * ```
+     */
+    static router(router: BaseAgent, routes: Route[], options?: RouterExecutorOptions): RouterExecutor;
+}
+//# sourceMappingURL=AgentGraph.d.ts.map

package/dist/graph/AgentGraph.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentGraph = exports.createMetricsCollector = exports.setMetricsCollector = exports.getMetricsCollector = exports.MetricsCollector = exports.BaseExecutor = exports.RouterExecutor = exports.VotingSystem = exports.MapExecutor = exports.Pipeline = exports.ParallelExecutor = exports.SequentialExecutor = void 0;
+const MapExecutor_1 = require("./MapExecutor");
+const ParallelExecutor_1 = require("./ParallelExecutor");
+const Pipeline_1 = require("./Pipeline");
+const RouterExecutor_1 = require("./RouterExecutor");
+const SequentialExecutor_1 = require("./SequentialExecutor");
+const VotingSystem_1 = require("./VotingSystem");
+var SequentialExecutor_2 = require("./SequentialExecutor");
+Object.defineProperty(exports, "SequentialExecutor", { enumerable: true, get: function () { return SequentialExecutor_2.SequentialExecutor; } });
+var ParallelExecutor_2 = require("./ParallelExecutor");
+Object.defineProperty(exports, "ParallelExecutor", { enumerable: true, get: function () { return ParallelExecutor_2.ParallelExecutor; } });
+var Pipeline_2 = require("./Pipeline");
+Object.defineProperty(exports, "Pipeline", { enumerable: true, get: function () { return Pipeline_2.Pipeline; } });
+var MapExecutor_2 = require("./MapExecutor");
+Object.defineProperty(exports, "MapExecutor", { enumerable: true, get: function () { return MapExecutor_2.MapExecutor; } });
+var VotingSystem_2 = require("./VotingSystem");
+Object.defineProperty(exports, "VotingSystem", { enumerable: true, get: function () { return VotingSystem_2.VotingSystem; } });
+var RouterExecutor_2 = require("./RouterExecutor");
+Object.defineProperty(exports, "RouterExecutor", { enumerable: true, get: function () { return RouterExecutor_2.RouterExecutor; } });
+var BaseExecutor_1 = require("./BaseExecutor");
+Object.defineProperty(exports, "BaseExecutor", { enumerable: true, get: function () { return BaseExecutor_1.BaseExecutor; } });
+Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return BaseExecutor_1.MetricsCollector; } });
+var GraphMetrics_1 = require("./GraphMetrics");
+Object.defineProperty(exports, "getMetricsCollector", { enumerable: true, get: function () { return GraphMetrics_1.getMetricsCollector; } });
+Object.defineProperty(exports, "setMetricsCollector", { enumerable: true, get: function () { return GraphMetrics_1.setMetricsCollector; } });
+Object.defineProperty(exports, "createMetricsCollector", { enumerable: true, get: function () { return GraphMetrics_1.createMetricsCollector; } });
+/**
+ * Factory class for building agent graphs and workflows.
+ * Provides static methods to create various execution patterns.
+ *
+ * @example
+ * ```typescript
+ * // Simple sequential workflow
+ * const workflow = AgentGraph.sequential(researchAgent, summaryAgent);
+ *
+ * // Parallel experts with voting
+ * const pipeline = AgentGraph.pipeline(
+ *   AgentGraph.parallel({}, expertA, expertB, expertC),
+ *   { execute: async (results) => ({ originalInput: query, solutions: results }) },
+ *   AgentGraph.votingSystem(judgeAgent)
+ * );
+ * ```
+ */
+class AgentGraph {
+    static sequential(...args) {
+        return new SequentialExecutor_1.SequentialExecutor(...args);
+    }
+    /**
+     * Creates a parallel executor that runs agents concurrently.
+     * All agents receive the same input and results are collected.
+     *
+     * @param options - Configuration options
+     * @param agents - Agents to execute in parallel
+     * @returns ParallelExecutor instance
+     */
+    static parallel(options = {}, ...agents) {
+        return new ParallelExecutor_1.ParallelExecutor(options, ...agents);
+    }
+    /**
+     * Creates a voting system with a judge agent.
+     * Used to select or synthesize the best answer from multiple solutions.
+     *
+     * @param judge - Agent that will evaluate and select the best answer
+     * @param options - Configuration options
+     * @returns VotingSystem instance
+     */
+    static votingSystem(judge, options = {}) {
+        return new VotingSystem_1.VotingSystem(judge, options);
+    }
+    /**
+     * Creates a map executor that applies a processor to each item in an array.
+     *
+     * @param processor - GraphNode to apply to each item
+     * @param options - Configuration options
+     * @returns MapExecutor instance
+     */
+    static map(processor, options = {}) {
+        return new MapExecutor_1.MapExecutor(processor, options);
+    }
+    /**
+     * Creates a pipeline that chains multiple graph nodes together.
+     * Output of each stage becomes input to the next.
+     *
+     * @param stages - GraphNodes to execute in sequence
+     * @returns Pipeline instance
+     */
+    static pipeline(...stages) {
+        return new Pipeline_1.Pipeline(...stages);
+    }
+    /**
+     * Creates a router executor that routes input to one of several handlers.
+     * A router agent analyzes the input and selects the most appropriate route.
+     *
+     * @param router - Agent that decides which route to select
+     * @param routes - Array of available routes with names, descriptions, and handlers
+     * @param options - Configuration options
+     * @returns RouterExecutor instance
+     *
+     * @example
+     * ```typescript
+     * const router = AgentGraph.router(routerAgent, [
+     *   { name: "technical", description: "Technical questions", handler: techAgent },
+     *   { name: "general", description: "General questions", handler: generalAgent },
+     * ]);
+     * const result = await router.execute("How do I fix this bug?");
+     * ```
+     */
+    static router(router, routes, options = {}) {
+        return new RouterExecutor_1.RouterExecutor(router, routes, options);
+    }
+}
+exports.AgentGraph = AgentGraph;
+//# sourceMappingURL=AgentGraph.js.map

package/dist/graph/BaseExecutor.d.ts

@@ -0,0 +1,86 @@
+import { MetricsCollector, NodeExecutionMetrics } from "./GraphMetrics";
+/**
+ * Type identifier for graph nodes.
+ */
+export type GraphNodeType = "sequential" | "parallel" | "pipeline" | "map" | "voting" | "router" | "agent" | "custom";
+/**
+ * Represents a node in the agent graph that can process inputs and produce outputs.
+ * Uses generics for type-safe input/output handling.
+ */
+export interface GraphNode<TInput = unknown, TOutput = unknown> {
+    execute(input: TInput): Promise<TOutput>;
+    /** Optional name for the node (used in metrics) */
+    name?: string;
+    /** Type of the node (used in metrics and visualization) */
+    nodeType?: GraphNodeType;
+}
+/**
+ * Options for executor execution with metrics tracking.
+ */
+export interface ExecutorOptions {
+    /** Metrics collector for tracking execution data */
+    metrics?: MetricsCollector;
+    /** Whether to collect metrics (default: false) */
+    collectMetrics?: boolean;
+}
+/**
+ * Base class for executors that implement the GraphNode interface.
+ * Provides a foundation for building type-safe graph executors with optional metrics.
+ */
+export declare abstract class BaseExecutor<TInput = unknown, TOutput = unknown> implements GraphNode<TInput, TOutput> {
+    /** Display name for this executor */
+    name: string;
+    /** Type of this node for metrics and visualization */
+    nodeType: GraphNodeType;
+    /** Metrics collector for this executor */
+    protected metricsCollector?: MetricsCollector;
+    /** Whether metrics collection is enabled */
+    protected collectMetrics: boolean;
+    /**
+     * Enable metrics collection for this executor.
+     */
+    withMetrics(collector?: MetricsCollector): this;
+    /**
+     * Set a custom name for this executor (used in metrics).
+     */
+    withName(name: string): this;
+    /**
+     * Get the metrics collector (creates one if needed and metrics enabled).
+     */
+    protected getCollector(): MetricsCollector | undefined;
+    /**
+     * Get collected metrics (if metrics collection is enabled).
+     */
+    getMetrics(): NodeExecutionMetrics[] | undefined;
+    /**
+     * Get the metrics collector instance.
+     */
+    getMetricsCollector(): MetricsCollector | undefined;
+    abstract execute(input: TInput): Promise<TOutput>;
+}
+/**
+ * Configuration for passing context through pipeline stages.
+ */
+export interface PipelineContext {
+    /** The original input that started the pipeline */
+    originalInput?: unknown;
+    /** Metadata that can be passed between stages */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input wrapper that includes both the value and pipeline context.
+ */
+export interface ContextualInput<T = unknown> {
+    value: T;
+    context: PipelineContext;
+}
+/**
+ * Helper type for extracting input type from a GraphNode
+ */
+export type NodeInput<T> = T extends GraphNode<infer I, unknown> ? I : never;
+/**
+ * Helper type for extracting output type from a GraphNode
+ */
+export type NodeOutput<T> = T extends GraphNode<unknown, infer O> ? O : never;
+export { MetricsCollector, NodeExecutionMetrics, MetricsTokenUsage, } from "./GraphMetrics";
+//# sourceMappingURL=BaseExecutor.d.ts.map

package/dist/graph/BaseExecutor.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsCollector = exports.BaseExecutor = void 0;
+const GraphMetrics_1 = require("./GraphMetrics");
+/**
+ * Base class for executors that implement the GraphNode interface.
+ * Provides a foundation for building type-safe graph executors with optional metrics.
+ */
+class BaseExecutor {
+    constructor() {
+        /** Display name for this executor */
+        this.name = this.constructor.name;
+        /** Type of this node for metrics and visualization */
+        this.nodeType = "custom";
+        /** Whether metrics collection is enabled */
+        this.collectMetrics = false;
+    }
+    /**
+     * Enable metrics collection for this executor.
+     */
+    withMetrics(collector) {
+        this.collectMetrics = true;
+        this.metricsCollector = collector;
+        return this;
+    }
+    /**
+     * Set a custom name for this executor (used in metrics).
+     */
+    withName(name) {
+        this.name = name;
+        return this;
+    }
+    /**
+     * Get the metrics collector (creates one if needed and metrics enabled).
+     */
+    getCollector() {
+        if (!this.collectMetrics)
+            return undefined;
+        if (!this.metricsCollector) {
+            this.metricsCollector = new GraphMetrics_1.MetricsCollector();
+        }
+        return this.metricsCollector;
+    }
+    /**
+     * Get collected metrics (if metrics collection is enabled).
+     */
+    getMetrics() {
+        return this.metricsCollector?.getExecutions();
+    }
+    /**
+     * Get the metrics collector instance.
+     */
+    getMetricsCollector() {
+        return this.metricsCollector;
+    }
+}
+exports.BaseExecutor = BaseExecutor;
+// Re-export metrics types for convenience
+var GraphMetrics_2 = require("./GraphMetrics");
+Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return GraphMetrics_2.MetricsCollector; } });
+//# sourceMappingURL=BaseExecutor.js.map

package/dist/graph/GraphMetrics.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Metrics and observability for graph execution.
+ * Tracks timing, token usage, and pipeline structure for analysis and visualization.
+ */
+/**
+ * Token usage statistics from an LLM call (for metrics tracking).
+ */
+export interface MetricsTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * Metrics for a single node execution.
+ */
+export interface NodeExecutionMetrics {
+    /** Unique identifier for this execution */
+    id: string;
+    /** Name of the node/agent */
+    name: string;
+    /** Type of executor (sequential, parallel, pipeline, map, voting, router, agent) */
+    type: "sequential" | "parallel" | "pipeline" | "map" | "voting" | "router" | "agent" | "custom";
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Token usage if applicable */
+    tokenUsage?: MetricsTokenUsage;
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Input summary (truncated for large inputs) */
+    inputSummary?: string;
+    /** Output summary (truncated for large outputs) */
+    outputSummary?: string;
+    /** Child node metrics (for composite executors) */
+    children?: NodeExecutionMetrics[];
+    /** Execution order within parent (for sequential/parallel) */
+    order?: number;
+}
+/**
+ * Aggregate metrics for a complete pipeline execution.
+ */
+export interface PipelineMetrics {
+    /** Total execution time in milliseconds */
+    totalDurationMs: number;
+    /** Total tokens used across all nodes */
+    totalTokens: MetricsTokenUsage;
+    /** Number of nodes executed */
+    nodeCount: number;
+    /** Number of successful executions */
+    successCount: number;
+    /** Number of failed executions */
+    failureCount: number;
+    /** Detailed metrics for each stage */
+    stages: NodeExecutionMetrics[];
+    /** Pipeline structure for visualization */
+    structure: PipelineStructure;
+}
+/**
+ * Represents the structure of a pipeline for visualization.
+ */
+export interface PipelineStructure {
+    /** Type of this node */
+    type: "sequential" | "parallel" | "pipeline" | "map" | "voting" | "router" | "agent" | "custom";
+    /** Display name */
+    name: string;
+    /** Child nodes */
+    children?: PipelineStructure[];
+}
+/**
+ * Collector for gathering metrics during graph execution.
+ */
+export declare class MetricsCollector {
+    private executions;
+    private currentExecution;
+    private executionStack;
+    private idCounter;
+    /**
+     * Generate a unique execution ID.
+     */
+    private generateId;
+    /**
+     * Truncate a string for summary display.
+     */
+    private truncate;
+    /**
+     * Start tracking a node execution.
+     */
+    startExecution(name: string, type: NodeExecutionMetrics["type"], input?: unknown): string;
+    /**
+     * Complete a node execution.
+     */
+    endExecution(id: string, success: boolean, output?: unknown, tokenUsage?: MetricsTokenUsage, error?: string): void;
+    /**
+     * Find an execution by ID.
+     */
+    private findExecution;
+    /**
+     * Add token usage to the current execution.
+     */
+    addTokenUsage(usage: MetricsTokenUsage): void;
+    /**
+     * Get all collected metrics.
+     */
+    getExecutions(): NodeExecutionMetrics[];
+    /**
+     * Calculate aggregate metrics.
+     */
+    getAggregateMetrics(): PipelineMetrics;
+    /**
+     * Build pipeline structure for visualization.
+     */
+    private buildStructure;
+    /**
+     * Reset all collected metrics.
+     */
+    reset(): void;
+    /**
+     * Generate a simple text-based visualization of the pipeline.
+     */
+    toTextVisualization(): string;
+    /**
+     * Generate a JSON representation suitable for external visualization tools.
+     */
+    toJSON(): string;
+}
+/**
+ * Get or create the global metrics collector.
+ */
+export declare function getMetricsCollector(): MetricsCollector;
+/**
+ * Set a custom global metrics collector.
+ */
+export declare function setMetricsCollector(collector: MetricsCollector): void;
+/**
+ * Create a new metrics collector (for isolated tracking).
+ */
+export declare function createMetricsCollector(): MetricsCollector;
+//# sourceMappingURL=GraphMetrics.d.ts.map