modular-agent-examples 0.0.1

package/graph/sequential-example.ts

@@ -0,0 +1,141 @@
+/**
+ * Sequential Executor Example
+ *
+ * Demonstrates chaining agents in sequence where each agent's output
+ * becomes the input for the next agent.
+ *
+ * Use case: Research pipeline with fact-checking and summarization
+ *
+ * For data-fetching pipelines with factories, see: ./data-pipeline/
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph } 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);
+}
+
+// ============================================================================
+// Agent Definitions
+// ============================================================================
+
+const researchAgent = new ClaudeAgent({
+  id: "researcher",
+  name: "Research Agent",
+  description: `You are a research agent. Given a topic, provide detailed factual information.
+Be thorough but concise. Focus on key facts, dates, and verifiable information.
+Output your findings in a structured format.`,
+  apiKey,
+  maxTokens: 1024,
+});
+
+const factCheckerAgent = new ClaudeAgent({
+  id: "fact-checker",
+  name: "Fact Checker Agent",
+  description: `You are a fact-checking agent. You receive research findings and verify their accuracy.
+Mark any claims that seem questionable or need verification.
+Add confidence levels (High/Medium/Low) to each fact.
+Correct any obvious errors you find.`,
+  apiKey,
+  maxTokens: 1024,
+});
+
+const summaryAgent = new ClaudeAgent({
+  id: "summarizer",
+  name: "Summary Agent",
+  description: `You are a summarization agent. You receive fact-checked research and create a clear,
+concise summary suitable for a general audience.
+Highlight the most important points.
+Include a brief conclusion with key takeaways.
+Keep the summary under 200 words.`,
+  apiKey,
+  maxTokens: 512,
+});
+
+// ============================================================================
+// Example 1: Basic Sequential Pipeline
+// ============================================================================
+
+async function runSequentialExample() {
+  console.log("=== Sequential Executor Example ===\n");
+  console.log("Pipeline: Research -> Fact-Check -> Summarize\n");
+
+  const researchPipeline = AgentGraph.sequential(
+    researchAgent,
+    factCheckerAgent,
+    summaryAgent
+  );
+
+  const topic = "The discovery of penicillin and its impact on medicine";
+  console.log(`Topic: "${topic}"\n`);
+
+  try {
+    const result = await researchPipeline.execute(topic);
+    console.log("\n=== Final Summary ===\n");
+    console.log(result);
+  } catch (error) {
+    console.error("Pipeline failed:", error);
+  }
+}
+
+// ============================================================================
+// Example 2: Raw Input Mode (no JSON wrapping)
+// ============================================================================
+
+async function runRawSequentialExample() {
+  console.log("\n=== Sequential with Raw Input ===\n");
+
+  const translator = new ClaudeAgent({
+    id: "translator",
+    name: "Translator",
+    description: `Translate the input text to French. Output only the translation, nothing else.`,
+    apiKey,
+    maxTokens: 256,
+  });
+
+  const polisher = new ClaudeAgent({
+    id: "polisher",
+    name: "Polisher",
+    description: `You receive French text. Make it more elegant and poetic while keeping the meaning.
+Output only the polished French text.`,
+    apiKey,
+    maxTokens: 256,
+  });
+
+  // wrapInput: false passes raw output between agents
+  const translationPipeline = AgentGraph.sequential(
+    { wrapInput: false },
+    translator,
+    polisher
+  );
+
+  const englishText =
+    "The sun sets slowly over the mountains, painting the sky in shades of orange and purple.";
+  console.log(`English: "${englishText}"\n`);
+
+  try {
+    const result = await translationPipeline.execute(englishText);
+    console.log(`Polished French: "${result}"`);
+  } catch (error) {
+    console.error("Translation failed:", error);
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  await runSequentialExample();
+  await runRawSequentialExample();
+
+  console.log("\n---");
+  console.log("For data-fetching pipelines with DB/API integration,");
+  console.log("see: examples/graph/data-pipeline/");
+}
+
+main().catch(console.error);

package/graph/voting-example.ts

@@ -0,0 +1,159 @@
+/**
+ * Voting System Example
+ *
+ * Demonstrates using a judge agent to select the best answer
+ * from multiple expert responses.
+ *
+ * Use case: Getting diverse opinions and synthesizing the best answer
+ */
+import "dotenv/config";
+import { ClaudeAgent } from "../../lib/agents/anthropic/ClaudeAgent";
+import { AgentGraph, VotingInput } from "../../lib/graph/AgentGraph";
+
+const apiKey = process.env.ANTHROPIC_API_KEY as string;
+
+if (!apiKey) {
+  console.error("Please set ANTHROPIC_API_KEY environment variable");
+  process.exit(1);
+}
+
+// Three experts with different approaches
+const conservativeExpert = new ClaudeAgent({
+  id: "conservative",
+  name: "Conservative Expert",
+  description: `You are a conservative, risk-averse advisor.
+When answering questions, prioritize safety, proven methods, and caution.
+Recommend established approaches over experimental ones.
+Keep responses under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+const innovativeExpert = new ClaudeAgent({
+  id: "innovative",
+  name: "Innovative Expert",
+  description: `You are an innovative, forward-thinking advisor.
+When answering questions, prioritize new approaches, cutting-edge solutions, and bold ideas.
+Recommend creative and unconventional methods.
+Keep responses under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+const balancedExpert = new ClaudeAgent({
+  id: "balanced",
+  name: "Balanced Expert",
+  description: `You are a balanced, pragmatic advisor.
+When answering questions, weigh both traditional and innovative approaches.
+Recommend solutions that balance risk and reward.
+Keep responses under 100 words.`,
+  apiKey,
+  maxTokens: 256,
+});
+
+// Judge agent to evaluate and select the best answer
+const judgeAgent = new ClaudeAgent({
+  id: "judge",
+  name: "Judge",
+  description: `You are an impartial judge evaluating expert opinions.
+Analyze each expert's response for:
+- Practicality and feasibility
+- Completeness of the answer
+- Quality of reasoning
+
+Select the best answer OR synthesize a superior answer combining the best elements.
+Explain your choice briefly, then provide the final recommended answer.`,
+  apiKey,
+  maxTokens: 512,
+});
+
+async function runBasicVotingExample() {
+  console.log("=== Basic Voting System Example ===\n");
+
+  const question = "What's the best strategy for a small business to adopt AI?";
+  console.log(`Question: "${question}"\n`);
+
+  // Get opinions from all experts
+  console.log("Gathering expert opinions...\n");
+
+  const [conservative, innovative, balanced] = await Promise.all([
+    conservativeExpert.execute(question),
+    innovativeExpert.execute(question),
+    balancedExpert.execute(question),
+  ]);
+
+  console.log("--- Conservative Expert ---");
+  console.log(conservative);
+  console.log("\n--- Innovative Expert ---");
+  console.log(innovative);
+  console.log("\n--- Balanced Expert ---");
+  console.log(balanced);
+
+  // Create voting system
+  const votingSystem = AgentGraph.votingSystem(judgeAgent);
+
+  // Submit for voting
+  const votingInput: VotingInput = {
+    originalInput: question,
+    solutions: [
+      conservative as string,
+      innovative as string,
+      balanced as string,
+    ],
+  };
+
+  console.log("\n--- Judge's Verdict ---\n");
+  const verdict = await votingSystem.execute(votingInput);
+  console.log(verdict);
+}
+
+// Custom prompt template example
+async function runCustomTemplateExample() {
+  console.log("\n=== Custom Voting Template Example ===\n");
+
+  const customJudge = new ClaudeAgent({
+    id: "custom-judge",
+    name: "Custom Judge",
+    description: `You evaluate code solutions. Pick the best one based on:
+- Code quality and readability
+- Performance considerations
+- Best practices
+
+Output only the winning solution number and a brief explanation.`,
+    apiKey,
+    maxTokens: 256,
+  });
+
+  const votingSystem = AgentGraph.votingSystem(customJudge, {
+    promptTemplate: `## Code Review Task
+
+**Original Request:** {originalQuestion}
+
+**Submitted Solutions:**
+{expertAnswers}
+
+Evaluate each solution and declare a winner.`,
+  });
+
+  const solutions = [
+    "Solution using a for loop: for(let i=0; i<arr.length; i++) { sum += arr[i]; }",
+    "Solution using reduce: arr.reduce((sum, val) => sum + val, 0)",
+    "Solution using forEach: let sum=0; arr.forEach(x => sum += x);",
+  ];
+
+  const result = await votingSystem.execute({
+    originalInput: "Sum all numbers in an array",
+    solutions,
+  });
+
+  console.log("Judge's decision:");
+  console.log(result);
+}
+
+// Run examples
+async function main() {
+  await runBasicVotingExample();
+  await runCustomTemplateExample();
+}
+
+main().catch(console.error);

package/graph-rag/docker-compose.yaml

@@ -0,0 +1,14 @@
+version: "3.8"
+services:
+  neo4j:
+    image: neo4j:latest
+    container_name: neo4j_db
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    environment:
+      NEO4J_AUTH: neo4j/your_password
+    volumes:
+      - neo4j-data:/data
+volumes:
+  neo4j-data:

package/graph-rag/index.js

@@ -0,0 +1,99 @@
+const neo4j = require("neo4j-driver");
+
+// Neo4j connection details
+const uri = "bolt://localhost:7687";
+const user = "neo4j";
+const password = "your_password";
+
+const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+
+// Helper function to generate random vectors
+function generateRandomVector(dim) {
+  return Array.from({ length: dim }, () => (Math.random() * 2 - 1).toFixed(4));
+}
+
+async function runTests() {
+  const session = driver.session();
+
+  try {
+    // Clear the database
+    await session.run("MATCH (n) DETACH DELETE n");
+    console.log("Database cleared.");
+
+    // Insert nodes with vector embeddings
+    const items = [
+      { name: "Item1", embedding: generateRandomVector(3) },
+      { name: "Item2", embedding: generateRandomVector(3) },
+      { name: "Item3", embedding: generateRandomVector(3) },
+    ];
+
+    for (const item of items) {
+      await session.run(
+        "CREATE (i:Item {name: $name, embedding: $embedding})",
+        { name: item.name, embedding: item.embedding.map(Number) }
+      );
+      console.log(
+        `Inserted node: ${item.name} with embedding ${item.embedding}`
+      );
+    }
+
+    // Perform vector similarity search (cosine similarity)
+    const queryVector = generateRandomVector(3);
+    console.log(`Querying with vector: ${queryVector}`);
+
+    const result = await session.run(
+      `
+      MATCH (i:Item)
+      WITH i, $queryVector AS query
+      RETURN i.name, i.embedding,
+             gds.similarity.cosine(i.embedding, query) AS similarity
+      ORDER BY similarity DESC
+      LIMIT 2
+      `,
+      { queryVector: queryVector.map(Number) }
+    );
+
+    console.log("Vector similarity search results:");
+    result.records.forEach((record) => {
+      console.log(
+        `Item: ${record.get("i.name")}, Embedding: ${record.get(
+          "i.embedding"
+        )}, Similarity: ${record.get("similarity")}`
+      );
+    });
+
+    // Create a simple graph with relationships
+    await session.run(
+      `
+      MATCH (i1:Item {name: 'Item1'}), (i2:Item {name: 'Item2'})
+      CREATE (i1)-[:RELATED_TO {weight: 0.8}]->(i2)
+      `
+    );
+    console.log("Created relationship between Item1 and Item2.");
+
+    // Query the graph
+    const graphResult = await session.run(
+      `
+      MATCH (i:Item)-[r:RELATED_TO]->(other)
+      RETURN i.name, type(r), other.name, r.weight
+      `
+    );
+
+    console.log("Graph query results:");
+    graphResult.records.forEach((record) => {
+      console.log(
+        `From: ${record.get("i.name")} -> ${record.get(
+          "other.name"
+        )} via ${record.get("type(r)")}, Weight: ${record.get("r.weight")}`
+      );
+    });
+  } catch (error) {
+    console.error("Error:", error);
+  } finally {
+    await session.close();
+    await driver.close();
+  }
+}
+
+// Run the tests
+runTests();

package/graph-rag/init-db.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
+    CREATE EXTENSION IF NOT EXISTS vector;
+    CREATE EXTENSION IF NOT EXISTS age;
+    LOAD 'age';
+    SET search_path = ag_catalog, "\$user", public;
+EOSQL

package/graph-rag/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "graph-rag",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "neo4j-driver": "^5.28.1"
+  }
+}

