@jackchen_me/open-multi-agent 0.1.0 → 1.0.0

package/examples/07-fan-out-aggregate.ts

@@ -0,0 +1,209 @@
+/**
+ * Example 07 — Fan-Out / Aggregate (MapReduce) Pattern
+ *
+ * Demonstrates:
+ * - Fan-out: send the same question to N "analyst" agents in parallel
+ * - Aggregate: a "synthesizer" agent reads all analyst outputs and produces
+ *   a balanced final report
+ * - AgentPool with runParallel() for concurrent fan-out
+ * - No tools needed — pure LLM reasoning to keep the focus on the pattern
+ *
+ * Run:
+ *   npx tsx examples/07-fan-out-aggregate.ts
+ *
+ * Prerequisites:
+ *   ANTHROPIC_API_KEY env var must be set.
+ */
+
+import { Agent, AgentPool, ToolRegistry, ToolExecutor, registerBuiltInTools } from '../src/index.js'
+import type { AgentConfig, AgentRunResult } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Analysis topic
+// ---------------------------------------------------------------------------
+
+const TOPIC = `Should a solo developer build a SaaS product that uses AI agents
+for automated customer support? Consider the current state of AI technology,
+market demand, competition, costs, and the unique constraints of being a solo
+founder with limited time (~6 hours/day of productive work).`
+
+// ---------------------------------------------------------------------------
+// Analyst agent configs — three perspectives on the same question
+// ---------------------------------------------------------------------------
+
+const optimistConfig: AgentConfig = {
+  name: 'optimist',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are an optimistic technology analyst who focuses on
+opportunities, upside potential, and emerging trends. You see possibilities
+where others see obstacles. Back your optimism with concrete reasoning —
+cite market trends, cost curves, and real capabilities. Keep your analysis
+to 200-300 words.`,
+  maxTurns: 1,
+  temperature: 0.4,
+}
+
+const skepticConfig: AgentConfig = {
+  name: 'skeptic',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are a skeptical technology analyst who focuses on risks,
+challenges, failure modes, and hidden costs. You stress-test assumptions and
+ask "what could go wrong?" Back your skepticism with concrete reasoning —
+cite failure rates, technical limitations, and market realities. Keep your
+analysis to 200-300 words.`,
+  maxTurns: 1,
+  temperature: 0.4,
+}
+
+const pragmatistConfig: AgentConfig = {
+  name: 'pragmatist',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are a pragmatic technology analyst who focuses on practical
+feasibility, execution complexity, and resource requirements. You care about
+what works today, not what might work someday. You think in terms of MVPs,
+timelines, and concrete tradeoffs. Keep your analysis to 200-300 words.`,
+  maxTurns: 1,
+  temperature: 0.4,
+}
+
+const synthesizerConfig: AgentConfig = {
+  name: 'synthesizer',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are a senior strategy advisor who synthesizes multiple
+perspectives into a balanced, actionable recommendation. You do not simply
+summarise — you weigh the arguments, identify where they agree and disagree,
+and produce a clear verdict with next steps. Structure your output as:
+
+1. Key agreements across perspectives
+2. Key disagreements and how you weigh them
+3. Verdict (go / no-go / conditional go)
+4. Recommended next steps (3-5 bullet points)
+
+Keep the final report to 300-400 words.`,
+  maxTurns: 1,
+  temperature: 0.3,
+}
+
+// ---------------------------------------------------------------------------
+// Build agents — no tools needed for pure reasoning
+// ---------------------------------------------------------------------------
+
+function buildAgent(config: AgentConfig): Agent {
+  const registry = new ToolRegistry()
+  registerBuiltInTools(registry) // not needed here, but safe if tools are added later
+  const executor = new ToolExecutor(registry)
+  return new Agent(config, registry, executor)
+}
+
+const optimist = buildAgent(optimistConfig)
+const skeptic = buildAgent(skepticConfig)
+const pragmatist = buildAgent(pragmatistConfig)
+const synthesizer = buildAgent(synthesizerConfig)
+
+// ---------------------------------------------------------------------------
+// Set up the pool
+// ---------------------------------------------------------------------------
+
+const pool = new AgentPool(3) // 3 analysts can run simultaneously
+pool.add(optimist)
+pool.add(skeptic)
+pool.add(pragmatist)
+pool.add(synthesizer)
+
+console.log('Fan-Out / Aggregate (MapReduce) Pattern')
+console.log('='.repeat(60))
+console.log(`\nTopic: ${TOPIC.replace(/\n/g, ' ').trim()}\n`)
+
+// ---------------------------------------------------------------------------
+// Step 1: Fan-out — run all 3 analysts in parallel
+// ---------------------------------------------------------------------------
+
+console.log('[Step 1] Fan-out: 3 analysts running in parallel...\n')
+
+const analystResults: Map<string, AgentRunResult> = await pool.runParallel([
+  { agent: 'optimist',   prompt: TOPIC },
+  { agent: 'skeptic',    prompt: TOPIC },
+  { agent: 'pragmatist', prompt: TOPIC },
+])
+
+// Print each analyst's output (truncated)
+const analysts = ['optimist', 'skeptic', 'pragmatist'] as const
+for (const name of analysts) {
+  const result = analystResults.get(name)!
+  const status = result.success ? 'OK' : 'FAILED'
+  console.log(`  ${name} [${status}] — ${result.tokenUsage.output_tokens} output tokens`)
+  console.log(`  ${result.output.slice(0, 150).replace(/\n/g, ' ')}...`)
+  console.log()
+}
+
+// Check all analysts succeeded
+for (const name of analysts) {
+  if (!analystResults.get(name)!.success) {
+    console.error(`Analyst '${name}' failed: ${analystResults.get(name)!.output}`)
+    process.exit(1)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: Aggregate — synthesizer reads all 3 analyses
+// ---------------------------------------------------------------------------
+
+console.log('[Step 2] Aggregate: synthesizer producing final report...\n')
+
+const synthesizerPrompt = `Three analysts have independently evaluated the same question.
+Read their analyses below and produce your synthesis report.
+
+--- OPTIMIST ---
+${analystResults.get('optimist')!.output}
+
+--- SKEPTIC ---
+${analystResults.get('skeptic')!.output}
+
+--- PRAGMATIST ---
+${analystResults.get('pragmatist')!.output}
+
+Now synthesize these three perspectives into a balanced recommendation.`
+
+const synthResult = await pool.run('synthesizer', synthesizerPrompt)
+
+if (!synthResult.success) {
+  console.error('Synthesizer failed:', synthResult.output)
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// Final output
+// ---------------------------------------------------------------------------
+
+console.log('='.repeat(60))
+console.log('SYNTHESIZED REPORT')
+console.log('='.repeat(60))
+console.log()
+console.log(synthResult.output)
+console.log()
+console.log('-'.repeat(60))
+
+// ---------------------------------------------------------------------------
+// Token usage comparison
+// ---------------------------------------------------------------------------
+
+console.log('\nToken Usage Summary:')
+console.log('-'.repeat(60))
+
+let totalInput = 0
+let totalOutput = 0
+
+for (const name of analysts) {
+  const r = analystResults.get(name)!
+  totalInput += r.tokenUsage.input_tokens
+  totalOutput += r.tokenUsage.output_tokens
+  console.log(`  ${name.padEnd(12)} — input: ${r.tokenUsage.input_tokens}, output: ${r.tokenUsage.output_tokens}`)
+}
+
+totalInput += synthResult.tokenUsage.input_tokens
+totalOutput += synthResult.tokenUsage.output_tokens
+console.log(`  ${'synthesizer'.padEnd(12)} — input: ${synthResult.tokenUsage.input_tokens}, output: ${synthResult.tokenUsage.output_tokens}`)
+console.log('-'.repeat(60))
+console.log(`  ${'TOTAL'.padEnd(12)} — input: ${totalInput}, output: ${totalOutput}`)
+
+console.log('\nDone.')

package/examples/08-gemma4-local.ts

@@ -0,0 +1,192 @@
+/**
+ * Example 08 — Gemma 4 Local (100% Local, Zero API Cost)
+ *
+ * Demonstrates both execution modes with a fully local Gemma 4 model via
+ * Ollama. No cloud API keys needed — everything runs on your machine.
+ *
+ * Part 1 — runTasks(): explicit task pipeline (researcher → summarizer)
+ * Part 2 — runTeam(): auto-orchestration where Gemma 4 acts as coordinator,
+ *           decomposes the goal into tasks, and synthesises the final result
+ *
+ * This is the hardest test for a local model — runTeam() requires it to
+ * produce valid JSON for task decomposition AND do tool-calling for execution.
+ * Gemma 4 e2b (5.1B params) handles both reliably.
+ *
+ * Run:
+ *   no_proxy=localhost npx tsx examples/08-gemma4-local.ts
+ *
+ * Prerequisites:
+ *   1. Ollama >= 0.20.0 installed and running: https://ollama.com
+ *   2. Pull the model: ollama pull gemma4:e2b
+ *      (or gemma4:e4b for better quality on machines with more RAM)
+ *   3. No API keys needed!
+ *
+ * Note: The no_proxy=localhost prefix is needed if you have an HTTP proxy
+ * configured, since the OpenAI SDK would otherwise route Ollama requests
+ * through the proxy.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig, OrchestratorEvent, Task } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Configuration — change this to match your Ollama setup
+// ---------------------------------------------------------------------------
+
+// See available tags at https://ollama.com/library/gemma4
+const OLLAMA_MODEL = 'gemma4:e2b'      // or 'gemma4:e4b', 'gemma4:26b'
+const OLLAMA_BASE_URL = 'http://localhost:11434/v1'
+const OUTPUT_DIR = '/tmp/gemma4-demo'
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+
+const researcher: AgentConfig = {
+  name: 'researcher',
+  model: OLLAMA_MODEL,
+  provider: 'openai',
+  baseURL: OLLAMA_BASE_URL,
+  apiKey: 'ollama', // placeholder — Ollama ignores this, but the OpenAI SDK requires a non-empty value
+  systemPrompt: `You are a system researcher. Use bash to run non-destructive,
+read-only commands (uname -a, sw_vers, df -h, uptime, etc.) and report results.
+Use file_write to save reports when asked.`,
+  tools: ['bash', 'file_write'],
+  maxTurns: 8,
+}
+
+const summarizer: AgentConfig = {
+  name: 'summarizer',
+  model: OLLAMA_MODEL,
+  provider: 'openai',
+  baseURL: OLLAMA_BASE_URL,
+  apiKey: 'ollama',
+  systemPrompt: `You are a technical writer. Read files and produce concise,
+structured Markdown summaries. Use file_write to save reports when asked.`,
+  tools: ['file_read', 'file_write'],
+  maxTurns: 4,
+}
+
+// ---------------------------------------------------------------------------
+// Progress handler
+// ---------------------------------------------------------------------------
+
+function handleProgress(event: OrchestratorEvent): void {
+  const ts = new Date().toISOString().slice(11, 23)
+  switch (event.type) {
+    case 'task_start': {
+      const task = event.data as Task | undefined
+      console.log(`[${ts}] TASK START    "${task?.title ?? event.task}" → ${task?.assignee ?? '?'}`)
+      break
+    }
+    case 'task_complete':
+      console.log(`[${ts}] TASK DONE     "${event.task}"`)
+      break
+    case 'agent_start':
+      console.log(`[${ts}] AGENT START   ${event.agent}`)
+      break
+    case 'agent_complete':
+      console.log(`[${ts}] AGENT DONE    ${event.agent}`)
+      break
+    case 'error':
+      console.error(`[${ts}] ERROR         ${event.agent ?? ''}  task=${event.task ?? '?'}`)
+      break
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Part 1: runTasks() — Explicit task pipeline
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('Part 1: runTasks() — Explicit Pipeline')
+console.log('='.repeat(60))
+console.log(`  model       → ${OLLAMA_MODEL} via Ollama`)
+console.log(`  pipeline    → researcher gathers info → summarizer writes summary`)
+console.log()
+
+const orchestrator1 = new OpenMultiAgent({
+  defaultModel: OLLAMA_MODEL,
+  maxConcurrency: 1, // local model serves one request at a time
+  onProgress: handleProgress,
+})
+
+const team1 = orchestrator1.createTeam('explicit', {
+  name: 'explicit',
+  agents: [researcher, summarizer],
+  sharedMemory: true,
+})
+
+const tasks = [
+  {
+    title: 'Gather system information',
+    description: `Use bash to run system info commands (uname -a, sw_vers, sysctl, df -h, uptime).
+Then write a structured Markdown report to ${OUTPUT_DIR}/system-report.md with sections:
+OS, Hardware, Disk, and Uptime.`,
+    assignee: 'researcher',
+  },
+  {
+    title: 'Summarize the report',
+    description: `Read the file at ${OUTPUT_DIR}/system-report.md.
+Produce a concise one-paragraph executive summary of the system information.`,
+    assignee: 'summarizer',
+    dependsOn: ['Gather system information'],
+  },
+]
+
+const start1 = Date.now()
+const result1 = await orchestrator1.runTasks(team1, tasks)
+
+console.log(`\nSuccess: ${result1.success}  Time: ${((Date.now() - start1) / 1000).toFixed(1)}s`)
+console.log(`Tokens — input: ${result1.totalTokenUsage.input_tokens}, output: ${result1.totalTokenUsage.output_tokens}`)
+
+const summary = result1.agentResults.get('summarizer')
+if (summary?.success) {
+  console.log('\nSummary (from local Gemma 4):')
+  console.log('-'.repeat(60))
+  console.log(summary.output)
+  console.log('-'.repeat(60))
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Part 2: runTeam() — Auto-orchestration (Gemma 4 as coordinator)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n\nPart 2: runTeam() — Auto-Orchestration')
+console.log('='.repeat(60))
+console.log(`  coordinator  → auto-created by runTeam(), also Gemma 4`)
+console.log(`  goal         → given in natural language, framework plans everything`)
+console.log()
+
+const orchestrator2 = new OpenMultiAgent({
+  defaultModel: OLLAMA_MODEL,
+  defaultProvider: 'openai',
+  defaultBaseURL: OLLAMA_BASE_URL,
+  defaultApiKey: 'ollama',
+  maxConcurrency: 1,
+  onProgress: handleProgress,
+})
+
+const team2 = orchestrator2.createTeam('auto', {
+  name: 'auto',
+  agents: [researcher, summarizer],
+  sharedMemory: true,
+})
+
+const goal = `Check this machine's Node.js version, npm version, and OS info,
+then write a short Markdown summary report to /tmp/gemma4-auto/report.md`
+
+const start2 = Date.now()
+const result2 = await orchestrator2.runTeam(team2, goal)
+
+console.log(`\nSuccess: ${result2.success}  Time: ${((Date.now() - start2) / 1000).toFixed(1)}s`)
+console.log(`Tokens — input: ${result2.totalTokenUsage.input_tokens}, output: ${result2.totalTokenUsage.output_tokens}`)
+
+const coordResult = result2.agentResults.get('coordinator')
+if (coordResult?.success) {
+  console.log('\nFinal synthesis (from local Gemma 4 coordinator):')
+  console.log('-'.repeat(60))
+  console.log(coordResult.output)
+  console.log('-'.repeat(60))
+}
+
+console.log('\nAll processing done locally. $0 API cost.')

package/examples/09-structured-output.ts

@@ -0,0 +1,73 @@
+/**
+ * Example 09 — Structured Output
+ *
+ * Demonstrates `outputSchema` on AgentConfig. The agent's response is
+ * automatically parsed as JSON and validated against a Zod schema.
+ * On validation failure, the framework retries once with error feedback.
+ *
+ * The validated result is available via `result.structured`.
+ *
+ * Run:
+ *   npx tsx examples/09-structured-output.ts
+ *
+ * Prerequisites:
+ *   ANTHROPIC_API_KEY env var must be set.
+ */
+
+import { z } from 'zod'
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Define a Zod schema for the expected output
+// ---------------------------------------------------------------------------
+
+const ReviewAnalysis = z.object({
+  summary: z.string().describe('One-sentence summary of the review'),
+  sentiment: z.enum(['positive', 'negative', 'neutral']),
+  confidence: z.number().min(0).max(1).describe('How confident the analysis is'),
+  keyTopics: z.array(z.string()).describe('Main topics mentioned in the review'),
+})
+
+type ReviewAnalysis = z.infer<typeof ReviewAnalysis>
+
+// ---------------------------------------------------------------------------
+// Agent with outputSchema
+// ---------------------------------------------------------------------------
+
+const analyst: AgentConfig = {
+  name: 'analyst',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You are a product review analyst. Analyze the given review and extract structured insights.',
+  outputSchema: ReviewAnalysis,
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
+
+const reviews = [
+  'This keyboard is amazing! The mechanical switches feel incredible and the RGB lighting is stunning. Build quality is top-notch. Only downside is the price.',
+  'Terrible experience. The product arrived broken, customer support was unhelpful, and the return process took 3 weeks.',
+  'It works fine. Nothing special, nothing bad. Does what it says on the box.',
+]
+
+console.log('Analyzing product reviews with structured output...\n')
+
+for (const review of reviews) {
+  const result = await orchestrator.runAgent(analyst, `Analyze this review: "${review}"`)
+
+  if (result.structured) {
+    const data = result.structured as ReviewAnalysis
+    console.log(`Sentiment: ${data.sentiment} (confidence: ${data.confidence})`)
+    console.log(`Summary:   ${data.summary}`)
+    console.log(`Topics:    ${data.keyTopics.join(', ')}`)
+  } else {
+    console.log(`Validation failed. Raw output: ${result.output.slice(0, 100)}`)
+  }
+
+  console.log(`Tokens:    ${result.tokenUsage.input_tokens} in / ${result.tokenUsage.output_tokens} out`)
+  console.log('---')
+}

package/examples/10-task-retry.ts

@@ -0,0 +1,132 @@
+/**
+ * Example 10 — Task Retry with Exponential Backoff
+ *
+ * Demonstrates `maxRetries`, `retryDelayMs`, and `retryBackoff` on task config.
+ * When a task fails, the framework automatically retries with exponential
+ * backoff. The `onProgress` callback receives `task_retry` events so you can
+ * log retry attempts in real time.
+ *
+ * Scenario: a two-step pipeline where the first task (data fetch) is configured
+ * to retry on failure, and the second task (analysis) depends on it.
+ *
+ * Run:
+ *   npx tsx examples/10-task-retry.ts
+ *
+ * Prerequisites:
+ *   ANTHROPIC_API_KEY env var must be set.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig, OrchestratorEvent } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+
+const fetcher: AgentConfig = {
+  name: 'fetcher',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are a data-fetching agent. When given a topic, produce a short
+JSON summary with 3-5 key facts. Output ONLY valid JSON, no markdown fences.
+Example: {"topic":"...", "facts":["fact1","fact2","fact3"]}`,
+  maxTurns: 2,
+}
+
+const analyst: AgentConfig = {
+  name: 'analyst',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: `You are a data analyst. Read the fetched data from shared memory
+and produce a brief analysis (3-4 sentences) highlighting trends or insights.`,
+  maxTurns: 2,
+}
+
+// ---------------------------------------------------------------------------
+// Progress handler — watch for task_retry events
+// ---------------------------------------------------------------------------
+
+function handleProgress(event: OrchestratorEvent): void {
+  const ts = new Date().toISOString().slice(11, 23)
+
+  switch (event.type) {
+    case 'task_start':
+      console.log(`[${ts}] TASK START    "${event.task}" (agent: ${event.agent})`)
+      break
+    case 'task_complete':
+      console.log(`[${ts}] TASK DONE     "${event.task}"`)
+      break
+    case 'task_retry': {
+      const d = event.data as { attempt: number; maxAttempts: number; error: string; nextDelayMs: number }
+      console.log(`[${ts}] TASK RETRY    "${event.task}" — attempt ${d.attempt}/${d.maxAttempts}, next in ${d.nextDelayMs}ms`)
+      console.log(`               error: ${d.error.slice(0, 120)}`)
+      break
+    }
+    case 'error':
+      console.log(`[${ts}] ERROR         "${event.task}" agent=${event.agent}`)
+      break
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator + team
+// ---------------------------------------------------------------------------
+
+const orchestrator = new OpenMultiAgent({
+  defaultModel: 'claude-sonnet-4-6',
+  onProgress: handleProgress,
+})
+
+const team = orchestrator.createTeam('retry-demo', {
+  name: 'retry-demo',
+  agents: [fetcher, analyst],
+  sharedMemory: true,
+})
+
+// ---------------------------------------------------------------------------
+// Tasks — fetcher has retry config, analyst depends on it
+// ---------------------------------------------------------------------------
+
+const tasks = [
+  {
+    title: 'Fetch data',
+    description: 'Fetch key facts about the adoption of TypeScript in open-source projects as of 2024. Output a JSON object with a "topic" and "facts" array.',
+    assignee: 'fetcher',
+    // Retry config: up to 2 retries, 500ms base delay, 2x backoff (500ms, 1000ms)
+    maxRetries: 2,
+    retryDelayMs: 500,
+    retryBackoff: 2,
+  },
+  {
+    title: 'Analyze data',
+    description: 'Read the fetched data from shared memory and produce a 3-4 sentence analysis of TypeScript adoption trends.',
+    assignee: 'analyst',
+    dependsOn: ['Fetch data'],
+    // No retry — if analysis fails, just report the error
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+console.log('Task Retry Example')
+console.log('='.repeat(60))
+console.log('Pipeline: fetch (with retry) → analyze')
+console.log(`Retry config: maxRetries=2, delay=500ms, backoff=2x`)
+console.log('='.repeat(60))
+console.log()
+
+const result = await orchestrator.runTasks(team, tasks)
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log('\n' + '='.repeat(60))
+console.log(`Overall success: ${result.success}`)
+console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
+
+for (const [name, r] of result.agentResults) {
+  const icon = r.success ? 'OK  ' : 'FAIL'
+  console.log(`  [${icon}] ${name}`)
+  console.log(`         ${r.output.slice(0, 200)}`)
+}