modular-agent-examples 0.0.1

package/graph/metrics-example.ts

@@ -0,0 +1,238 @@
+/**
+ * Metrics and Observability Example
+ *
+ * Demonstrates how to track timing, token usage, and pipeline structure
+ * for analysis and visualization.
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import {
+  AgentGraph,
+  createMetricsCollector,
+  VotingInput,
+  GraphNode,
+} from "../../lib/graph/AgentGraph";
+
+const apiKey = process.env.ANTHROPIC_API_KEY as string;
+
+// Create some agents for demonstration
+const researchAgent = new ClaudeAgent({
+  id: "researcher",
+  name: "Researcher",
+  description:
+    "Research the given topic briefly. Keep response under 50 words.",
+  apiKey,
+  maxTokens: 128,
+});
+
+const optimistAgent = new ClaudeAgent({
+  id: "optimist",
+  name: "Optimist",
+  description: "Give a brief optimistic perspective. Under 30 words.",
+  apiKey,
+  maxTokens: 64,
+});
+
+const pessimistAgent = new ClaudeAgent({
+  id: "pessimist",
+  name: "Pessimist",
+  description: "Give a brief pessimistic perspective. Under 30 words.",
+  apiKey,
+  maxTokens: 64,
+});
+
+const judgeAgent = new ClaudeAgent({
+  id: "judge",
+  name: "Judge",
+  description:
+    "Pick the better perspective. Say 'Optimist' or 'Pessimist' only.",
+  apiKey,
+  maxTokens: 16,
+});
+
+async function runMetricsExample() {
+  console.log("╔══════════════════════════════════════════════╗");
+  console.log("║     Graph Metrics & Observability Demo       ║");
+  console.log("╚══════════════════════════════════════════════╝\n");
+
+  // Create a metrics collector
+  const metrics = createMetricsCollector();
+
+  // Build a pipeline with metrics enabled
+  const pipeline = AgentGraph.pipeline<string, string>(
+    // Stage 1: Research
+    AgentGraph.sequential({ wrapInput: false }, researchAgent),
+
+    // Stage 2: Parallel perspectives
+    AgentGraph.parallel({ wrapInput: false }, optimistAgent, pessimistAgent),
+
+    // Stage 3: Transform for voting
+    {
+      name: "TransformForVoting",
+      execute: async (results: string[]) => ({
+        originalInput: "Which perspective is better?",
+        solutions: results,
+      }),
+    } as GraphNode<string[], VotingInput>,
+
+    // Stage 4: Judge votes
+    AgentGraph.votingSystem(judgeAgent)
+  ).withMetrics(metrics);
+
+  console.log("Running pipeline with metrics collection...\n");
+  const startTime = Date.now();
+
+  try {
+    const result = await pipeline.execute("The future of renewable energy");
+    const totalTime = Date.now() - startTime;
+
+    console.log("\n════════════════════════════════════════════════");
+    console.log("RESULT:", result);
+    console.log("════════════════════════════════════════════════\n");
+
+    // Display metrics
+    console.log("📊 EXECUTION METRICS\n");
+    console.log(metrics.toTextVisualization());
+
+    // Get aggregate metrics
+    const aggregate = metrics.getAggregateMetrics();
+
+    console.log("\n────────────────────────────────────────────────");
+    console.log("📈 AGGREGATE STATISTICS\n");
+    console.log(`Total Duration:    ${aggregate.totalDurationMs}ms`);
+    console.log(`Nodes Executed:    ${aggregate.nodeCount}`);
+    console.log(`Successful:        ${aggregate.successCount}`);
+    console.log(`Failed:            ${aggregate.failureCount}`);
+    console.log(`Total Tokens:      ${aggregate.totalTokens.totalTokens}`);
+    console.log(`  - Input Tokens:  ${aggregate.totalTokens.inputTokens}`);
+    console.log(`  - Output Tokens: ${aggregate.totalTokens.outputTokens}`);
+
+    // Display pipeline structure
+    console.log("\n────────────────────────────────────────────────");
+    console.log("🏗️  PIPELINE STRUCTURE\n");
+    displayStructure(aggregate.structure);
+
+    // Show JSON output (for external tools)
+    console.log("\n────────────────────────────────────────────────");
+    console.log("📄 JSON OUTPUT (for visualization tools)\n");
+    console.log(metrics.toJSON());
+  } catch (error) {
+    console.error("Pipeline failed:", error);
+
+    // Even on failure, we can see what executed
+    console.log("\n📊 PARTIAL EXECUTION METRICS\n");
+    console.log(metrics.toTextVisualization());
+  }
+}
+
+/**
+ * Display pipeline structure as ASCII tree
+ */
+function displayStructure(
+  structure: { type: string; name: string; children?: any[] },
+  indent = 0
+): void {
+  const prefix = indent === 0 ? "" : "  ".repeat(indent - 1) + "├─ ";
+  console.log(`${prefix}[${structure.type}] ${structure.name}`);
+
+  if (structure.children) {
+    for (const child of structure.children) {
+      displayStructure(child, indent + 1);
+    }
+  }
+}
+
+/**
+ * Example: Comparing execution times
+ */
+async function runTimingComparison() {
+  console.log("\n╔══════════════════════════════════════════════╗");
+  console.log("║         Timing Comparison Example            ║");
+  console.log("╚══════════════════════════════════════════════╝\n");
+
+  const quickAgent = new ClaudeAgent({
+    id: "quick",
+    name: "Quick Agent",
+    description: "Say 'Hello' only.",
+    apiKey,
+    maxTokens: 8,
+  });
+
+  // Sequential execution
+  const seqMetrics = createMetricsCollector();
+  const sequential = AgentGraph.sequential(
+    { wrapInput: false },
+    quickAgent,
+    quickAgent,
+    quickAgent
+  ).withMetrics(seqMetrics);
+
+  console.log("Running 3 agents SEQUENTIALLY...");
+  await sequential.execute("test");
+  const seqAggregate = seqMetrics.getAggregateMetrics();
+  console.log(`Sequential time: ${seqAggregate.totalDurationMs}ms\n`);
+
+  // Parallel execution
+  const parMetrics = createMetricsCollector();
+  const parallel = AgentGraph.parallel(
+    { wrapInput: false },
+    quickAgent,
+    quickAgent,
+    quickAgent
+  ).withMetrics(parMetrics);
+
+  console.log("Running 3 agents in PARALLEL...");
+  await parallel.execute("test");
+  const parAggregate = parMetrics.getAggregateMetrics();
+  console.log(`Parallel time: ${parAggregate.totalDurationMs}ms\n`);
+
+  const speedup = seqAggregate.totalDurationMs / parAggregate.totalDurationMs;
+  console.log(`Speedup: ${speedup.toFixed(2)}x faster with parallel execution`);
+}
+
+/**
+ * Example: Error tracking
+ */
+async function runErrorTrackingExample() {
+  console.log("\n╔══════════════════════════════════════════════╗");
+  console.log("║           Error Tracking Example             ║");
+  console.log("╚══════════════════════════════════════════════╝\n");
+
+  const failingNode: GraphNode<string, string> = {
+    name: "FailingNode",
+    execute: async () => {
+      throw new Error("Simulated failure!");
+    },
+  };
+
+  const metrics = createMetricsCollector();
+  const pipeline = AgentGraph.pipeline(
+    AgentGraph.sequential({ wrapInput: false }, researchAgent),
+    failingNode
+  ).withMetrics(metrics);
+
+  console.log("Running pipeline with a failing stage...\n");
+
+  try {
+    await pipeline.execute("test topic");
+  } catch (error) {
+    console.log("Pipeline failed as expected.\n");
+  }
+
+  console.log("📊 METRICS (showing failure):\n");
+  console.log(metrics.toTextVisualization());
+
+  const aggregate = metrics.getAggregateMetrics();
+  console.log(
+    `\nSuccess rate: ${aggregate.successCount}/${aggregate.nodeCount}`
+  );
+}
+
+// Run all examples
+async function main() {
+  await runMetricsExample();
+  await runTimingComparison();
+  await runErrorTrackingExample();
+}
+
+main().catch(console.error);

