@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

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

@@ -1,209 +0,0 @@
-/**
- * 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

@@ -1,192 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,132 +0,0 @@
-/**
- * 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)}`)
-}