modular-agent-examples 0.0.1

package/pubmed.ts

@@ -0,0 +1,289 @@
+import "dotenv/config";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { OpenAiAgent } from "../lib/agents/openai/OpenAiAgent";
+import { Tool } from "../lib/tools/Tool";
+import { createInterface } from "node:readline/promises";
+import { BaseAgent } from "../lib/agents/BaseAgent";
+import { History } from "../lib/history/History";
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// PubMed Search Tool
+const pubmedSearchTool = new Tool({
+  name: "pubmedSearch",
+  description: `This tool searches PubMed for medical research articles based on search terms and returns metadata for relevant papers.
+  It accepts search terms and additional parameters, and returns citation data for matching articles.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description:
+          "Search terms to use for finding medical literature. For best results, use specific medical terminology.",
+      },
+      maxResults: {
+        type: "number",
+        description:
+          "Maximum number of results to return (default: 10, max: 20).",
+      },
+      sortBy: {
+        type: "string",
+        description:
+          "How to sort results: 'relevance', 'date' (newest first), or 'cited' (most cited). Default is 'relevance'.",
+      },
+    },
+    required: ["query", "maxResults", "sortBy"],
+  },
+  execute: async (input): Promise<any> => {
+    try {
+      // Set defaults and enforce limits
+      const maxResults = Math.min(input.maxResults || 10, 20);
+      const sortBy = input.sortBy || "relevance";
+
+      // Use PubMed's E-utilities API
+      // First, search for IDs matching the query
+      const searchUrl = `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmode=json&term=${encodeURIComponent(
+        input.query
+      )}&retmax=${maxResults}&sort=${
+        sortBy === "date"
+          ? "pub+date"
+          : sortBy === "cited"
+          ? "most+cited"
+          : "relevance"
+      }`;
+      // console.log(searchUrl);
+      const searchResponse = await fetch(searchUrl);
+      const searchData = await searchResponse.json();
+
+      if (
+        !searchData.esearchresult ||
+        !searchData.esearchresult.idlist ||
+        searchData.esearchresult.idlist.length === 0
+      ) {
+        return {
+          count: 0,
+          message: "No results found for your query.",
+          articles: [],
+        };
+      }
+
+      const ids = searchData.esearchresult.idlist;
+
+      // Then, fetch summary data for these IDs
+      const summaryUrl = `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&retmode=json&id=${ids.join(
+        ","
+      )}`;
+      const summaryResponse = await fetch(summaryUrl);
+      const summaryData = await summaryResponse.json();
+
+      // Process and format results
+      const articles = ids
+        .map((id: string) => {
+          const article = summaryData.result[id];
+          if (!article) return null;
+
+          return {
+            pmid: id,
+            title: article.title,
+            authors: article.authors
+              ? article.authors.map((a: any) => `${a.name}`)
+              : ["No authors listed"],
+            journal:
+              article.fulljournalname || article.source || "Unknown journal",
+            publicationDate: article.pubdate || "Unknown date",
+            // abstract: article.abstract || "No abstract available",
+            doi: article.elocationid
+              ? article.elocationid.replace("doi: ", "")
+              : null,
+            url: `https://pubmed.ncbi.nlm.nih.gov/${id}/`,
+          };
+        })
+        .filter((a: any) => a !== null);
+      // console.log({
+      //   count: articles.length,
+      //   query: input.query,
+      //   articles,
+      // });
+      return {
+        count: articles.length,
+        query: input.query,
+        articles,
+      };
+    } catch (error: any) {
+      console.error("Error searching PubMed:", error);
+      return {
+        error: "Failed to search PubMed: " + error.message,
+      };
+    }
+  },
+});
+
+// PubMed Abstract Fetcher Tool
+const pubmedAbstractTool = new Tool({
+  name: "pubmedGetAbstract",
+  description: `This tool fetches the full abstract for a specific PubMed article by its ID (PMID).`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      pmid: {
+        type: "string",
+        description:
+          "PubMed ID (PMID) of the article to retrieve the abstract for.",
+      },
+    },
+    required: ["pmid"],
+  },
+  execute: async (input): Promise<any> => {
+    try {
+      const url = `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=${input.pmid}&retmode=json&rettype=abstract`;
+      const response = await fetch(url);
+
+      // PubMed efetch returns XML by default, so we'll manually extract the abstract
+      const text = await response.text();
+      // console.log({
+      //   pmid: input.pmid,
+      //   abstract: text,
+      //   fullText: false, // PubMed doesn't provide full text, only abstracts
+      //   url: `https://pubmed.ncbi.nlm.nih.gov/${input.pmid}/`,
+      // });
+
+      return {
+        pmid: input.pmid,
+        abstract: text,
+        fullText: false, // PubMed doesn't provide full text, only abstracts
+        url: `https://pubmed.ncbi.nlm.nih.gov/${input.pmid}/`,
+      };
+    } catch (error: any) {
+      return {
+        error: "Failed to retrieve abstract: " + error.message,
+      };
+    }
+  },
+});
+
+const history = new History();
+
+const medicalResearchAgent = new ClaudeAgent(
+  {
+    id: "medical-research",
+    name: "Medical Research Assistant",
+    description: `You are a medical research expert specializing in coming up with novel and in-depth knowledge based on literature research and extensive experience.
+
+  You have access to PubMed, a database of medical research papers. Your goal is to help users:
+  - Find relevant medical research for their questions
+  - Summarize findings from medical literature
+  - Explain medical concepts from research in clear, understandable terms
+  - Identify patterns and consensus across multiple papers
+  - Come up with novel strategies and thinking
+  - Try to dive deep in the subject and cast a wide net
+  - ALWAYS list sources
+
+  When responding:
+  1. Use the pubmedSearch tool to find relevant papers before providing any medical information
+  2. ALWAYS cite your sources with PMID numbers and links
+  3. Be clear about the strength of evidence (e.g., systematic review vs. single study)
+  4. Highlight limitations of studies when appropriate
+
+  You can use the pubmedGetAbstract tool to read full abstracts for the most relevant papers.`,
+    tools: [pubmedSearchTool, pubmedAbstractTool],
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    // Using Opus for better medical knowledge and reasoning
+    model: "claude-3-5-haiku-latest",
+    maxTokens: 8000,
+    temperature: 0.4,
+  },
+  history
+);
+
+// Alternative using OpenAI
+const openAiMedicalAgent = new OpenAiAgent(
+  {
+    id: "openai-medical-research",
+    name: "Medical Research Assistant",
+    description: `You are a medical research expert specializing in coming up with novel and in-depth knowledge based on literature research and extensive experience.
+
+  You have access to PubMed, a database of medical research papers. Your goal is to help users:
+  - Find relevant medical research for their questions
+  - Summarize findings from medical literature
+  - Explain medical concepts from research in clear, understandable terms
+  - Identify patterns and consensus across multiple papers
+  - Come up with novel strategies and thinking
+  - Try to dive deep in the subject and cast a wide net
+
+  When responding:
+  1. Use the pubmedSearch tool to find relevant papers before providing any medical information
+  2. ALWAYS cite your sources with PMID numbers and links
+  3. Be clear about the strength of evidence (e.g., systematic review vs. single study)
+  4. Highlight limitations of studies when appropriate
+
+  You can use the pubmedGetAbstract tool to read full abstracts for the most relevant papers.`,
+    tools: [pubmedSearchTool, pubmedAbstractTool],
+    apiKey: process.env.OPENAI_API_KEY as string,
+    model: "gpt-4o",
+  },
+  history
+);
+
+async function runMedicalResearchExample() {
+  try {
+    let running = true;
+    let agent: BaseAgent = medicalResearchAgent; // Default to Claude
+    // pubmedSearchTool.on(ToolEvent.EXECUTE, console.log);
+    // pubmedSearchTool.on(ToolEvent.RESULT, console.log);
+    // pubmedAbstractTool.on(ToolEvent.EXECUTE, console.log);
+    // Ask which model to use
+    const modelChoice = await rl.question(
+      "Which model would you like to use? [1] Claude (default) or [2] OpenAI: "
+    );
+
+    if (modelChoice === "2") {
+      agent = openAiMedicalAgent;
+      console.log("Using OpenAI model");
+    } else {
+      console.log("Using Claude model");
+    }
+
+    console.log("\n----- Medical Research Assistant -----");
+    console.log(
+      "Ask medical research questions and the assistant will search PubMed for you."
+    );
+    console.log("Type 'exit' to quit.");
+    console.log("---------------------------------------\n");
+
+    while (running) {
+      const question = await rl.question(
+        "\nWhat medical topic would you like to research? \n"
+      );
+
+      if (question.toLowerCase() === "exit") {
+        running = false;
+        continue;
+      }
+
+      console.log("\nSearching medical literature...");
+      const result = await agent.execute(question);
+
+      console.log("\n" + result);
+
+      // Ask if the user wants to continue
+      const continueResponse = await rl.question(
+        "\nWould you like to ask another question? (y/n): "
+      );
+      if (continueResponse.toLowerCase() !== "y") {
+        running = false;
+      }
+    }
+
+    rl.close();
+    process.exit(0);
+  } catch (error) {
+    console.error("Error:", error);
+    rl.close();
+    process.exit(1);
+  }
+}
+
+runMedicalResearchExample();