package/graph/parallel-example.ts

@@ -0,0 +1,167 @@
+/**
+ * Parallel Executor Example
+ *
+ * Demonstrates running multiple agents concurrently on the same input.
+ * Each agent provides their unique perspective simultaneously.
+ *
+ * Use case: Getting multiple expert opinions on a topic
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph } from "../../lib/graph/AgentGraph";
+import { AgentEvent } from "../../lib/agents/AgentEvent";
+
+const apiKey = process.env.ANTHROPIC_API_KEY as string;
+console.log("apiKey", apiKey);
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+// Expert 1: Technical perspective
+const technicalExpert = new ClaudeAgent({
+  id: "tech-expert",
+  name: "Technical Expert",
+  description: `You are a technical expert specializing in technology and engineering.
+Analyze topics from a technical feasibility and implementation perspective.
+Focus on: technical challenges, solutions, innovations, and practical considerations.
+Keep your analysis concise (under 150 words).`,
+  apiKey,
+  maxTokens: 512,
+});
+
+// Expert 2: Economic perspective
+const economicExpert = new ClaudeAgent({
+  id: "econ-expert",
+  name: "Economic Expert",
+  description: `You are an economic expert specializing in markets and business.
+Analyze topics from an economic and business perspective.
+Focus on: costs, benefits, market impact, investment potential, and economic trends.
+Keep your analysis concise (under 150 words).`,
+  apiKey,
+  maxTokens: 512,
+});
+
+// Expert 3: Social perspective
+const socialExpert = new ClaudeAgent({
+  id: "social-expert",
+  name: "Social Expert",
+  description: `You are a social scientist specializing in societal impact.
+Analyze topics from a social and human perspective.
+Focus on: social implications, ethical considerations, human behavior, and cultural impact.
+Keep your analysis concise (under 150 words).`,
+  apiKey,
+  maxTokens: 512,
+});
+
+// Expert 4: Environmental perspective
+const environmentalExpert = new ClaudeAgent({
+  id: "env-expert",
+  name: "Environmental Expert",
+  description: `You are an environmental scientist.
+Analyze topics from an environmental and sustainability perspective.
+Focus on: environmental impact, sustainability, resource usage, and ecological considerations.
+Keep your analysis concise (under 150 words).`,
+  apiKey,
+  maxTokens: 512,
+});
+
+async function runParallelExample() {
+  console.log("=== Parallel Executor Example ===\n");
+  console.log("Running 4 experts in parallel to analyze a topic\n");
+
+  // Create parallel executor with all experts
+  const expertPanel = AgentGraph.parallel(
+    { wrapInput: false }, // Pass raw input to each expert
+    technicalExpert,
+    economicExpert,
+    socialExpert,
+    environmentalExpert
+  );
+
+  // Track timing
+  const experts = [
+    technicalExpert,
+    economicExpert,
+    socialExpert,
+    environmentalExpert,
+  ];
+  const startTimes: Record<string, number> = {};
+
+  experts.forEach((expert) => {
+    expert.addListener(AgentEvent.BEFORE_EXECUTE, () => {
+      startTimes[expert.getId()] = Date.now();
+      console.log(`>>> ${expert.getName()} starting analysis...`);
+    });
+    expert.addListener(AgentEvent.DONE, () => {
+      const elapsed = Date.now() - startTimes[expert.getId()];
+      console.log(`<<< ${expert.getName()} completed (${elapsed}ms)`);
+    });
+  });
+
+  const topic = "The rise of electric vehicles and autonomous driving";
+  console.log(`Topic: "${topic}"\n`);
+
+  const overallStart = Date.now();
+
+  try {
+    const results = await expertPanel.execute(topic);
+    const totalTime = Date.now() - overallStart;
+
+    console.log("\n=== Expert Opinions ===\n");
+
+    const expertNames = ["Technical", "Economic", "Social", "Environmental"];
+    results.forEach((result, index) => {
+      console.log(`--- ${expertNames[index]} Perspective ---`);
+      console.log(result);
+      console.log();
+    });
+
+    console.log(`Total time: ${totalTime}ms (parallel execution)`);
+    console.log("Note: Sequential execution would take ~4x longer\n");
+  } catch (error) {
+    console.error("Expert panel failed:", error);
+  }
+}
+
+// Demonstrate isolated vs shared execution
+async function runIsolationExample() {
+  console.log("\n=== Isolation Modes ===\n");
+
+  const analyst1 = new ClaudeAgent({
+    id: "analyst-1",
+    name: "Analyst 1",
+    description: `Provide a brief one-sentence analysis of the topic.`,
+    apiKey,
+    maxTokens: 100,
+  });
+
+  const analyst2 = new ClaudeAgent({
+    id: "analyst-2",
+    name: "Analyst 2",
+    description: `Provide a brief one-sentence analysis of the topic.`,
+    apiKey,
+    maxTokens: 100,
+  });
+
+  // Isolated execution - each agent works independently
+  const isolatedPanel = AgentGraph.parallel(
+    { isolatedExecution: true, wrapInput: false },
+    analyst1,
+    analyst2
+  );
+
+  console.log("Running with isolated execution...");
+  const results = await isolatedPanel.execute("Climate change");
+
+  console.log("\nAnalyst 1:", results[0]);
+  console.log("Analyst 2:", results[1]);
+}
+
+// Run examples
+async function main() {
+  await runParallelExample();
+  await runIsolationExample();
+}
+
+main().catch(console.error);

package/graph/pipeline-example.ts

@@ -0,0 +1,225 @@
+/**
+ * Pipeline Example
+ *
+ * Demonstrates building complex multi-stage workflows by composing
+ * different executor types together.
+ *
+ * Use case: Complete research workflow with parallel experts and voting
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph, GraphNode, VotingInput } from "../../lib/graph/AgentGraph";
+import { AgentEvent } from "../../lib/agents/AgentEvent";
+
+const apiKey = process.env.ANTHROPIC_API_KEY as string;
+
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+// Stage 1: Research Agent
+const researchAgent = new ClaudeAgent({
+  id: "researcher",
+  name: "Researcher",
+  description: `You are a research assistant. Given a topic, provide a clear, factual overview.
+Focus on the most important and interesting aspects.
+Keep your response under 200 words.`,
+  apiKey,
+  maxTokens: 512,
+});
+
+// Stage 2: Parallel Experts
+const optimistExpert = new ClaudeAgent({
+  id: "optimist",
+  name: "Optimist",
+  description: `You analyze research findings with an optimistic lens.
+Highlight opportunities, positive developments, and potential benefits.
+Keep your analysis under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+const pessimistExpert = new ClaudeAgent({
+  id: "pessimist",
+  name: "Pessimist",
+  description: `You analyze research findings with a critical lens.
+Highlight risks, challenges, and potential problems.
+Keep your analysis under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+const realistExpert = new ClaudeAgent({
+  id: "realist",
+  name: "Realist",
+  description: `You analyze research findings with a balanced, realistic lens.
+Present both opportunities and challenges objectively.
+Keep your analysis under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+// Stage 3: Judge
+const judgeAgent = new ClaudeAgent({
+  id: "judge",
+  name: "Judge",
+  description: `You synthesize multiple expert perspectives into a final, balanced conclusion.
+Combine the best insights from each perspective.
+Provide actionable takeaways.
+Keep your synthesis under 150 words.`,
+  apiKey,
+  maxTokens: 384,
+});
+
+// Custom transformer node to prepare data for voting
+const prepareForVoting: GraphNode<string[], VotingInput> = {
+  execute: async (expertResults: string[]) => {
+    // Store the original question for later (in real use, you'd pass this through context)
+    return {
+      originalInput:
+        "Synthesize these expert analyses into a balanced conclusion",
+      solutions: expertResults,
+    };
+  },
+};
+
+async function runFullPipelineExample() {
+  console.log("=== Full Pipeline Example ===\n");
+  console.log(
+    "Pipeline: Research -> Parallel Experts -> Transform -> Voting\n"
+  );
+
+  // Build the complete pipeline
+  const analysisPipeline = AgentGraph.pipeline(
+    // Stage 1: Initial research (sequential with single agent)
+    AgentGraph.sequential({ wrapInput: false }, researchAgent),
+
+    // Stage 2: Parallel expert analysis
+    AgentGraph.parallel(
+      { wrapInput: false },
+      optimistExpert,
+      pessimistExpert,
+      realistExpert
+    ),
+
+    // Stage 3: Transform results for voting
+    prepareForVoting,
+
+    // Stage 4: Judge synthesizes final answer
+    AgentGraph.votingSystem(judgeAgent)
+  );
+
+  // Add logging
+  const allAgents = [
+    researchAgent,
+    optimistExpert,
+    pessimistExpert,
+    realistExpert,
+    judgeAgent,
+  ];
+  allAgents.forEach((agent) => {
+    agent.addListener(AgentEvent.BEFORE_EXECUTE, () => {
+      console.log(`  > ${agent.getName()} working...`);
+    });
+  });
+
+  const topic = "The future of remote work";
+  console.log(`Topic: "${topic}"\n`);
+  console.log("Running pipeline...\n");
+
+  const startTime = Date.now();
+
+  try {
+    const result = await analysisPipeline.execute(topic);
+    const elapsed = Date.now() - startTime;
+
+    console.log("\n=== Final Synthesized Analysis ===\n");
+    console.log(result);
+    console.log(`\nCompleted in ${elapsed}ms`);
+  } catch (error) {
+    console.error("Pipeline failed:", error);
+  }
+}
+
+// Demonstrate pipeline with custom intermediate stages
+async function runCustomStagesPipeline() {
+  console.log("\n=== Pipeline with Custom Stages ===\n");
+
+  const writer = new ClaudeAgent({
+    id: "writer",
+    name: "Writer",
+    description: `Write a short paragraph about the given topic. Keep it under 50 words.`,
+    apiKey,
+    maxTokens: 128,
+  });
+
+  // Build pipeline with custom transformation stages
+  const textPipeline = AgentGraph.pipeline<string, string>(
+    // Stage 1: Write initial content
+    AgentGraph.sequential({ wrapInput: false }, writer),
+
+    // Stage 2: Custom transformation - convert to uppercase
+    {
+      execute: async (text: string) => {
+        console.log("  > Transforming to uppercase...");
+        return text.toUpperCase();
+      },
+    },
+
+    // Stage 3: Custom transformation - add decoration
+    {
+      execute: async (text: string) => {
+        console.log("  > Adding decoration...");
+        return `✨ ${text} ✨`;
+      },
+    }
+  );
+
+  const result = await textPipeline.execute("The beauty of nature");
+  console.log("\nResult:");
+  console.log(result);
+}
+
+// Demonstrate building pipeline incrementally
+async function runIncrementalPipeline() {
+  console.log("\n=== Incremental Pipeline Building ===\n");
+
+  // Build pipeline with explicit stages using AgentGraph.pipeline
+  // Each stage transforms the data: number -> number -> number -> string
+  const pipeline = AgentGraph.pipeline<number, string>(
+    {
+      execute: async (n: number) => {
+        console.log(`  > Doubling ${n}...`);
+        return n * 2;
+      },
+    },
+    {
+      execute: async (n: number) => {
+        console.log(`  > Adding 10 to ${n}...`);
+        return n + 10;
+      },
+    },
+    {
+      execute: async (n: number) => {
+        console.log(`  > Converting ${n} to string...`);
+        return `The result is: ${n}`;
+      },
+    }
+  );
+
+  console.log("Pipeline stages:", pipeline.length);
+  console.log("Input: 5\n");
+
+  const result = await pipeline.execute(5);
+  console.log("\nOutput:", result);
+}
+
+// Run all examples
+async function main() {
+  await runFullPipelineExample();
+  await runCustomStagesPipeline();
+  await runIncrementalPipeline();
+}
+
+main().catch(console.error);