modular-agent-examples 0.0.1

package/graph/context-example.ts

@@ -0,0 +1,209 @@
+/**
+ * Shared Context Example
+ *
+ * This example demonstrates how multiple agents can share data
+ * through a common context store using tools.
+ *
+ * Run with: npx ts-node examples/graph/context-example.ts
+ */
+
+import { AgentGraph } from "../../lib/graph/AgentGraph";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+
+async function main() {
+  // Create a shared context store with initial values
+  const contextStore = AgentGraph.createContextStore({
+    user_preferences: {
+      language: "English",
+      detail_level: "comprehensive",
+    },
+  });
+
+  // Create context tools that all agents will share
+  const contextTools = AgentGraph.createContextTools(contextStore);
+
+  // Agent 1: Researcher - gathers information and stores in context
+  const researcher = new ClaudeAgent({
+    id: "researcher",
+    name: "Research Agent",
+    description: `You are a research agent. Your job is to:
+1. Research the given topic
+2. Store your findings in context using context_set with key "research_findings"
+3. Store a list of key points using context_set with key "key_points"
+
+Use clear, descriptive keys for all context values.`,
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 2048,
+    tools: contextTools,
+  });
+
+  // Agent 2: Analyst - reads research and adds analysis
+  const analyst = new ClaudeAgent({
+    id: "analyst",
+    name: "Analysis Agent",
+    description: `You are an analysis agent. Your job is to:
+1. First, use list_context_keys to see what data is available
+2. Use context_get to retrieve "research_findings" and "key_points"
+3. Analyze the research and identify patterns, insights, and implications
+4. Store your analysis using context_set with key "analysis_results"
+
+Build upon the research already in context.`,
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 2048,
+    tools: contextTools,
+  });
+
+  // Agent 3: Writer - reads everything and creates final output
+  const writer = new ClaudeAgent({
+    id: "writer",
+    name: "Writer Agent",
+    description: `You are a writing agent. Your job is to:
+1. Use list_context_keys to see all available data
+2. Use context_get to retrieve research findings, key points, and analysis results
+3. Also check user_preferences for language and detail level preferences
+4. Write a well-structured report combining all the information
+5. Store the final report using context_set with key "final_report"
+
+Create a cohesive narrative from all the gathered information.`,
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 2048,
+    tools: contextTools,
+  });
+
+  const topic = "The impact of artificial intelligence on software development workflows";
+
+  console.log(`\n=== Shared Context Pipeline ===\n`);
+  console.log(`Topic: ${topic}\n`);
+  console.log("Initial context:", contextStore.toObject());
+
+  try {
+    // Step 1: Research
+    console.log("\n--- Step 1: Research ---");
+    await researcher.execute(
+      `Research the following topic and store your findings in context: "${topic}"`
+    );
+    console.log("Context keys after research:", contextStore.keys());
+
+    // Step 2: Analysis
+    console.log("\n--- Step 2: Analysis ---");
+    await analyst.execute(
+      "Retrieve the research from context, analyze it, and store your analysis."
+    );
+    console.log("Context keys after analysis:", contextStore.keys());
+
+    // Step 3: Writing
+    console.log("\n--- Step 3: Writing ---");
+    await writer.execute(
+      "Retrieve all information from context and write a comprehensive report."
+    );
+    console.log("Context keys after writing:", contextStore.keys());
+
+    // Display final results
+    console.log("\n=== Final Context Contents ===\n");
+
+    const allKeys = contextStore.keys();
+    for (const key of allKeys) {
+      const value = contextStore.get(key);
+      console.log(`\n[${key}]:`);
+      if (typeof value === "string") {
+        // Truncate long strings for display
+        console.log(value.length > 500 ? value.substring(0, 500) + "..." : value);
+      } else {
+        console.log(JSON.stringify(value, null, 2));
+      }
+    }
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+// Alternative: Using context in a pipeline
+async function pipelineExample() {
+  console.log("\n\n=== Context in Pipeline Example ===\n");
+
+  const contextStore = AgentGraph.createContextStore();
+  const contextTools = AgentGraph.createContextTools(contextStore);
+
+  // Simple agents that use context
+  const agent1 = new ClaudeAgent({
+    id: "agent1",
+    name: "Agent 1",
+    description:
+      "You receive input and store it in context with key 'stage1_output'. " +
+      "Also add your own observations with key 'stage1_observations'.",
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 1024,
+    tools: contextTools,
+  });
+
+  const agent2 = new ClaudeAgent({
+    id: "agent2",
+    name: "Agent 2",
+    description:
+      "First retrieve 'stage1_output' and 'stage1_observations' from context. " +
+      "Then process them and store result with key 'stage2_output'.",
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 1024,
+    tools: contextTools,
+  });
+
+  // Create a sequential pipeline
+  const pipeline = AgentGraph.sequential({ wrapInput: false }, agent1, agent2);
+
+  try {
+    const result = await pipeline.execute("Process this: Hello, World!");
+
+    console.log("Pipeline result:", result.substring(0, 200));
+    console.log("\nContext after pipeline:");
+    console.log(contextStore.toObject());
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+// Demonstration without API calls (using the store directly)
+function storeDemo() {
+  console.log("\n\n=== Context Store Demo (No API) ===\n");
+
+  const store = AgentGraph.createContextStore({
+    initial_value: "hello",
+  });
+
+  // Set various types of values
+  store.set("string_value", "This is a string");
+  store.set("number_value", 42);
+  store.set("object_value", { nested: { data: [1, 2, 3] } });
+  store.set("array_value", ["a", "b", "c"]);
+
+  console.log("All keys:", store.keys());
+  console.log("Has 'string_value':", store.has("string_value"));
+  console.log("Get 'object_value':", store.get("object_value"));
+  console.log("Size:", store.size);
+
+  // Delete a key
+  store.delete("number_value");
+  console.log("\nAfter delete 'number_value':");
+  console.log("All keys:", store.keys());
+
+  // Clone the store
+  const cloned = store.clone();
+  store.set("new_key", "only in original");
+  console.log("\nOriginal keys:", store.keys());
+  console.log("Cloned keys:", cloned.keys());
+
+  // Export to object
+  console.log("\nExport to object:", store.toObject());
+}
+
+// Run examples
+storeDemo();
+
+// Uncomment to run with actual API calls:
+// main()
+//   .then(() => pipelineExample())
+//   .catch(console.error);

package/graph/data-pipeline/agents.ts

@@ -0,0 +1,60 @@
+/**
+ * Agent Definitions for Data Pipeline Example
+ */
+
+import { ClaudeAgent } from "../../../lib/agents/anthropic/ClaudeAgent";
+
+/**
+ * Creates the agents used in the data pipeline.
+ * Requires ANTHROPIC_API_KEY environment variable.
+ */
+export function createPipelineAgents(apiKey: string) {
+  const analyzerAgent = new ClaudeAgent({
+    id: "analyzer",
+    name: "Data Analyzer",
+    description: `You are a data analysis agent. You receive information compiled from multiple sources
+(internal databases, external web sources, vector databases, etc.).
+
+Your job is to:
+1. Analyze and synthesize the information
+2. Note the source of each piece of information
+3. Identify any discrepancies between sources
+4. Highlight what's most important
+5. Flag any gaps in the data
+
+Be objective and factual. If sources conflict, present both perspectives.`,
+    apiKey,
+    maxTokens: 1024,
+  });
+
+  const summarizerAgent = new ClaudeAgent({
+    id: "summarizer",
+    name: "Executive Summarizer",
+    description: `You create concise executive summaries.
+
+Guidelines:
+- Maximum 100 words
+- Lead with the most important finding
+- Use bullet points for key facts
+- End with a clear recommendation or next step
+- Be direct and actionable`,
+    apiKey,
+    maxTokens: 256,
+  });
+
+  const researchAgent = new ClaudeAgent({
+    id: "researcher",
+    name: "Research Agent",
+    description: `You are a research agent that synthesizes information from multiple data sources.
+Given compiled research data, provide a comprehensive but focused analysis.
+Structure your output clearly with sections for: Key Facts, Analysis, and Conclusions.`,
+    apiKey,
+    maxTokens: 1024,
+  });
+
+  return {
+    analyzerAgent,
+    summarizerAgent,
+    researchAgent,
+  };
+}

package/graph/data-pipeline/fetchers.ts

@@ -0,0 +1,166 @@
+/**
+ * Data Fetcher Factories
+ *
+ * Demonstrates the factory pattern for creating data-fetching GraphNodes.
+ * Factories capture context (user permissions, tenant, config) at creation time,
+ * keeping the pipeline data flow simple (string -> string).
+ */
+
+import { GraphNode } from "../../../lib/graph/AgentGraph";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UserContext {
+  userId: string;
+  tenantId: string;
+  permissions: string[];
+}
+
+export interface DatabaseConfig {
+  connectionString?: string;
+  timeout?: number;
+}
+
+export interface ApiConfig {
+  baseUrl?: string;
+  apiKey?: string;
+  timeout?: number;
+}
+
+// ============================================================================
+// Database Fetcher Factory
+// ============================================================================
+
+/**
+ * Creates a database fetcher with user context baked in.
+ * The returned GraphNode only needs a topic string - auth is handled internally.
+ */
+export function createDatabaseFetcher(
+  userContext: UserContext,
+  config: DatabaseConfig = {}
+): GraphNode<string, string> {
+  // Simulated database with access control
+  const mockDatabase: Record<string, { data: string; requiredPermission: string }> = {
+    "penicillin": {
+      data: "Internal records: Alexander Fleming discovered penicillin in 1928 at St. Mary's Hospital London. Mass production began 1942. Patents filed 1940-1945. Estimated 200M lives saved.",
+      requiredPermission: "read:medical",
+    },
+    "quantum computing": {
+      data: "Internal records: Shor's algorithm (1994), Google quantum supremacy (2019), IBM 1000+ qubit processor (2023). Active research projects: QC-7, QC-12.",
+      requiredPermission: "read:tech",
+    },
+    "financials": {
+      data: "Q4 Revenue: $12.3M, YoY Growth: 23%, EBITDA margin: 18%. Confidential projections attached.",
+      requiredPermission: "read:finance",
+    },
+    "climate change": {
+      data: "Internal research: IPCC data analysis, Paris Agreement compliance tracking, carbon offset calculations for FY2023.",
+      requiredPermission: "read:research",
+    },
+  };
+
+  return {
+    name: `DatabaseFetcher[${userContext.userId}]`,
+    nodeType: "custom",
+    execute: async (topic: string) => {
+      console.log(`  [DB] User ${userContext.userId} querying: "${topic}"`);
+      console.log(`  [DB] Tenant: ${userContext.tenantId}, Permissions: ${userContext.permissions.join(", ")}`);
+
+      // Simulate database delay
+      await new Promise((resolve) => setTimeout(resolve, config.timeout ?? 100));
+
+      // Find matching records
+      const key = Object.keys(mockDatabase).find((k) =>
+        topic.toLowerCase().includes(k)
+      );
+
+      if (!key) {
+        console.log(`  [DB] No records found`);
+        return `[Database] No internal records found for "${topic}".`;
+      }
+
+      const record = mockDatabase[key];
+
+      // Check permissions
+      if (!userContext.permissions.includes(record.requiredPermission)) {
+        console.log(`  [DB] Access denied - requires ${record.requiredPermission}`);
+        return `[Database] Access denied. You don't have permission to access records about "${key}".`;
+      }
+
+      console.log(`  [DB] Access granted - returning data`);
+      return `[Database] ${record.data}`;
+    },
+  };
+}
+
+// ============================================================================
+// Web/API Fetcher Factory
+// ============================================================================
+
+/**
+ * Creates a web API fetcher with configuration baked in.
+ * In production, replace mock data with actual fetch() calls.
+ */
+export function createWebFetcher(
+  config: ApiConfig = {}
+): GraphNode<string, string> {
+  // Simulated web API responses
+  const mockWebData: Record<string, string> = {
+    "penicillin": "Wikipedia: Penicillin is a group of antibiotics derived from Penicillium fungi. Discovery credited to Alexander Fleming (1928). Nobel Prize in Physiology/Medicine (1945) shared with Florey and Chain.",
+    "quantum computing": "Latest news: Quantum computing market expected to reach $65B by 2030. Recent breakthroughs in error correction. IBM, Google, and IonQ leading commercial efforts.",
+    "climate change": "Current data: 2023 confirmed as hottest year on record. Global average temperature 1.45°C above pre-industrial levels. COP28 agreements under implementation.",
+  };
+
+  return {
+    name: "WebFetcher",
+    nodeType: "custom",
+    execute: async (topic: string) => {
+      console.log(`  [WEB] Fetching external data for: "${topic}"`);
+
+      // Simulate API call delay
+      await new Promise((resolve) => setTimeout(resolve, config.timeout ?? 150));
+
+      const key = Object.keys(mockWebData).find((k) =>
+        topic.toLowerCase().includes(k)
+      );
+
+      if (!key) {
+        console.log(`  [WEB] No relevant data found`);
+        return `[Web] No relevant external data found for "${topic}".`;
+      }
+
+      console.log(`  [WEB] Data retrieved`);
+      return `[Web] ${mockWebData[key]}`;
+    },
+  };
+}
+
+// ============================================================================
+// Vector Database Fetcher Factory (placeholder for future)
+// ============================================================================
+
+/**
+ * Creates a vector database fetcher for semantic search.
+ * Placeholder for future vector DB integration.
+ */
+export function createVectorDbFetcher(
+  userContext: UserContext,
+  config: { collection?: string; topK?: number } = {}
+): GraphNode<string, string> {
+  return {
+    name: `VectorDBFetcher[${config.collection ?? "default"}]`,
+    nodeType: "custom",
+    execute: async (topic: string) => {
+      console.log(`  [VECTOR] Semantic search for: "${topic}"`);
+      console.log(`  [VECTOR] Collection: ${config.collection ?? "default"}, TopK: ${config.topK ?? 5}`);
+
+      // Simulate vector search delay
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      // Mock semantic search results
+      return `[VectorDB] Found 3 semantically similar documents for "${topic}". Top match (similarity: 0.89): "Related research document..."`;
+    },
+  };
+}