@jackchen_me/open-multi-agent 0.2.0 → 1.0.0

package/examples/08-gemma4-local.ts

@@ -1,15 +1,16 @@
 /**
- * Example 08 — Gemma 4 Local Agent Team (100% Local, Zero API Cost)
+ * Example 08 — Gemma 4 Local (100% Local, Zero API Cost)
  *
- * Demonstrates a fully local multi-agent team using Google's Gemma 4 via
+ * Demonstrates both execution modes with a fully local Gemma 4 model 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
+ * 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 pattern works with any Ollama model that supports tool-calling.
- * Gemma 4 (released 2026-04-02) has native tool-calling support.
+ * 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
@@ -38,46 +39,31 @@ const OLLAMA_BASE_URL = 'http://localhost:11434/v1'
 const OUTPUT_DIR = '/tmp/gemma4-demo'
 
 // ---------------------------------------------------------------------------
-// Agents — both use Gemma 4 locally
+// Agents
 // ---------------------------------------------------------------------------
 
-/**
- * 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.`,
+  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,
 }
 
-/**
- * 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'],
+  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,
 }
 
@@ -85,23 +71,17 @@ Focus on the key highlights: what OS, how much RAM, disk status, and uptime.`,
 // 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`)
+    case 'task_complete':
+      console.log(`[${ts}] TASK DONE     "${event.task}"`)
       break
-    }
     case 'agent_start':
       console.log(`[${ts}] AGENT START   ${event.agent}`)
       break
@@ -114,32 +94,29 @@ function handleProgress(event: OrchestratorEvent): void {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Orchestrator + Team
-// ---------------------------------------------------------------------------
+// ═══════════════════════════════════════════════════════════════════════════
+// Part 1: runTasks() — Explicit task pipeline
+// ═══════════════════════════════════════════════════════════════════════════
 
-const orchestrator = new OpenMultiAgent({
+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, // run agents sequentially — local model can only serve one at a time
+  maxConcurrency: 1, // local model serves one request at a time
   onProgress: handleProgress,
 })
 
-const team = orchestrator.createTeam('gemma4-team', {
-  name: 'gemma4-team',
+const team1 = orchestrator1.createTeam('explicit', {
+  name: 'explicit',
   agents: [researcher, summarizer],
   sharedMemory: true,
 })
 
-// ---------------------------------------------------------------------------
-// Task pipeline: research → summarize
-// ---------------------------------------------------------------------------
-
-const tasks: Array<{
-  title: string
-  description: string
-  assignee?: string
-  dependsOn?: string[]
-}> = [
+const tasks = [
   {
     title: 'Gather system information',
     description: `Use bash to run system info commands (uname -a, sw_vers, sysctl, df -h, uptime).
@@ -156,47 +133,59 @@ Produce a concise one-paragraph executive summary of the system information.`,
   },
 ]
 
-// ---------------------------------------------------------------------------
-// Run
-// ---------------------------------------------------------------------------
+const start1 = Date.now()
+const result1 = await orchestrator1.runTasks(team1, tasks)
 
-console.log('Gemma 4 Local Agent Team — Zero API Cost')
+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(`  model       → ${OLLAMA_MODEL} via Ollama`)
-console.log(`  researcher  → bash + file_write`)
-console.log(`  summarizer  → file_read`)
-console.log(`  output dir  → ${OUTPUT_DIR}`)
+console.log(`  coordinator  → auto-created by runTeam(), also Gemma 4`)
+console.log(`  goal         → given in natural language, framework plans everything`)
 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
+const orchestrator2 = new OpenMultiAgent({
+  defaultModel: OLLAMA_MODEL,
+  defaultProvider: 'openai',
+  defaultBaseURL: OLLAMA_BASE_URL,
+  defaultApiKey: 'ollama',
+  maxConcurrency: 1,
+  onProgress: handleProgress,
+})
 
-// ---------------------------------------------------------------------------
-// Summary
-// ---------------------------------------------------------------------------
+const team2 = orchestrator2.createTeam('auto', {
+  name: 'auto',
+  agents: [researcher, summarizer],
+  sharedMemory: true,
+})
 
-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)'}`)
-}
+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`
 
-// Print the summarizer's output
-const summary = result.agentResults.get('summarizer')
-if (summary?.success) {
-  console.log('\nExecutive Summary (from local Gemma 4):')
+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(summary.output)
+  console.log(coordResult.output)
   console.log('-'.repeat(60))
 }
 

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)}`)
+}

package/examples/11-trace-observability.ts

@@ -0,0 +1,133 @@
+/**
+ * Example 11 — Trace Observability
+ *
+ * Demonstrates the `onTrace` callback for lightweight observability. Every LLM
+ * call, tool execution, task lifecycle, and agent run emits a structured trace
+ * event with timing data and token usage — giving you full visibility into
+ * what's happening inside a multi-agent run.
+ *
+ * Trace events share a `runId` for correlation, so you can reconstruct the
+ * full execution timeline. Pipe them into your own logging, OpenTelemetry, or
+ * dashboard.
+ *
+ * Run:
+ *   npx tsx examples/11-trace-observability.ts
+ *
+ * Prerequisites:
+ *   ANTHROPIC_API_KEY env var must be set.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig, TraceEvent } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+
+const researcher: AgentConfig = {
+  name: 'researcher',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You are a research assistant. Provide concise, factual answers.',
+  maxTurns: 2,
+}
+
+const writer: AgentConfig = {
+  name: 'writer',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You are a technical writer. Summarize research into clear prose.',
+  maxTurns: 2,
+}
+
+// ---------------------------------------------------------------------------
+// Trace handler — log every span with timing
+// ---------------------------------------------------------------------------
+
+function handleTrace(event: TraceEvent): void {
+  const dur = `${event.durationMs}ms`.padStart(7)
+
+  switch (event.type) {
+    case 'llm_call':
+      console.log(
+        `  [LLM]   ${dur}  agent=${event.agent}  model=${event.model}  turn=${event.turn}` +
+        `  tokens=${event.tokens.input_tokens}in/${event.tokens.output_tokens}out`,
+      )
+      break
+    case 'tool_call':
+      console.log(
+        `  [TOOL]  ${dur}  agent=${event.agent}  tool=${event.tool}` +
+        `  error=${event.isError}`,
+      )
+      break
+    case 'task':
+      console.log(
+        `  [TASK]  ${dur}  task="${event.taskTitle}"  agent=${event.agent}` +
+        `  success=${event.success}  retries=${event.retries}`,
+      )
+      break
+    case 'agent':
+      console.log(
+        `  [AGENT] ${dur}  agent=${event.agent}  turns=${event.turns}` +
+        `  tools=${event.toolCalls}  tokens=${event.tokens.input_tokens}in/${event.tokens.output_tokens}out`,
+      )
+      break
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator + team
+// ---------------------------------------------------------------------------
+
+const orchestrator = new OpenMultiAgent({
+  defaultModel: 'claude-sonnet-4-6',
+  onTrace: handleTrace,
+})
+
+const team = orchestrator.createTeam('trace-demo', {
+  name: 'trace-demo',
+  agents: [researcher, writer],
+  sharedMemory: true,
+})
+
+// ---------------------------------------------------------------------------
+// Tasks — researcher first, then writer summarizes
+// ---------------------------------------------------------------------------
+
+const tasks = [
+  {
+    title: 'Research topic',
+    description: 'List 5 key benefits of TypeScript for large codebases. Be concise.',
+    assignee: 'researcher',
+  },
+  {
+    title: 'Write summary',
+    description: 'Read the research from shared memory and write a 3-sentence summary.',
+    assignee: 'writer',
+    dependsOn: ['Research topic'],
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+console.log('Trace Observability Example')
+console.log('='.repeat(60))
+console.log('Pipeline: research → write (with full trace output)')
+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)}`)
+}