package/reasoning-with-sub-agent.ts

@@ -0,0 +1,311 @@
+/**
+ * Reasoning with Sub-Agent Example
+ *
+ * This example demonstrates using an agent as a reasoning assistant for another agent.
+ * A focused "reasoner" agent breaks down complex questions and analyzes them step-by-step,
+ * while a main agent coordinates and provides the final synthesized answer.
+ *
+ * Architecture:
+ *   Main Agent (coordinator, no specialized tools)
+ *     └── Reasoner Agent (specialized in analytical thinking and problem decomposition)
+ */
+
+import "dotenv/config";
+import { createInterface } from "node:readline/promises";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { OpenAiAgent } from "../lib/agents/openai/OpenAiAgent";
+import { MistralAgent } from "../lib/agents/mistral/MistralAgent";
+import { BaseAgent } from "../lib/agents/BaseAgent";
+import { Tool } from "../lib/tools/Tool";
+import { AgentEvent } from "../lib/agents/AgentEvent";
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// =============================================================================
+// Reasoning Tools (used by the reasoner sub-agent)
+// =============================================================================
+
+const decomposeQuestionTool = new Tool({
+  name: "decompose_question",
+  description: `Break down a complex question into smaller, manageable sub-questions.
+Returns a list of sub-questions that need to be answered to fully address the main question.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        description: "The complex question to decompose",
+      },
+    },
+    required: ["question"],
+  },
+  execute: async (input: { question: string }): Promise<unknown> => {
+    // This is a simulated tool - in a real system, this might use LLM or rules
+    return {
+      originalQuestion: input.question,
+      subQuestions: [
+        `What are the key concepts involved in: "${input.question}"?`,
+        `What assumptions are being made in: "${input.question}"?`,
+        `What are the possible approaches to answer: "${input.question}"?`,
+      ],
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+
+const analyzeAssumptionsTool = new Tool({
+  name: "analyze_assumptions",
+  description: `Identify and analyze the assumptions underlying a question or statement.
+Returns a list of implicit and explicit assumptions that should be considered.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      statement: {
+        type: "string",
+        description: "The statement or question to analyze for assumptions",
+      },
+    },
+    required: ["statement"],
+  },
+  execute: async (input: { statement: string }): Promise<unknown> => {
+    return {
+      analyzedStatement: input.statement,
+      assumptions: {
+        implicit: [
+          "The question has a definitive answer",
+          "Current information is complete and accurate",
+        ],
+        explicit: ["The context provided is sufficient"],
+        needsValidation: ["Check if all terms are clearly defined"],
+      },
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+
+const evaluateLogicTool = new Tool({
+  name: "evaluate_logic",
+  description: `Evaluate the logical structure of an argument or reasoning chain.
+Returns an analysis of logical validity, potential fallacies, and strength of reasoning.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      argument: {
+        type: "string",
+        description: "The argument or reasoning to evaluate",
+      },
+      context: {
+        type: "string",
+        description: "Additional context for the argument (optional)",
+      },
+    },
+    required: ["argument"],
+  },
+  execute: async (input: {
+    argument: string;
+    context?: string;
+  }): Promise<unknown> => {
+    return {
+      argument: input.argument,
+      context: input.context || "No additional context provided",
+      logicalStructure: {
+        isValid: true,
+        strength: "moderate",
+        potentialFallacies: [],
+        recommendations: [
+          "Consider alternative perspectives",
+          "Verify factual claims",
+        ],
+      },
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+
+// =============================================================================
+// Sub-Agent Creation (the analytical reasoner)
+// =============================================================================
+
+const REASONER_DESCRIPTION = `You are an analytical reasoning specialist. Your job is to:
+1. Break down complex questions into manageable parts
+2. Identify assumptions and logical structures
+3. Evaluate different perspectives and approaches
+4. Provide structured analytical insights
+
+
+Be thorough but concise, you only have 2000 tokens. Focus on clarity and logical rigor in a few lines.`;
+
+function createReasonerAgent(
+  provider: "claude" | "openai" | "mistral"
+): BaseAgent {
+  const config = {
+    id: "reasoner",
+    name: "Analytical Reasoner",
+    description: REASONER_DESCRIPTION,
+    tools: [],
+    maxTokens: 2048,
+  };
+
+  if (provider === "openai") {
+    return new OpenAiAgent({
+      ...config,
+      apiKey: process.env.OPENAI_API_KEY as string,
+      model: "gpt-4o-mini", // Fast and cost-effective, no reasoning overhead
+      // Note: For reasoning models (gpt-5-nano, o1, etc.), either:
+      // - Set disableReasoning: true to disable extended thinking
+      // - Or increase maxTokens (e.g., 8192) to accommodate reasoning tokens
+    });
+  }
+
+  if (provider === "mistral") {
+    return new MistralAgent({
+      ...config,
+      apiKey: process.env.MISTRAL_API_KEY as string,
+      model: "mistral-small-latest", // Efficient model for structured reasoning
+    });
+  }
+
+  return new ClaudeAgent({
+    ...config,
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    model: "claude-haiku-4-5", // Fast and efficient for analytical tasks
+  });
+}
+
+// =============================================================================
+// Main Agent Creation (the coordinator)
+// =============================================================================
+
+const MAIN_AGENT_DESCRIPTION = `You are a thoughtful assistant that helps users reason through complex questions.
+You have access to an analytical reasoner who can break down questions, analyze assumptions, and evaluate logic.
+
+When the user asks a complex question:
+1. Use the reasoner to analyze the question thoroughly
+2. Synthesize the analysis into a clear, helpful response
+3. Provide insights and perspectives that address the core question
+4. Acknowledge uncertainty where appropriate
+
+Be clear, thoughtful, and educational. Help the user understand not just the answer, but the reasoning process itself.`;
+
+function createMainAgent(
+  provider: "claude" | "openai" | "mistral",
+  reasonerTool: Tool<string>
+): BaseAgent {
+  const config = {
+    id: "main",
+    name: "Reasoning Assistant",
+    description: MAIN_AGENT_DESCRIPTION,
+    tools: [reasonerTool],
+    maxTokens: 3072,
+  };
+
+  if (provider === "openai") {
+    return new OpenAiAgent({
+      ...config,
+      apiKey: process.env.OPENAI_API_KEY as string,
+      model: "gpt-4o-mini", // More capable model for synthesis and coordination
+    });
+  }
+
+  if (provider === "mistral") {
+    return new MistralAgent({
+      ...config,
+      apiKey: process.env.MISTRAL_API_KEY as string,
+      model: "mistral-large-latest",
+    });
+  }
+
+  return new ClaudeAgent({
+    ...config,
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    model: "claude-haiku-4-5",
+  });
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  console.log("=== Reasoning Assistant with Sub-Agent ===\n");
+  console.log(
+    "This example uses a specialized 'reasoner' agent to analyze questions,"
+  );
+  console.log(
+    "while a coordinator agent synthesizes the analysis into helpful responses.\n"
+  );
+
+  // Choose provider
+  const providerChoice = await rl.question(
+    "Which provider? [1] Claude (default), [2] OpenAI, or [3] Mistral: "
+  );
+  let provider: "claude" | "openai" | "mistral" = "claude";
+  if (providerChoice === "2") {
+    provider = "openai";
+  } else if (providerChoice === "3") {
+    provider = "mistral";
+  }
+  console.log(`Using ${provider}\n`);
+
+  // Create the reasoner sub-agent
+  const reasonerAgent = createReasonerAgent(provider);
+  console.log(
+    "Created reasoner sub-agent (specialized in analytical thinking)"
+  );
+
+  // Wrap the reasoner agent as a tool
+  const reasonerTool = Tool.fromAgent(
+    reasonerAgent,
+    `Use this analytical reasoner to break down complex questions, identify assumptions, and evaluate logic.
+Provide the question or problem you want analyzed, and it will return structured analytical insights.`
+  );
+  console.log("Wrapped reasoner as a tool for the main agent");
+
+  // Create the main agent with the reasoner tool
+  const mainAgent = createMainAgent(provider, reasonerTool);
+  console.log("Created main agent (coordinator for synthesis)\n");
+
+  // Interactive loop for questions
+  console.log(
+    "Ask me any complex question and I'll reason through it with you."
+  );
+  console.log("Type 'quit' or 'exit' to end the conversation.\n");
+
+  while (true) {
+    const question = await rl.question("> ");
+
+    if (
+      question.toLowerCase() === "quit" ||
+      question.toLowerCase() === "exit"
+    ) {
+      console.log("\nGoodbye!");
+      break;
+    }
+
+    if (!question.trim()) {
+      continue;
+    }
+
+    console.log("\n--- Reasoning Process ---");
+
+    try {
+      reasonerAgent.on(AgentEvent.AFTER_EXECUTE, console.log);
+      reasonerAgent.on(AgentEvent.BEFORE_EXECUTE, console.log);
+      const result = await mainAgent.execute(question);
+
+      console.log("\n--- Response ---");
+      console.log(result);
+      console.log("\n");
+    } catch (error) {
+      console.error("Error:", error);
+    }
+  }
+
+  rl.close();
+  process.exit(0);
+}
+
+main().catch(console.error);

package/synchronous/index.ts

@@ -0,0 +1,48 @@
+import "dotenv/config";
+import { OpenAiAgent } from "../../lib/agents/openai/OpenAiAgent";
+import { AgentGraph } from "../../lib/graph/AgentGraph";
+import { AgentEvent } from "../../lib/agents/AgentEvent";
+export const agent1 = new OpenAiAgent({
+  id: "medical-research",
+  name: "Deep thinker agent",
+  description: `You write code for a problem that the user has`,
+  tools: [],
+  apiKey: process.env.OPENAI_API_KEY as string,
+  temperature: 1,
+  model: "gpt-4o-mini",
+  maxTokens: 8000,
+});
+
+export const agent2 = new OpenAiAgent({
+  id: "medical-research",
+  name: "Deep feedback agent",
+  description: `You review code and write tests. Return both the code and the tests.`,
+  tools: [],
+  apiKey: process.env.OPENAI_API_KEY as string,
+  model: "gpt-4o-mini",
+  temperature: 0,
+  maxTokens: 8000,
+});
+
+const graph = AgentGraph.synchronous(agent1, agent2);
+
+agent1.on(AgentEvent.AFTER_EXECUTE, (event: AgentEvent) => {
+  console.log(JSON.stringify(event, undefined, "  "));
+});
+agent2.on(AgentEvent.AFTER_EXECUTE, (event: AgentEvent) => {
+  console.log(JSON.stringify(event, null, "  "));
+});
+
+function run() {
+  graph
+    .execute(
+      `Write a TS class that supports Agents working together in a graph.
+      An initial execute command will add to the input of the first agent the choice of connected agents.
+      interface Agent{
+      execute(input:string):Promise<string>
+      }
+      `
+    )
+    .then(console.log);
+}
+run();

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "strictPropertyInitialization": false,
+    "noEmit": true
+  },
+  "include": ["./**/*", "../lib/**/*"]
+}