@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

package/examples/04-multi-model-team.ts

@@ -1,261 +0,0 @@
-/**
- * Example 04 — Multi-Model Team with Custom Tools
- *
- * Demonstrates:
- * - Mixing Anthropic and OpenAI models in the same team
- * - Defining custom tools with defineTool() and Zod schemas
- * - Building agents with a custom ToolRegistry so they can use custom tools
- * - Running a team goal that uses the custom tools
- *
- * Run:
- *   npx tsx examples/04-multi-model-team.ts
- *
- * Prerequisites:
- *   ANTHROPIC_API_KEY and OPENAI_API_KEY env vars must be set.
- *   (If you only have one key, set useOpenAI = false below.)
- */
-
-import { z } from 'zod'
-import { OpenMultiAgent, defineTool } from '../src/index.js'
-import type { AgentConfig, OrchestratorEvent } from '../src/types.js'
-
-// ---------------------------------------------------------------------------
-// Custom tools — defined with defineTool() + Zod schemas
-// ---------------------------------------------------------------------------
-
-/**
- * A custom tool that fetches live exchange rates from a public API.
- */
-const exchangeRateTool = defineTool({
-  name: 'get_exchange_rate',
-  description:
-    'Get the current exchange rate between two currencies. ' +
-    'Returns the rate as a decimal: 1 unit of `from` = N units of `to`.',
-  inputSchema: z.object({
-    from: z.string().describe('ISO 4217 currency code, e.g. "USD"'),
-    to: z.string().describe('ISO 4217 currency code, e.g. "EUR"'),
-  }),
-  execute: async ({ from, to }) => {
-    try {
-      const url = `https://api.exchangerate.host/convert?from=${from}&to=${to}&amount=1`
-      const resp = await fetch(url, { signal: AbortSignal.timeout(5000) })
-
-      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
-
-      interface ExchangeRateResponse {
-        result?: number
-        info?: { rate?: number }
-      }
-      const json = (await resp.json()) as ExchangeRateResponse
-      const rate: number | undefined = json?.result ?? json?.info?.rate
-
-      if (typeof rate !== 'number') throw new Error('Unexpected API response shape')
-
-      return {
-        data: JSON.stringify({ from, to, rate, timestamp: new Date().toISOString() }),
-        isError: false,
-      }
-    } catch (err) {
-      // Graceful degradation — return a stubbed rate so the team can still proceed
-      const stub = parseFloat((Math.random() * 0.5 + 0.8).toFixed(4))
-      return {
-        data: JSON.stringify({
-          from,
-          to,
-          rate: stub,
-          note: `Live fetch failed (${err instanceof Error ? err.message : String(err)}). Using stub rate.`,
-        }),
-        isError: false,
-      }
-    }
-  },
-})
-
-/**
- * A custom tool that formats a number as a localised currency string.
- */
-const formatCurrencyTool = defineTool({
-  name: 'format_currency',
-  description: 'Format a number as a localised currency string.',
-  inputSchema: z.object({
-    amount: z.number().describe('The numeric amount to format.'),
-    currency: z.string().describe('ISO 4217 currency code, e.g. "USD".'),
-    locale: z
-      .string()
-      .optional()
-      .describe('BCP 47 locale string, e.g. "en-US". Defaults to "en-US".'),
-  }),
-  execute: async ({ amount, currency, locale = 'en-US' }) => {
-    try {
-      const formatted = new Intl.NumberFormat(locale, {
-        style: 'currency',
-        currency,
-      }).format(amount)
-      return { data: formatted, isError: false }
-    } catch {
-      return { data: `${amount} ${currency}`, isError: true }
-    }
-  },
-})
-
-// ---------------------------------------------------------------------------
-// Helper: build an AgentConfig whose tools list includes custom tool names.
-//
-// Agents reference tools by name in their AgentConfig.tools array.
-// The ToolRegistry is injected via the Agent constructor. When using OpenMultiAgent
-// convenience methods (runTeam, runTasks, runAgent), the orchestrator builds
-// agents internally using buildAgent(), which registers only the five built-in
-// tools. For custom tools, use AgentPool + Agent directly (see the note in the
-// README) or provide the custom tool names in the tools array and rely on a
-// registry you inject yourself.
-//
-// In this example we demonstrate the custom-tool pattern by running the agents
-// directly through AgentPool rather than through the OpenMultiAgent high-level API.
-// ---------------------------------------------------------------------------
-
-import { Agent, AgentPool, ToolRegistry, ToolExecutor, registerBuiltInTools } from '../src/index.js'
-
-/**
- * Build an Agent with both built-in and custom tools registered.
- */
-function buildCustomAgent(
-  config: AgentConfig,
-  extraTools: ReturnType<typeof defineTool>[],
-): Agent {
-  const registry = new ToolRegistry()
-  registerBuiltInTools(registry)
-  for (const tool of extraTools) {
-    registry.register(tool)
-  }
-  const executor = new ToolExecutor(registry)
-  return new Agent(config, registry, executor)
-}
-
-// ---------------------------------------------------------------------------
-// Agent definitions — mixed providers
-// ---------------------------------------------------------------------------
-
-const useOpenAI = Boolean(process.env.OPENAI_API_KEY)
-
-const researcherConfig: AgentConfig = {
-  name: 'researcher',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: `You are a financial data researcher.
-Use the get_exchange_rate tool to fetch current rates between the currency pairs you are given.
-Return the raw rates as a JSON object keyed by pair, e.g. { "USD/EUR": 0.91, "USD/GBP": 0.79 }.`,
-  tools: ['get_exchange_rate'],
-  maxTurns: 6,
-  temperature: 0,
-}
-
-const analystConfig: AgentConfig = {
-  name: 'analyst',
-  model: useOpenAI ? 'gpt-5.4' : 'claude-sonnet-4-6',
-  provider: useOpenAI ? 'openai' : 'anthropic',
-  systemPrompt: `You are a foreign exchange analyst.
-You receive exchange rate data and produce a short briefing.
-Use format_currency to show example conversions.
-Keep the briefing under 200 words.`,
-  tools: ['format_currency'],
-  maxTurns: 4,
-  temperature: 0.3,
-}
-
-// ---------------------------------------------------------------------------
-// Build agents with custom tools
-// ---------------------------------------------------------------------------
-
-const researcher = buildCustomAgent(researcherConfig, [exchangeRateTool])
-const analyst = buildCustomAgent(analystConfig, [formatCurrencyTool])
-
-// ---------------------------------------------------------------------------
-// Run with AgentPool for concurrency control
-// ---------------------------------------------------------------------------
-
-console.log('Multi-model team with custom tools')
-console.log(`Providers: researcher=anthropic, analyst=${useOpenAI ? 'openai (gpt-5.4)' : 'anthropic (fallback)'}`)
-console.log('Custom tools:', [exchangeRateTool.name, formatCurrencyTool.name].join(', '))
-console.log()
-
-const pool = new AgentPool(1) // sequential for readability
-pool.add(researcher)
-pool.add(analyst)
-
-// Step 1: researcher fetches the rates
-console.log('[1/2] Researcher fetching FX rates...')
-const researchResult = await pool.run(
-  'researcher',
-  `Fetch exchange rates for these pairs using the get_exchange_rate tool:
-- USD to EUR
-- USD to GBP
-- USD to JPY
-- EUR to GBP
-
-Return the results as a JSON object: { "USD/EUR": <rate>, "USD/GBP": <rate>, ... }`,
-)
-
-if (!researchResult.success) {
-  console.error('Researcher failed:', researchResult.output)
-  process.exit(1)
-}
-
-console.log('Researcher done. Tool calls made:', researchResult.toolCalls.map(c => c.toolName).join(', '))
-
-// Step 2: analyst writes the briefing, receiving the researcher output as context
-console.log('\n[2/2] Analyst writing FX briefing...')
-const analystResult = await pool.run(
-  'analyst',
-  `Here are the current FX rates gathered by the research team:
-
-${researchResult.output}
-
-Using format_currency, show what $1,000 USD and €1,000 EUR convert to in each of the other currencies.
-Then write a short FX market briefing (under 200 words) covering:
-- Each rate with a brief observation
-- The strongest and weakest currency in the set
-- One-sentence market comment`,
-)
-
-if (!analystResult.success) {
-  console.error('Analyst failed:', analystResult.output)
-  process.exit(1)
-}
-
-console.log('Analyst done. Tool calls made:', analystResult.toolCalls.map(c => c.toolName).join(', '))
-
-// ---------------------------------------------------------------------------
-// Results
-// ---------------------------------------------------------------------------
-
-console.log('\n' + '='.repeat(60))
-
-console.log('\nResearcher output:')
-console.log(researchResult.output.slice(0, 400))
-
-console.log('\nAnalyst briefing:')
-console.log('─'.repeat(60))
-console.log(analystResult.output)
-console.log('─'.repeat(60))
-
-const totalInput = researchResult.tokenUsage.input_tokens + analystResult.tokenUsage.input_tokens
-const totalOutput = researchResult.tokenUsage.output_tokens + analystResult.tokenUsage.output_tokens
-console.log(`\nTotal tokens — input: ${totalInput}, output: ${totalOutput}`)
-
-// ---------------------------------------------------------------------------
-// Bonus: show how defineTool() works in isolation (no LLM needed)
-// ---------------------------------------------------------------------------
-
-console.log('\n--- Bonus: testing custom tools in isolation ---\n')
-
-const fmtResult = await formatCurrencyTool.execute(
-  { amount: 1234.56, currency: 'EUR', locale: 'de-DE' },
-  { agent: { name: 'test', role: 'test', model: 'test' } },
-)
-console.log(`format_currency(1234.56, EUR, de-DE) = ${fmtResult.data}`)
-
-const rateResult = await exchangeRateTool.execute(
-  { from: 'USD', to: 'EUR' },
-  { agent: { name: 'test', role: 'test', model: 'test' } },
-)
-console.log(`get_exchange_rate(USD→EUR) = ${rateResult.data}`)

