@jackchen_me/open-multi-agent 0.2.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,203 +0,0 @@
-/**
- * Example 08 — Gemma 4 Local Agent Team (100% Local, Zero API Cost)
- *
- * Demonstrates a fully local multi-agent team using Google's Gemma 4 via
- * Ollama. No cloud API keys needed — everything runs on your machine.
- *
- * Two agents collaborate through a task pipeline:
- * - researcher: uses bash + file_write to gather system info and write a report
- * - summarizer: uses file_read to read the report and produce a concise summary
- *
- * This pattern works with any Ollama model that supports tool-calling.
- * Gemma 4 (released 2026-04-02) has native tool-calling support.
- *
- * 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 — both use Gemma 4 locally
-// ---------------------------------------------------------------------------
-
-/**
- * Researcher — gathers system information using shell commands.
- */
-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. Your job is to gather information
-about the current machine using shell commands and write a structured report.
-
-Use the bash tool to run commands like: uname -a, df -h, uptime, and similar
-non-destructive read-only commands.
-On macOS you can also use: sw_vers, sysctl -n hw.memsize.
-On Linux you can also use: cat /etc/os-release, free -h.
-
-Then use file_write to save a Markdown report to ${OUTPUT_DIR}/system-report.md.
-The report should have sections: OS, Hardware, Disk, and Uptime.
-Be concise — one or two lines per section is enough.`,
-  tools: ['bash', 'file_write'],
-  maxTurns: 8,
-}
-
-/**
- * Summarizer — reads the report and writes a one-paragraph executive summary.
- */
-const summarizer: AgentConfig = {
-  name: 'summarizer',
-  model: OLLAMA_MODEL,
-  provider: 'openai',
-  baseURL: OLLAMA_BASE_URL,
-  apiKey: 'ollama',
-  systemPrompt: `You are a technical writer. Read the system report file provided,
-then produce a concise one-paragraph executive summary (3-5 sentences).
-Focus on the key highlights: what OS, how much RAM, disk status, and uptime.`,
-  tools: ['file_read'],
-  maxTurns: 4,
-}
-
-// ---------------------------------------------------------------------------
-// Progress handler
-// ---------------------------------------------------------------------------
-
-const taskTimes = new Map<string, number>()
-
-function handleProgress(event: OrchestratorEvent): void {
-  const ts = new Date().toISOString().slice(11, 23)
-
-  switch (event.type) {
-    case 'task_start': {
-      taskTimes.set(event.task ?? '', Date.now())
-      const task = event.data as Task | undefined
-      console.log(`[${ts}] TASK START    "${task?.title ?? event.task}" → ${task?.assignee ?? '?'}`)
-      break
-    }
-    case 'task_complete': {
-      const elapsed = Date.now() - (taskTimes.get(event.task ?? '') ?? Date.now())
-      console.log(`[${ts}] TASK DONE     "${event.task}" in ${(elapsed / 1000).toFixed(1)}s`)
-      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
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Orchestrator + Team
-// ---------------------------------------------------------------------------
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: OLLAMA_MODEL,
-  maxConcurrency: 1, // run agents sequentially — local model can only serve one at a time
-  onProgress: handleProgress,
-})
-
-const team = orchestrator.createTeam('gemma4-team', {
-  name: 'gemma4-team',
-  agents: [researcher, summarizer],
-  sharedMemory: true,
-})
-
-// ---------------------------------------------------------------------------
-// Task pipeline: research → summarize
-// ---------------------------------------------------------------------------
-
-const tasks: Array<{
-  title: string
-  description: string
-  assignee?: string
-  dependsOn?: string[]
-}> = [
-  {
-    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'],
-  },
-]
-
-// ---------------------------------------------------------------------------
-// Run
-// ---------------------------------------------------------------------------
-
-console.log('Gemma 4 Local Agent Team — Zero API Cost')
-console.log('='.repeat(60))
-console.log(`  model       → ${OLLAMA_MODEL} via Ollama`)
-console.log(`  researcher  → bash + file_write`)
-console.log(`  summarizer  → file_read`)
-console.log(`  output dir  → ${OUTPUT_DIR}`)
-console.log()
-console.log('Pipeline: researcher gathers info → summarizer writes summary')
-console.log('='.repeat(60))
-
-const start = Date.now()
-const result = await orchestrator.runTasks(team, tasks)
-const totalTime = Date.now() - start
-
-// ---------------------------------------------------------------------------
-// Summary
-// ---------------------------------------------------------------------------
-
-console.log('\n' + '='.repeat(60))
-console.log('Pipeline complete.\n')
-console.log(`Overall success: ${result.success}`)
-console.log(`Total time: ${(totalTime / 1000).toFixed(1)}s`)
-console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
-
-console.log('\nPer-agent results:')
-for (const [name, r] of result.agentResults) {
-  const icon = r.success ? 'OK  ' : 'FAIL'
-  const tools = r.toolCalls.map(c => c.toolName).join(', ')
-  console.log(`  [${icon}] ${name.padEnd(12)} tools: ${tools || '(none)'}`)
-}
-
-// Print the summarizer's output
-const summary = result.agentResults.get('summarizer')
-if (summary?.success) {
-  console.log('\nExecutive Summary (from local Gemma 4):')
-  console.log('-'.repeat(60))
-  console.log(summary.output)
-  console.log('-'.repeat(60))
-}
-
-console.log('\nAll processing done locally. $0 API cost.')

package/examples/09-gemma4-auto-orchestration.ts

@@ -1,162 +0,0 @@
-/**
- * Example 09 — Gemma 4 Auto-Orchestration (runTeam, 100% Local)
- *
- * Demonstrates the framework's key feature — automatic task decomposition —
- * powered entirely by a local Gemma 4 model. No cloud API needed.
- *
- * What happens:
- * 1. A Gemma 4 "coordinator" receives the goal + agent roster
- * 2. It outputs a structured JSON task array (title, description, assignee, dependsOn)
- * 3. The framework resolves dependencies, schedules tasks, and runs agents
- * 4. The coordinator synthesises all task results into a final answer
- *
- * This is the hardest test for a local model — it must produce valid JSON
- * for task decomposition AND do tool-calling for actual task execution.
- * Gemma 4 e2b (5.1B params) handles both reliably.
- *
- * Run:
- *   no_proxy=localhost npx tsx examples/09-gemma4-auto-orchestration.ts
- *
- * Prerequisites:
- *   1. Ollama >= 0.20.0 installed and running: https://ollama.com
- *   2. Pull the model: ollama pull gemma4:e2b
- *   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
-// ---------------------------------------------------------------------------
-
-// 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'
-
-// ---------------------------------------------------------------------------
-// Agents — the coordinator is created automatically by runTeam()
-// ---------------------------------------------------------------------------
-
-const researcher: AgentConfig = {
-  name: 'researcher',
-  model: OLLAMA_MODEL,
-  provider: 'openai',
-  baseURL: OLLAMA_BASE_URL,
-  apiKey: 'ollama',
-  systemPrompt: `You are a system researcher. Use bash to run non-destructive,
-read-only commands and report the results concisely.`,
-  tools: ['bash'],
-  maxTurns: 4,
-}
-
-const writer: AgentConfig = {
-  name: 'writer',
-  model: OLLAMA_MODEL,
-  provider: 'openai',
-  baseURL: OLLAMA_BASE_URL,
-  apiKey: 'ollama',
-  systemPrompt: `You are a technical writer. Use file_write to create clear,
-structured Markdown reports based on the information provided.`,
-  tools: ['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
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Orchestrator — defaultModel is used for the coordinator agent
-// ---------------------------------------------------------------------------
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: OLLAMA_MODEL,
-  defaultProvider: 'openai',
-  defaultBaseURL: OLLAMA_BASE_URL,
-  defaultApiKey: 'ollama',
-  maxConcurrency: 1, // local model serves one request at a time
-  onProgress: handleProgress,
-})
-
-const team = orchestrator.createTeam('gemma4-auto', {
-  name: 'gemma4-auto',
-  agents: [researcher, writer],
-  sharedMemory: true,
-})
-
-// ---------------------------------------------------------------------------
-// Give a goal — the framework handles the rest
-// ---------------------------------------------------------------------------
-
-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`
-
-console.log('Gemma 4 Auto-Orchestration — Zero API Cost')
-console.log('='.repeat(60))
-console.log(`  model        → ${OLLAMA_MODEL} via Ollama (all agents + coordinator)`)
-console.log(`  researcher   → bash`)
-console.log(`  writer       → file_write`)
-console.log(`  coordinator  → auto-created by runTeam()`)
-console.log()
-console.log(`Goal: ${goal.replace(/\n/g, ' ').trim()}`)
-console.log('='.repeat(60))
-
-const start = Date.now()
-const result = await orchestrator.runTeam(team, goal)
-const totalTime = Date.now() - start
-
-// ---------------------------------------------------------------------------
-// Results
-// ---------------------------------------------------------------------------
-
-console.log('\n' + '='.repeat(60))
-console.log('Pipeline complete.\n')
-console.log(`Overall success: ${result.success}`)
-console.log(`Total time: ${(totalTime / 1000).toFixed(1)}s`)
-console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
-
-console.log('\nPer-agent results:')
-for (const [name, r] of result.agentResults) {
-  const icon = r.success ? 'OK  ' : 'FAIL'
-  const tools = r.toolCalls.length > 0 ? r.toolCalls.map(c => c.toolName).join(', ') : '(none)'
-  console.log(`  [${icon}] ${name.padEnd(24)} tools: ${tools}`)
-}
-
-// Print the coordinator's final synthesis
-const coordResult = result.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.')