modular-agent-examples 0.0.1

package/graph/data-pipeline/index.ts

@@ -0,0 +1,282 @@
+/**
+ * Data Pipeline Example
+ *
+ * Demonstrates the factory pattern for creating data-fetching pipelines.
+ *
+ * Key concepts:
+ * - Factories capture context (user, config) at creation time
+ * - Pipeline data flow stays simple (string -> string)
+ * - Security/permissions are handled at the factory level
+ * - Easy to compose different fetchers for different use cases
+ *
+ * Run with: npx ts-node examples/graph/data-pipeline/index.ts
+ */
+
+import "dotenv/config";
+import {
+  AgentGraph,
+  GraphNode,
+  createMetricsCollector,
+} from "../../../lib/graph/AgentGraph";
+import {
+  createDatabaseFetcher,
+  createWebFetcher,
+  createVectorDbFetcher,
+  UserContext,
+} from "./fetchers";
+import { createPipelineAgents } from "./agents";
+
+const apiKey = process.env.ANTHROPIC_API_KEY;
+
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+// ============================================================================
+// Helper: Combine Multiple Data Sources
+// ============================================================================
+
+/**
+ * Creates a node that combines results from multiple fetchers.
+ * Each fetcher runs in parallel, results are concatenated.
+ */
+function createDataCombiner(
+  ...fetchers: GraphNode<string, string>[]
+): GraphNode<string, string> {
+  return {
+    name: "DataCombiner",
+    nodeType: "custom",
+    execute: async (topic: string) => {
+      console.log(`\n  [COMBINE] Fetching from ${fetchers.length} sources in parallel...`);
+
+      // Run all fetchers in parallel
+      const results = await Promise.all(
+        fetchers.map((f) => f.execute(topic))
+      );
+
+      // Combine results with clear separation
+      return results.join("\n\n");
+    },
+  };
+}
+
+// ============================================================================
+// Example 1: Basic Data Pipeline with Permissions
+// ============================================================================
+
+async function runBasicPipeline() {
+  console.log("╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Example 1: Basic Data Pipeline with Permissions             ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝\n");
+
+  // Simulate a user with limited permissions
+  const regularUser: UserContext = {
+    userId: "user-123",
+    tenantId: "acme-corp",
+    permissions: ["read:tech", "read:research"],
+  };
+
+  // Create fetchers with user context baked in
+  const dbFetcher = createDatabaseFetcher(regularUser);
+  const webFetcher = createWebFetcher();
+
+  // Create agents
+  const { summarizerAgent } = createPipelineAgents(apiKey);
+
+  // Build pipeline: Combine sources -> Summarize
+  const pipeline = AgentGraph.pipeline<string, string>(
+    createDataCombiner(dbFetcher, webFetcher),
+    AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+  );
+
+  console.log("User:", regularUser.userId);
+  console.log("Permissions:", regularUser.permissions.join(", "));
+  console.log("\n--- Running pipeline for 'quantum computing' ---\n");
+
+  const result = await pipeline.execute("quantum computing");
+
+  console.log("\n=== Result ===\n");
+  console.log(result);
+}
+
+// ============================================================================
+// Example 2: Access Denied Scenario
+// ============================================================================
+
+async function runAccessDeniedExample() {
+  console.log("\n╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Example 2: Access Denied Scenario                           ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝\n");
+
+  // User without finance permissions
+  const limitedUser: UserContext = {
+    userId: "intern-456",
+    tenantId: "acme-corp",
+    permissions: ["read:research"], // No finance access
+  };
+
+  const dbFetcher = createDatabaseFetcher(limitedUser);
+  const { summarizerAgent } = createPipelineAgents(apiKey);
+
+  const pipeline = AgentGraph.pipeline<string, string>(
+    dbFetcher,
+    AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+  );
+
+  console.log("User:", limitedUser.userId);
+  console.log("Permissions:", limitedUser.permissions.join(", "));
+  console.log("\n--- Attempting to access 'financials' ---\n");
+
+  const result = await pipeline.execute("financials");
+
+  console.log("\n=== Result ===\n");
+  console.log(result);
+}
+
+// ============================================================================
+// Example 3: Multi-Source Research Pipeline
+// ============================================================================
+
+async function runMultiSourcePipeline() {
+  console.log("\n╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Example 3: Multi-Source Research Pipeline                   ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝\n");
+
+  // Admin user with full access
+  const adminUser: UserContext = {
+    userId: "admin-001",
+    tenantId: "acme-corp",
+    permissions: ["read:tech", "read:research", "read:medical", "read:finance"],
+  };
+
+  // Create multiple fetchers
+  const dbFetcher = createDatabaseFetcher(adminUser);
+  const webFetcher = createWebFetcher();
+  const vectorFetcher = createVectorDbFetcher(adminUser, {
+    collection: "research-papers",
+    topK: 3
+  });
+
+  // Create agents
+  const { analyzerAgent, summarizerAgent } = createPipelineAgents(apiKey);
+
+  // Create metrics collector
+  const metrics = createMetricsCollector();
+
+  // Build comprehensive research pipeline
+  const researchPipeline = AgentGraph.pipeline<string, string>(
+    // Stage 1: Fetch from all sources in parallel
+    createDataCombiner(dbFetcher, webFetcher, vectorFetcher),
+
+    // Stage 2: Deep analysis
+    AgentGraph.sequential({ wrapInput: false }, analyzerAgent),
+
+    // Stage 3: Executive summary
+    AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+  ).withMetrics(metrics);
+
+  console.log("User:", adminUser.userId);
+  console.log("Data sources: Database, Web, VectorDB");
+  console.log("\n--- Running comprehensive research on 'penicillin' ---\n");
+
+  const result = await researchPipeline.execute("penicillin");
+
+  console.log("\n=== Executive Summary ===\n");
+  console.log(result);
+
+  // Show metrics
+  console.log("\n=== Pipeline Metrics ===\n");
+  console.log(metrics.toTextVisualization());
+
+  const aggregate = metrics.getAggregateMetrics();
+  console.log(`\nTotal duration: ${aggregate.totalDurationMs}ms`);
+  console.log(`Total tokens: ${aggregate.totalTokens.totalTokens}`);
+}
+
+// ============================================================================
+// Example 4: Dynamic Pipeline Based on User Role
+// ============================================================================
+
+async function runRoleBasedPipeline() {
+  console.log("\n╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Example 4: Dynamic Pipeline Based on User Role              ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝\n");
+
+  /**
+   * Factory that creates different pipelines based on user role.
+   * Demonstrates how to compose pipelines dynamically.
+   */
+  function createPipelineForUser(
+    user: UserContext & { role: "basic" | "researcher" | "admin" }
+  ): GraphNode<string, string> {
+    const { summarizerAgent, analyzerAgent } = createPipelineAgents(apiKey);
+
+    switch (user.role) {
+      case "basic":
+        // Basic users only get web data
+        console.log(`Creating basic pipeline for ${user.userId}`);
+        return AgentGraph.pipeline(
+          createWebFetcher(),
+          AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+        );
+
+      case "researcher":
+        // Researchers get DB + web
+        console.log(`Creating researcher pipeline for ${user.userId}`);
+        return AgentGraph.pipeline(
+          createDataCombiner(
+            createDatabaseFetcher(user),
+            createWebFetcher()
+          ),
+          AgentGraph.sequential({ wrapInput: false }, analyzerAgent),
+          AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+        );
+
+      case "admin":
+        // Admins get everything
+        console.log(`Creating admin pipeline for ${user.userId}`);
+        return AgentGraph.pipeline(
+          createDataCombiner(
+            createDatabaseFetcher(user),
+            createWebFetcher(),
+            createVectorDbFetcher(user)
+          ),
+          AgentGraph.sequential({ wrapInput: false }, analyzerAgent),
+          AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+        );
+    }
+  }
+
+  // Test with different roles
+  const basicUser = {
+    userId: "basic-user",
+    tenantId: "acme-corp",
+    permissions: [],
+    role: "basic" as const,
+  };
+
+  const pipeline = createPipelineForUser(basicUser);
+
+  console.log("\n--- Running with basic user role ---\n");
+
+  const result = await pipeline.execute("climate change");
+
+  console.log("\n=== Result ===\n");
+  console.log(result);
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  await runBasicPipeline();
+  await runAccessDeniedExample();
+  await runMultiSourcePipeline();
+  await runRoleBasedPipeline();
+
+  console.log("\n✓ All examples completed");
+}
+
+main().catch(console.error);