package/examples/05-copilot-test.ts

@@ -1,49 +0,0 @@
-/**
- * Quick smoke test for the Copilot adapter.
- *
- * Run:
- *   npx tsx examples/05-copilot-test.ts
- *
- * If GITHUB_COPILOT_TOKEN is not set, the adapter will start an interactive
- * OAuth2 device flow — you'll be prompted to sign in via your browser.
- */
-
-import { OpenMultiAgent } from '../src/index.js'
-import type { OrchestratorEvent } from '../src/types.js'
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: 'gpt-4o',
-  defaultProvider: 'copilot',
-  onProgress: (event: OrchestratorEvent) => {
-    if (event.type === 'agent_start') {
-      console.log(`[start]    agent=${event.agent}`)
-    } else if (event.type === 'agent_complete') {
-      console.log(`[complete] agent=${event.agent}`)
-    }
-  },
-})
-
-console.log('Testing Copilot adapter with gpt-4o...\n')
-
-const result = await orchestrator.runAgent(
-  {
-    name: 'assistant',
-    model: 'gpt-4o',
-    provider: 'copilot',
-    systemPrompt: 'You are a helpful assistant. Keep answers brief.',
-    maxTurns: 1,
-    maxTokens: 256,
-  },
-  'What is 2 + 2? Reply in one sentence.',
-)
-
-if (result.success) {
-  console.log('\nAgent output:')
-  console.log('─'.repeat(60))
-  console.log(result.output)
-  console.log('─'.repeat(60))
-  console.log(`\nTokens: input=${result.tokenUsage.input_tokens}, output=${result.tokenUsage.output_tokens}`)
-} else {
-  console.error('Agent failed:', result.output)
-  process.exit(1)
-}

