@agentionai/agents 0.3.0-beta

package/dist/graph/Pipeline.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pipeline = void 0;
+const BaseExecutor_1 = require("./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");
+ * ```
+ */
+class Pipeline extends BaseExecutor_1.BaseExecutor {
+    constructor(...stages) {
+        super();
+        this.stages = [];
+        this.name = "Pipeline";
+        this.nodeType = "pipeline";
+        this.stages = stages;
+    }
+    /**
+     * Adds a stage to the end of the pipeline.
+     * @param stage - The GraphNode to add
+     * @returns The pipeline instance for chaining
+     */
+    addStage(stage) {
+        this.stages.push(stage);
+        return this;
+    }
+    /**
+     * Executes all stages in sequence.
+     * @param input - The initial input
+     * @returns The output from the final stage
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "pipeline", input);
+        if (this.stages.length === 0) {
+            if (execId)
+                collector?.endExecution(execId, true, input);
+            return input;
+        }
+        let result = input;
+        try {
+            for (let i = 0; i < this.stages.length; i++) {
+                const stage = this.stages[i];
+                const stageName = stage.name ?? `Stage ${i + 1}`;
+                // Get stage type from the node's nodeType property, or default to "custom"
+                const stageType = stage.nodeType ?? "custom";
+                // Only track non-executor stages directly
+                // Executors will track themselves when they have the collector
+                const isExecutor = stage instanceof BaseExecutor_1.BaseExecutor;
+                const stageExecId = !isExecutor
+                    ? collector?.startExecution(stageName, stageType, result)
+                    : undefined;
+                // Pass metrics collector to child executors
+                if (collector && isExecutor) {
+                    stage.withMetrics(collector);
+                }
+                try {
+                    result = await stage.execute(result);
+                    if (stageExecId) {
+                        collector?.endExecution(stageExecId, true, result);
+                    }
+                }
+                catch (error) {
+                    if (stageExecId) {
+                        collector?.endExecution(stageExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                    }
+                    throw error;
+                }
+            }
+            if (execId)
+                collector?.endExecution(execId, true, result);
+            return result;
+        }
+        catch (error) {
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Returns the number of stages in the pipeline.
+     */
+    get length() {
+        return this.stages.length;
+    }
+    /**
+     * Enable metrics collection and return the pipeline for chaining.
+     */
+    withMetrics(collector) {
+        super.withMetrics(collector);
+        return this;
+    }
+}
+exports.Pipeline = Pipeline;
+//# sourceMappingURL=Pipeline.js.map

package/dist/graph/RouterExecutor.d.ts

@@ -0,0 +1,89 @@
+import { BaseAgent } from "../agents/BaseAgent";
+import { BaseExecutor, GraphNode } from "./BaseExecutor";
+/**
+ * Represents a route option that the router can select.
+ */
+export interface Route<TInput = string, TOutput = string> {
+    /** Unique identifier for this route */
+    name: string;
+    /** Description of when this route should be selected */
+    description: string;
+    /** The handler to execute when this route is selected */
+    handler: GraphNode<TInput, TOutput> | BaseAgent;
+}
+/**
+ * Options for configuring the router executor.
+ */
+export interface RouterExecutorOptions {
+    /**
+     * Custom prompt template for the router agent.
+     * Use {input} for the user input and {routes} for the formatted route options.
+     */
+    promptTemplate?: string;
+    /**
+     * If true, includes the original input when executing the selected route.
+     * If false, passes only the input to the route handler.
+     * @default true
+     */
+    includeRouterContext?: boolean;
+    /**
+     * Fallback route name to use if the router fails to select a valid route.
+     * If not specified and router fails, an error is thrown.
+     */
+    fallbackRoute?: string;
+}
+/**
+ * Routes input to one of several available handlers based on an agent's decision.
+ * The router agent analyzes the input and selects the most appropriate route.
+ *
+ * @example
+ * ```typescript
+ * const router = new RouterExecutor(routerAgent, [
+ *   { name: "technical", description: "Technical questions about code", handler: techAgent },
+ *   { name: "general", description: "General knowledge questions", handler: generalAgent },
+ *   { name: "creative", description: "Creative writing tasks", handler: creativeAgent },
+ * ]);
+ *
+ * const result = await router.execute("How do I fix this TypeScript error?");
+ * // Router selects "technical" route and executes techAgent
+ * ```
+ */
+export declare class RouterExecutor extends BaseExecutor<string, string> {
+    private router;
+    private routes;
+    private options;
+    private routeNames;
+    constructor(router: BaseAgent, routes: Route[], options?: RouterExecutorOptions);
+    /**
+     * Routes the input to the appropriate handler based on the router agent's decision.
+     * @param input - The input string to route
+     * @returns The output from the selected route's handler
+     */
+    execute(input: string): Promise<string>;
+    /**
+     * Execute the selected route's handler.
+     */
+    private executeRoute;
+    /**
+     * Parse the router's response to extract the selected route name.
+     * Handles various response formats and normalizes the selection.
+     */
+    private parseRouteSelection;
+    /**
+     * Check if a value is a GraphNode.
+     */
+    private isGraphNode;
+    /**
+     * Attempt to extract token usage from an agent.
+     */
+    private extractTokenUsage;
+    /**
+     * Returns the available route names.
+     */
+    getRouteNames(): string[];
+    /**
+     * Returns the number of available routes.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=RouterExecutor.d.ts.map

package/dist/graph/RouterExecutor.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouterExecutor = void 0;
+const BaseExecutor_1 = require("./BaseExecutor");
+const DEFAULT_PROMPT_TEMPLATE = `You are a routing agent that must select the most appropriate handler for the given input.
+
+User Input: {input}
+
+Available Routes:
+{routes}
+
+Instructions:
+- Analyze the user input carefully
+- Select the single most appropriate route based on the descriptions
+- Respond with ONLY the route name, nothing else
+- Do not explain your choice, just output the route name exactly as shown`;
+/**
+ * Routes input to one of several available handlers based on an agent's decision.
+ * The router agent analyzes the input and selects the most appropriate route.
+ *
+ * @example
+ * ```typescript
+ * const router = new RouterExecutor(routerAgent, [
+ *   { name: "technical", description: "Technical questions about code", handler: techAgent },
+ *   { name: "general", description: "General knowledge questions", handler: generalAgent },
+ *   { name: "creative", description: "Creative writing tasks", handler: creativeAgent },
+ * ]);
+ *
+ * const result = await router.execute("How do I fix this TypeScript error?");
+ * // Router selects "technical" route and executes techAgent
+ * ```
+ */
+class RouterExecutor extends BaseExecutor_1.BaseExecutor {
+    constructor(router, routes, options = {}) {
+        super();
+        this.name = "RouterExecutor";
+        this.nodeType = "router";
+        this.router = router;
+        this.routes = new Map(routes.map((route) => [route.name.toLowerCase(), route]));
+        this.routeNames = routes.map((r) => r.name);
+        this.options = {
+            promptTemplate: options.promptTemplate ?? DEFAULT_PROMPT_TEMPLATE,
+            includeRouterContext: options.includeRouterContext ?? true,
+            fallbackRoute: options.fallbackRoute ?? "",
+        };
+        if (routes.length === 0) {
+            throw new Error("RouterExecutor requires at least one route");
+        }
+    }
+    /**
+     * Routes the input to the appropriate handler based on the router agent's decision.
+     * @param input - The input string to route
+     * @returns The output from the selected route's handler
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "router", input);
+        try {
+            // Build the routing prompt
+            const routesDescription = this.routeNames
+                .map((name) => {
+                const route = this.routes.get(name.toLowerCase());
+                return `- ${name}: ${route.description}`;
+            })
+                .join("\n");
+            const routingPrompt = this.options.promptTemplate
+                .replace("{input}", input)
+                .replace("{routes}", routesDescription);
+            // Execute the router agent to select a route
+            const routerName = this.router.getName?.() ?? "Router";
+            const routerExecId = collector?.startExecution(routerName, "agent", routingPrompt);
+            let selectedRouteName;
+            try {
+                const routerResponse = (await this.router.execute(routingPrompt));
+                selectedRouteName = this.parseRouteSelection(routerResponse);
+                const tokenUsage = this.extractTokenUsage(this.router);
+                if (routerExecId) {
+                    collector?.endExecution(routerExecId, true, selectedRouteName, tokenUsage);
+                }
+            }
+            catch (error) {
+                if (routerExecId) {
+                    collector?.endExecution(routerExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                }
+                throw error;
+            }
+            // Get the selected route
+            const route = this.routes.get(selectedRouteName.toLowerCase());
+            if (!route) {
+                // Try fallback if configured
+                if (this.options.fallbackRoute) {
+                    const fallbackRoute = this.routes.get(this.options.fallbackRoute.toLowerCase());
+                    if (fallbackRoute) {
+                        return this.executeRoute(fallbackRoute, input, collector, execId);
+                    }
+                }
+                throw new Error(`Router selected invalid route: "${selectedRouteName}". Available routes: ${this.routeNames.join(", ")}`);
+            }
+            return this.executeRoute(route, input, collector, execId);
+        }
+        catch (error) {
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Execute the selected route's handler.
+     */
+    async executeRoute(route, input, collector, parentExecId) {
+        const handlerName = route.name;
+        const handlerExecId = collector?.startExecution(handlerName, "agent", input);
+        try {
+            // Prepare input for the handler
+            const handlerInput = this.options.includeRouterContext
+                ? JSON.stringify({
+                    originalInput: input,
+                    selectedRoute: route.name,
+                })
+                : input;
+            let result;
+            if (this.isGraphNode(route.handler)) {
+                // Pass metrics collector to child executors
+                if (collector && route.handler instanceof BaseExecutor_1.BaseExecutor) {
+                    route.handler.withMetrics(collector);
+                }
+                result = (await route.handler.execute(handlerInput));
+            }
+            else {
+                result = (await route.handler.execute(handlerInput));
+            }
+            // Try to extract token usage if handler is an agent
+            let tokenUsage;
+            if (!this.isGraphNode(route.handler)) {
+                tokenUsage = this.extractTokenUsage(route.handler);
+            }
+            if (handlerExecId) {
+                collector?.endExecution(handlerExecId, true, result, tokenUsage);
+            }
+            if (parentExecId) {
+                collector?.endExecution(parentExecId, true, result);
+            }
+            return result;
+        }
+        catch (error) {
+            if (handlerExecId) {
+                collector?.endExecution(handlerExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Parse the router's response to extract the selected route name.
+     * Handles various response formats and normalizes the selection.
+     */
+    parseRouteSelection(response) {
+        // Clean up the response - trim whitespace and handle common formats
+        const cleaned = response.trim().toLowerCase();
+        // Direct match
+        if (this.routes.has(cleaned)) {
+            return cleaned;
+        }
+        // Try to find a route name mentioned in the response
+        for (const name of this.routeNames) {
+            if (cleaned.includes(name.toLowerCase())) {
+                return name.toLowerCase();
+            }
+        }
+        // If no match found, return the cleaned response and let caller handle the error
+        return cleaned;
+    }
+    /**
+     * Check if a value is a GraphNode.
+     */
+    isGraphNode(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            "execute" in value &&
+            typeof value.execute === "function");
+    }
+    /**
+     * Attempt to extract token usage from an agent.
+     */
+    extractTokenUsage(agent) {
+        const agentWithUsage = agent;
+        if (!agentWithUsage.lastTokenUsage)
+            return undefined;
+        return {
+            inputTokens: agentWithUsage.lastTokenUsage.input_tokens,
+            outputTokens: agentWithUsage.lastTokenUsage.output_tokens,
+            totalTokens: agentWithUsage.lastTokenUsage.total_tokens,
+        };
+    }
+    /**
+     * Returns the available route names.
+     */
+    getRouteNames() {
+        return [...this.routeNames];
+    }
+    /**
+     * Returns the number of available routes.
+     */
+    get length() {
+        return this.routes.size;
+    }
+}
+exports.RouterExecutor = RouterExecutor;
+//# sourceMappingURL=RouterExecutor.js.map

package/dist/graph/SequentialExecutor.d.ts

@@ -0,0 +1,44 @@
+import { BaseAgent } from "../agents/BaseAgent";
+import { BaseExecutor } from "./BaseExecutor";
+/**
+ * Options for configuring sequential execution behavior.
+ */
+export interface SequentialExecutorOptions {
+    /**
+     * If true, wraps the input in a JSON object with originalQuestion and resultFromPreviousAgent.
+     * If false, passes the raw result from one agent to the next.
+     * @default true
+     */
+    wrapInput?: boolean;
+}
+/**
+ * Executes agents in sequence, passing the output of each agent to the next.
+ *
+ * @example
+ * ```typescript
+ * const executor = new SequentialExecutor(researchAgent, summaryAgent);
+ * const result = await executor.execute("What is quantum computing?");
+ * ```
+ */
+export declare class SequentialExecutor extends BaseExecutor<string, string> {
+    private agents;
+    private options;
+    constructor(...args: [...BaseAgent[]] | [SequentialExecutorOptions, ...BaseAgent[]]);
+    private isAgent;
+    /**
+     * Executes agents in sequence.
+     * @param input - The initial input string
+     * @returns The final output from the last agent in the sequence
+     */
+    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 in the sequence.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=SequentialExecutor.d.ts.map

package/dist/graph/SequentialExecutor.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SequentialExecutor = void 0;
+const BaseExecutor_1 = require("./BaseExecutor");
+/**
+ * Executes agents in sequence, passing the output of each agent to the next.
+ *
+ * @example
+ * ```typescript
+ * const executor = new SequentialExecutor(researchAgent, summaryAgent);
+ * const result = await executor.execute("What is quantum computing?");
+ * ```
+ */
+class SequentialExecutor extends BaseExecutor_1.BaseExecutor {
+    constructor(...args) {
+        super();
+        this.name = "SequentialExecutor";
+        this.nodeType = "sequential";
+        // Check if first argument is options object
+        if (args.length > 0 && !this.isAgent(args[0])) {
+            const [options, ...agents] = args;
+            this.options = {
+                wrapInput: options.wrapInput ?? true,
+            };
+            this.agents = agents;
+        }
+        else {
+            this.options = { wrapInput: true };
+            this.agents = args;
+        }
+    }
+    isAgent(value) {
+        // Check for duck-typing: an agent has an execute method and is not a plain options object
+        return (typeof value === "object" &&
+            value !== null &&
+            "execute" in value &&
+            typeof value.execute === "function");
+    }
+    /**
+     * Executes agents in sequence.
+     * @param input - The initial input string
+     * @returns The final output from the last agent in the sequence
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "sequential", input);
+        if (this.agents.length === 0) {
+            if (execId)
+                collector?.endExecution(execId, true, input);
+            return input;
+        }
+        let result = input;
+        const originalInput = input;
+        try {
+            for (let i = 0; i < this.agents.length; i++) {
+                const agent = this.agents[i];
+                const agentName = agent.getName?.() ?? `Agent ${i + 1}`;
+                const agentExecId = collector?.startExecution(agentName, "agent", result);
+                const agentInput = this.options.wrapInput
+                    ? JSON.stringify({
+                        originalQuestion: originalInput,
+                        resultFromPreviousAgent: result,
+                    })
+                    : result;
+                try {
+                    result = (await agent.execute(agentInput));
+                    // Try to get token usage from agent if available
+                    const tokenUsage = this.extractTokenUsage(agent);
+                    if (agentExecId) {
+                        collector?.endExecution(agentExecId, true, result, tokenUsage);
+                    }
+                }
+                catch (error) {
+                    if (agentExecId) {
+                        collector?.endExecution(agentExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+                    }
+                    throw error;
+                }
+            }
+            if (execId)
+                collector?.endExecution(execId, true, result);
+            return result;
+        }
+        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) {
+        // Check if agent has lastTokenUsage property
+        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 in the sequence.
+     */
+    get length() {
+        return this.agents.length;
+    }
+}
+exports.SequentialExecutor = SequentialExecutor;
+//# sourceMappingURL=SequentialExecutor.js.map

package/dist/graph/VotingSystem.d.ts

@@ -0,0 +1,54 @@
+import { BaseAgent } from "../agents/BaseAgent";
+import { BaseExecutor } from "./BaseExecutor";
+/**
+ * Input format for the VotingSystem.
+ */
+export interface VotingInput {
+    /** The original question or input that was posed */
+    originalInput: string;
+    /** Array of solutions/answers from different sources to vote on */
+    solutions: string[];
+}
+/**
+ * Options for configuring the voting system.
+ */
+export interface VotingSystemOptions {
+    /**
+     * Custom prompt template for the judge.
+     * Use {originalQuestion} and {expertAnswers} as placeholders.
+     */
+    promptTemplate?: string;
+}
+/**
+ * A voting system that uses a judge agent to select or synthesize
+ * the best answer from multiple solutions.
+ *
+ * Typically used after a ParallelExecutor to evaluate multiple expert opinions.
+ *
+ * @example
+ * ```typescript
+ * const voting = new VotingSystem(judgeAgent);
+ * const result = await voting.execute({
+ *   originalInput: "What is the best approach?",
+ *   solutions: [expertA_answer, expertB_answer, expertC_answer]
+ * });
+ * ```
+ */
+export declare class VotingSystem extends BaseExecutor<VotingInput, string> {
+    private judge;
+    private promptTemplate;
+    constructor(judge: BaseAgent, options?: VotingSystemOptions);
+    /**
+     * Evaluates the solutions and returns the judge's verdict.
+     * @param input - Object containing originalInput and solutions array
+     * @returns The judge's selected or synthesized answer
+     * @throws Error if input is a string (must be VotingInput object)
+     */
+    execute(input: VotingInput | string): Promise<string>;
+    /**
+     * Attempt to extract token usage from an agent.
+     * Converts from agent's snake_case format to metrics camelCase format.
+     */
+    private extractTokenUsage;
+}
+//# sourceMappingURL=VotingSystem.d.ts.map