package/history-compression-example.ts

@@ -0,0 +1,163 @@
+/**
+ * History Compression Example
+ *
+ * Demonstrates the history plugin system with two complementary strategies:
+ *
+ * 1. toolResultMaskingPlugin — Read-time masking of old tool results.
+ *    Full content is always stored; only the view seen by the LLM is masked.
+ *    The agent can fetch any masked result on demand via retrieve_tool_result.
+ *
+ * 2. compressionPlugin — Rolling LLM summarization of old conversation turns.
+ *    Older turns are replaced by a compact summary entry, reducing token usage
+ *    while preserving the gist of what happened.
+ *
+ * Both plugins compose on the same history instance. Tool result masking is
+ * free (sync, no LLM calls). Rolling summarization runs automatically via
+ * autoReduceWhen when the token budget is exceeded — no manual history.reduce()
+ * call required.
+ */
+
+import "dotenv/config";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { History } from "../lib/history/History";
+import { Tool } from "../lib/tools/Tool";
+import { compressionPlugin } from "../lib/history/plugins/compressionPlugin";
+import { toolResultMaskingPlugin } from "../lib/history/plugins/toolResultMaskingPlugin";
+
+// ---------------------------------------------------------------------------
+// Simulated tools
+// ---------------------------------------------------------------------------
+
+const searchTool = new Tool<string>({
+  name: "web_search",
+  description: "Search the web for information",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query" },
+    },
+    required: ["query"],
+  },
+  execute: async ({ query }: { query: string }): Promise<string> => {
+    // Simulate a large search result
+    return (
+      `Search results for "${query}":\n` +
+      "1. Result one with detailed information about the topic...\n".repeat(
+        20
+      ) +
+      "2. Result two with more details...\n".repeat(20)
+    );
+  },
+});
+
+const calculatorTool = new Tool<number>({
+  name: "calculator",
+  description: "Perform arithmetic calculations",
+  inputSchema: {
+    type: "object",
+    properties: {
+      expression: {
+        type: "string",
+        description: "Math expression to evaluate",
+      },
+    },
+    required: ["expression"],
+  },
+  execute: async ({ expression }: { expression: string }): Promise<number> => {
+    // Safe eval for demo purposes only
+    return Function(`"use strict"; return (${expression})`)() as number;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const apiKey = process.env.ANTHROPIC_API_KEY;
+if (!apiKey) throw new Error("ANTHROPIC_API_KEY is required");
+
+// Dedicated summarization agent — cheap, fast model, no tools
+const summaryAgent = new ClaudeAgent({
+  id: "summarizer",
+  name: "Summarizer",
+  description: "Summarizes conversation history concisely",
+  apiKey,
+  model: "claude-haiku-4-5-20251001",
+});
+
+// Masking plugin: keep 1 recent web_search result verbatim; mask older ones.
+// Calculator results are excluded — they're tiny and always useful verbatim.
+const maskingPlugin = toolResultMaskingPlugin({
+  keepRecentResults: 1,
+  exclude: ["calculator"],
+  minTokensToMask: 50,
+});
+
+// Shared history with both plugins registered.
+// compressionPlugin auto-triggers when the history exceeds 2 000 tokens.
+const history = new History([], { maxTokens: 2000 })
+  .use(maskingPlugin)
+  .use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 2000 } }));
+
+// Surface async plugin errors
+history.on("pluginError", (error: Error, _plugin: unknown, hook: string) => {
+  console.error(`[pluginError] ${hook}: ${error.message}`);
+});
+
+// Main agent with the retrieve tool wired in
+const agent = new ClaudeAgent(
+  {
+    id: "assistant",
+    name: "Research Assistant",
+    description: "A research assistant with web search and calculation tools",
+    apiKey,
+    model: "claude-sonnet-4-6",
+    tools: [
+      searchTool,
+      calculatorTool,
+      maskingPlugin.retrieveTool, // allows retrieval of masked results
+    ],
+  },
+  history
+);
+
+// ---------------------------------------------------------------------------
+// Simulated conversation
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log("=== History Compression Example ===\n");
+
+  const turns = [
+    "Search for information about the history of the internet.",
+    "Now search for information about artificial intelligence milestones.",
+    "What is 1024 * 768?",
+    "Search for quantum computing breakthroughs in 2024.",
+    "Summarise everything we've discussed so far.",
+  ];
+
+  for (const turn of turns) {
+    console.log(`\n[User] ${turn}`);
+    console.log(
+      `  History before: ${history.length} entries, ~${history.totalEstimatedTokens} tokens`
+    );
+
+    const response = await agent.execute(turn);
+    console.log(`[Assistant] ${response.slice(0, 200)}...`);
+    console.log(
+      `  History after: ${history.length} entries, ~${history.totalEstimatedTokens} tokens`
+    );
+  }
+
+  console.log(
+    "\nNote: compressionPlugin auto-triggered whenever history exceeded 2 000 tokens."
+  );
+  console.log(
+    "Tool results are masked in the agent view but stored in full."
+  );
+  console.log(
+    "The agent can call retrieve_tool_result(tool_call_id) to access any masked result."
+  );
+}
+
+main().catch(console.error);