package/graph/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Graph Examples Index
+ *
+ * Run individual examples:
+ *   npx ts-node examples/graph/sequential-example.ts
+ *   npx ts-node examples/graph/parallel-example.ts
+ *   npx ts-node examples/graph/voting-example.ts
+ *   npx ts-node examples/graph/pipeline-example.ts
+ *   npx ts-node examples/graph/map-example.ts
+ *   npx ts-node examples/graph/router-example.ts
+ *
+ * Or run this file for a quick demo:
+ *   npx ts-node examples/graph/index.ts
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph, VotingInput, GraphNode } from "../../lib/graph/AgentGraph";
+
+const apiKey = process.env.ANTHROPIC_API_KEY;
+
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+/**
+ * Quick demo showcasing all graph executor types
+ */
+async function quickDemo() {
+  console.log("╔══════════════════════════════════════════╗");
+  console.log("║     Agention Graph System Quick Demo     ║");
+  console.log("╚══════════════════════════════════════════╝\n");
+
+  // Create some simple agents for demonstration
+  const uppercaseAgent = new ClaudeAgent({
+    id: "uppercase",
+    name: "Uppercase Agent",
+    description:
+      "Convert the input to uppercase. Output only the uppercase text.",
+    apiKey,
+    maxTokens: 100,
+  });
+
+  const excitedAgent = new ClaudeAgent({
+    id: "excited",
+    name: "Excited Agent",
+    description:
+      "Add excitement to the text by adding exclamation marks and enthusiastic words. Keep it short.",
+    apiKey,
+    maxTokens: 100,
+  });
+
+  const calmAgent = new ClaudeAgent({
+    id: "calm",
+    name: "Calm Agent",
+    description:
+      "Make the text calmer and more relaxed. Use peaceful language. Keep it short.",
+    apiKey,
+    maxTokens: 100,
+  });
+
+  const judgeAgent = new ClaudeAgent({
+    id: "judge",
+    name: "Judge Agent",
+    description:
+      "You receive two versions of text. Pick the better one. Output only 'Version 1' or 'Version 2'.",
+    apiKey,
+    maxTokens: 20,
+  });
+
+  // 1. Sequential Example
+  console.log("1. SEQUENTIAL EXECUTOR");
+  console.log("   Chain: Input -> Uppercase -> Excited\n");
+
+  const sequential = AgentGraph.sequential(
+    { wrapInput: false },
+    uppercaseAgent,
+    excitedAgent
+  );
+
+  const seqResult = await sequential.execute("hello world");
+  console.log(`   Input:  "hello world"`);
+  console.log(`   Output: "${seqResult}"\n`);
+
+  // 2. Parallel Example
+  console.log("2. PARALLEL EXECUTOR");
+  console.log("   Running Excited and Calm agents in parallel\n");
+
+  const parallel = AgentGraph.parallel(
+    { wrapInput: false },
+    excitedAgent,
+    calmAgent
+  );
+
+  const parResults = await parallel.execute("The sun is shining");
+  console.log(`   Input: "The sun is shining"`);
+  console.log(`   Excited: "${parResults[0]}"`);
+  console.log(`   Calm:    "${parResults[1]}"\n`);
+
+  // 3. Voting Example
+  console.log("3. VOTING SYSTEM");
+  console.log("   Judge picks between excited and calm versions\n");
+
+  const voting = AgentGraph.votingSystem(judgeAgent);
+  const votingInput: VotingInput = {
+    originalInput: "Pick the better version",
+    solutions: parResults,
+  };
+
+  const verdict = await voting.execute(votingInput);
+  console.log(`   Verdict: ${verdict}\n`);
+
+  // 4. Map Example
+  console.log("4. MAP EXECUTOR");
+  console.log("   Processing array of items in parallel\n");
+
+  const mapper = AgentGraph.map(
+    AgentGraph.sequential({ wrapInput: false }, uppercaseAgent)
+  );
+
+  const mapResults = await mapper.execute(["one", "two", "three"]);
+  console.log(`   Input:  ["one", "two", "three"]`);
+  console.log(`   Output: ${JSON.stringify(mapResults)}\n`);
+
+  // 5. Pipeline Example
+  console.log("5. PIPELINE");
+  console.log("   Complex workflow combining multiple executor types\n");
+
+  const pipeline = AgentGraph.pipeline<string, string>(
+    // Stage 1: Get two versions in parallel
+    AgentGraph.parallel({ wrapInput: false }, excitedAgent, calmAgent),
+
+    // Stage 2: Transform for voting
+    {
+      execute: async (results: string[]) => ({
+        originalInput: "Which version is better?",
+        solutions: results,
+      }),
+    } as GraphNode<string[], VotingInput>,
+
+    // Stage 3: Vote
+    voting
+  );
+
+  const pipelineResult = await pipeline.execute("Good morning");
+  console.log(`   Input:  "Good morning"`);
+  console.log(`   Output: "${pipelineResult}"`);
+
+  console.log("\n╔══════════════════════════════════════════╗");
+  console.log("║            Demo Complete!                ║");
+  console.log("╚══════════════════════════════════════════╝");
+}
+
+quickDemo().catch(console.error);