package/examples/06-local-model.ts

@@ -1,200 +0,0 @@
-/**
- * Example 06 — Local Model + Cloud Model Team (Ollama + Claude)
- *
- * Demonstrates mixing a local model served by Ollama with a cloud model
- * (Claude) in the same task pipeline. The key technique is using
- * `provider: 'openai'` with a custom `baseURL` pointing at Ollama's
- * OpenAI-compatible endpoint.
- *
- * This pattern works with ANY OpenAI-compatible local server:
- * - Ollama        → http://localhost:11434/v1
- * - vLLM          → http://localhost:8000/v1
- * - LM Studio     → http://localhost:1234/v1
- * - llama.cpp     → http://localhost:8080/v1
- * Just change the baseURL and model name below.
- *
- * Run:
- *   npx tsx examples/06-local-model.ts
- *
- * Prerequisites:
- *   1. Ollama installed and running: https://ollama.com
- *   2. Pull the model: ollama pull llama3.1
- *   3. ANTHROPIC_API_KEY env var must be set.
- */
-
-import { OpenMultiAgent } from '../src/index.js'
-import type { AgentConfig, OrchestratorEvent, Task } from '../src/types.js'
-
-// ---------------------------------------------------------------------------
-// Agents
-// ---------------------------------------------------------------------------
-
-/**
- * Coder — uses Claude (Anthropic) for high-quality code generation.
- */
-const coder: AgentConfig = {
-  name: 'coder',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: `You are a senior TypeScript developer. Write clean, well-typed,
-production-quality code. Use the tools to write files to /tmp/local-model-demo/.
-Always include brief JSDoc comments on exported functions.`,
-  tools: ['bash', 'file_write'],
-  maxTurns: 6,
-}
-
-/**
- * Reviewer — uses a local Ollama model via the OpenAI-compatible API.
- * The apiKey is required by the OpenAI SDK but Ollama ignores it,
- * so we pass the placeholder string 'ollama'.
- */
-const reviewer: AgentConfig = {
-  name: 'reviewer',
-  model: 'llama3.1',
-  provider: 'openai', // 'openai' here means "OpenAI-compatible protocol", not the OpenAI cloud
-  baseURL: 'http://localhost:11434/v1',
-  apiKey: 'ollama',
-  systemPrompt: `You are a code reviewer. You read source files and produce a structured review.
-Your review MUST include these sections:
-- Summary (2-3 sentences)
-- Strengths (bullet list)
-- Issues (bullet list — or "None found" if the code is clean)
-- Verdict: SHIP or NEEDS WORK
-
-Be specific and constructive. Reference line numbers or function names when possible.`,
-  tools: ['file_read'],
-  maxTurns: 4,
-  timeoutMs: 120_000, // 2 min — local models can be slow
-}
-
-// ---------------------------------------------------------------------------
-// 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 READY    "${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     task=${event.task} in ${elapsed}ms`)
-      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: 'claude-sonnet-4-6',
-  maxConcurrency: 2,
-  onProgress: handleProgress,
-})
-
-const team = orchestrator.createTeam('local-cloud-team', {
-  name: 'local-cloud-team',
-  agents: [coder, reviewer],
-  sharedMemory: true,
-})
-
-// ---------------------------------------------------------------------------
-// Task pipeline: code → review
-// ---------------------------------------------------------------------------
-
-const OUTPUT_DIR = '/tmp/local-model-demo'
-
-const tasks: Array<{
-  title: string
-  description: string
-  assignee?: string
-  dependsOn?: string[]
-}> = [
-  {
-    title: 'Write: retry utility',
-    description: `Write a small but complete TypeScript utility to ${OUTPUT_DIR}/retry.ts.
-
-The module should export:
-1. A \`RetryOptions\` interface with: maxRetries (number), delayMs (number),
-   backoffFactor (optional number, default 2), shouldRetry (optional predicate
-   taking the error and returning boolean).
-2. An async \`retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>\`
-   function that retries \`fn\` with exponential backoff.
-3. A convenience \`withRetry\` wrapper that returns a new function with retry
-   behaviour baked in.
-
-Include JSDoc comments. No external dependencies — use only Node built-ins.
-After writing the file, also create a small test script at ${OUTPUT_DIR}/retry-test.ts
-that exercises the happy path and a failure case, then run it with \`npx tsx\`.`,
-    assignee: 'coder',
-  },
-  {
-    title: 'Review: retry utility',
-    description: `Read the files at ${OUTPUT_DIR}/retry.ts and ${OUTPUT_DIR}/retry-test.ts.
-
-Produce a structured code review covering:
-- Summary (2-3 sentences describing the module)
-- Strengths (bullet list)
-- Issues (bullet list — be specific about what and why)
-- Verdict: SHIP or NEEDS WORK`,
-    assignee: 'reviewer',
-    dependsOn: ['Write: retry utility'],
-  },
-]
-
-// ---------------------------------------------------------------------------
-// Run
-// ---------------------------------------------------------------------------
-
-console.log('Local + Cloud model team')
-console.log(`  coder    → Claude (${coder.model}) via Anthropic API`)
-console.log(`  reviewer → Ollama (${reviewer.model}) at ${reviewer.baseURL}`)
-console.log()
-console.log('Pipeline: coder writes code → local model reviews it')
-console.log('='.repeat(60))
-
-const result = await orchestrator.runTasks(team, tasks)
-
-// ---------------------------------------------------------------------------
-// Summary
-// ---------------------------------------------------------------------------
-
-console.log('\n' + '='.repeat(60))
-console.log('Pipeline complete.\n')
-console.log(`Overall success: ${result.success}`)
-console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
-
-console.log('\nPer-agent summary:')
-for (const [name, r] of result.agentResults) {
-  const icon = r.success ? 'OK  ' : 'FAIL'
-  const provider = name === 'coder' ? 'anthropic' : 'ollama (local)'
-  const tools = r.toolCalls.map(c => c.toolName).join(', ')
-  console.log(`  [${icon}] ${name.padEnd(10)} (${provider.padEnd(16)})  tools: ${tools || '(none)'}`)
-}
-
-// Print the reviewer's output
-const review = result.agentResults.get('reviewer')
-if (review?.success) {
-  console.log('\nCode review (from local model):')
-  console.log('─'.repeat(60))
-  console.log(review.output)
-  console.log('─'.repeat(60))
-}