package/graph/map-example.ts

@@ -0,0 +1,227 @@
+/**
+ * Map Executor Example
+ *
+ * Demonstrates processing arrays of items in parallel using a processor agent.
+ *
+ * Use case: Batch processing documents, summarizing multiple articles, etc.
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph, GraphNode } from "../../lib/graph/AgentGraph";
+
+const apiKey = process.env.ANTHROPIC_API_KEY;
+
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+// Summarization agent for processing individual documents
+const summarizerAgent = new ClaudeAgent({
+  id: "summarizer",
+  name: "Summarizer",
+  description: `You are a summarization agent. Given a text, provide a one-sentence summary.
+Be concise and capture the main point. Output only the summary sentence.`,
+  apiKey,
+  maxTokens: 100,
+});
+
+// Sentiment analysis agent
+const sentimentAgent = new ClaudeAgent({
+  id: "sentiment",
+  name: "Sentiment Analyzer",
+  description: `Analyze the sentiment of the given text.
+Output exactly one word: POSITIVE, NEGATIVE, or NEUTRAL`,
+  apiKey,
+  maxTokens: 10,
+});
+
+// Translation agent
+const translatorAgent = new ClaudeAgent({
+  id: "translator",
+  name: "Translator",
+  description: `Translate the given text to Spanish. Output only the translation.`,
+  apiKey,
+  maxTokens: 200,
+});
+
+async function runBatchSummarization() {
+  console.log("=== Batch Summarization Example ===\n");
+
+  const documents = [
+    "Artificial intelligence is transforming healthcare by enabling faster diagnosis and personalized treatment plans. Machine learning algorithms can now detect diseases from medical images with accuracy matching or exceeding human experts.",
+    "Climate change is causing unprecedented shifts in global weather patterns. Rising temperatures are leading to more frequent extreme weather events, including hurricanes, droughts, and wildfires.",
+    "The global economy is increasingly driven by digital services and remote work. Companies are adapting to hybrid work models, reshaping urban centers and suburban communities alike.",
+    "Space exploration has entered a new era with private companies launching missions alongside government agencies. Reusable rockets have dramatically reduced the cost of reaching orbit.",
+  ];
+
+  console.log(`Processing ${documents.length} documents in parallel...\n`);
+
+  // Create map executor with the summarizer
+  const batchSummarizer = AgentGraph.map(
+    AgentGraph.sequential({ wrapInput: false }, summarizerAgent)
+  );
+
+  const startTime = Date.now();
+  const summaries = await batchSummarizer.execute(documents);
+  const elapsed = Date.now() - startTime;
+
+  console.log("Summaries:");
+  summaries.forEach((summary, index) => {
+    console.log(`${index + 1}. ${summary}`);
+  });
+
+  console.log(`\nProcessed ${documents.length} documents in ${elapsed}ms`);
+}
+
+async function runBatchSentimentAnalysis() {
+  console.log("\n=== Batch Sentiment Analysis Example ===\n");
+
+  const reviews = [
+    "This product exceeded all my expectations! Best purchase ever.",
+    "Terrible quality. Broke after one day. Complete waste of money.",
+    "It's okay. Does what it's supposed to do, nothing special.",
+    "Absolutely love it! Would recommend to everyone.",
+    "Not great, not terrible. Average product for average price.",
+  ];
+
+  console.log("Analyzing sentiment of customer reviews...\n");
+
+  const sentimentAnalyzer = AgentGraph.map(
+    AgentGraph.sequential({ wrapInput: false }, sentimentAgent)
+  );
+
+  const sentiments = await sentimentAnalyzer.execute(reviews);
+
+  console.log("Results:");
+  reviews.forEach((review, index) => {
+    console.log(`"${review.substring(0, 50)}..." -> ${sentiments[index]}`);
+  });
+
+  // Count sentiments
+  const counts = sentiments.reduce(
+    (acc, s) => {
+      const key = s.trim().toUpperCase();
+      acc[key] = (acc[key] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>
+  );
+
+  console.log("\nSummary:", counts);
+}
+
+async function runBatchTranslation() {
+  console.log("\n=== Batch Translation Example ===\n");
+
+  const phrases = [
+    "Hello, how are you?",
+    "The weather is beautiful today.",
+    "I love programming.",
+  ];
+
+  console.log("Translating phrases to Spanish...\n");
+
+  const translator = AgentGraph.map(
+    AgentGraph.sequential({ wrapInput: false }, translatorAgent)
+  );
+
+  const translations = await translator.execute(phrases);
+
+  console.log("Translations:");
+  phrases.forEach((phrase, index) => {
+    console.log(`EN: "${phrase}"`);
+    console.log(`ES: "${translations[index]}"`);
+    console.log();
+  });
+}
+
+// Custom processor example (non-agent)
+async function runCustomProcessor() {
+  console.log("=== Custom Processor Example ===\n");
+
+  // Custom processor that doesn't use an agent
+  const wordCounter: GraphNode<string, { text: string; wordCount: number }> = {
+    execute: async (text: string) => ({
+      text: text.substring(0, 30) + "...",
+      wordCount: text.split(/\s+/).length,
+    }),
+  };
+
+  const mapper = AgentGraph.map(wordCounter);
+
+  const texts = [
+    "This is a short sentence.",
+    "This is a much longer sentence with many more words in it.",
+    "One two three four five six seven eight nine ten eleven twelve.",
+  ];
+
+  const results = await mapper.execute(texts);
+
+  console.log("Word counts:");
+  results.forEach((result) => {
+    console.log(`"${result.text}" -> ${result.wordCount} words`);
+  });
+}
+
+// Pipeline with map example
+async function runPipelineWithMap() {
+  console.log("\n=== Pipeline with Map Example ===\n");
+
+  const qualityChecker = new ClaudeAgent({
+    id: "quality",
+    name: "Quality Checker",
+    description: `Given multiple summaries, identify which one is the best quality.
+Output only the number (1, 2, 3, etc.) of the best summary.`,
+    apiKey,
+    maxTokens: 10,
+  });
+
+  // Pipeline: Split -> Summarize Each -> Select Best
+  const pipeline = AgentGraph.pipeline(
+    // Split input into paragraphs
+    {
+      execute: async (text: string) => text.split("\n\n").filter((p) => p.trim()),
+    },
+
+    // Summarize each paragraph
+    AgentGraph.map(AgentGraph.sequential({ wrapInput: false }, summarizerAgent)),
+
+    // Combine summaries and select best
+    {
+      execute: async (summaries: string[]) => {
+        const numbered = summaries
+          .map((s, i) => `${i + 1}. ${s}`)
+          .join("\n");
+        return `Select the best summary:\n${numbered}`;
+      },
+    },
+
+    // Pick the best one
+    AgentGraph.sequential({ wrapInput: false }, qualityChecker)
+  );
+
+  const document = `
+The ocean covers over 70% of Earth's surface. It regulates climate, produces oxygen, and supports countless species. Marine ecosystems are vital for human survival.
+
+Technology has revolutionized communication. Smartphones connect billions of people worldwide. Social media platforms have transformed how we share information and interact.
+
+Education is the foundation of progress. Schools prepare young minds for the future. Lifelong learning enables adaptation in a rapidly changing world.
+  `.trim();
+
+  console.log("Document has 3 paragraphs. Finding best summary...\n");
+
+  const result = await pipeline.execute(document);
+  console.log("Best summary number:", result);
+}
+
+// Run all examples
+async function main() {
+  await runBatchSummarization();
+  await runBatchSentimentAnalysis();
+  await runBatchTranslation();
+  await runCustomProcessor();
+  await runPipelineWithMap();
+}
+
+main().catch(console.error);