ai-functions 2.1.1 → 2.3.0

package/examples/02-multi-agent-research.ts

@@ -0,0 +1,290 @@
+/**
+ * Multi-Agent Research Workflow Example
+ *
+ * This example demonstrates a multi-agent research workflow where different
+ * specialized agents collaborate to research a topic. It shows how to:
+ * - Define specialized agents with different roles
+ * - Coordinate agent interactions
+ * - Aggregate and synthesize results
+ * - Use tool orchestration for complex workflows
+ *
+ * @example
+ * ```bash
+ * ANTHROPIC_API_KEY=sk-... npx tsx examples/02-multi-agent-research.ts
+ * ```
+ */
+
+import {
+  ai,
+  write,
+  list,
+  is,
+  configure,
+  AgenticLoop,
+  createTool,
+  createToolset,
+  type Tool,
+} from '../src/index.js'
+import { z } from 'zod'
+
+// ============================================================================
+// Agent Definitions
+// ============================================================================
+
+interface AgentResult {
+  agent: string
+  findings: string[]
+  confidence: number
+}
+
+/**
+ * Research Planner Agent - Creates a research plan
+ */
+async function plannerAgent(topic: string): Promise<string[]> {
+  console.log('\n[Planner Agent] Creating research plan...')
+
+  const questions = await list`5 key research questions to thoroughly investigate: "${topic}"
+
+Consider:
+- Background and context
+- Current state and trends
+- Key players and stakeholders
+- Challenges and opportunities
+- Future implications`
+
+  console.log('[Planner Agent] Research questions:')
+  questions.forEach((q, i) => console.log(`  ${i + 1}. ${q}`))
+
+  return questions
+}
+
+/**
+ * Fact Finder Agent - Gathers factual information
+ */
+async function factFinderAgent(question: string): Promise<AgentResult> {
+  console.log(`\n[Fact Finder] Researching: ${question.substring(0, 50)}...`)
+
+  const { facts, sources, confidence } =
+    await ai`Research this question and provide factual information:
+"${question}"
+
+Provide your response with:
+- facts: array of factual findings (3-5 key facts)
+- sources: where this information typically comes from
+- confidence: your confidence level 0-1 in these facts`
+
+  const result: AgentResult = {
+    agent: 'FactFinder',
+    findings: facts as string[],
+    confidence: (confidence as number) || 0.7,
+  }
+
+  console.log(
+    `[Fact Finder] Found ${result.findings.length} facts (confidence: ${result.confidence})`
+  )
+  return result
+}
+
+/**
+ * Critical Analyst Agent - Analyzes and critiques
+ */
+async function analystAgent(findings: string[]): Promise<AgentResult> {
+  console.log('\n[Analyst Agent] Analyzing findings...')
+
+  const { analysis, gaps, confidence } = await ai`Critically analyze these research findings:
+${findings.map((f, i) => `${i + 1}. ${f}`).join('\n')}
+
+Provide:
+- analysis: array of analytical insights (3-4 insights)
+- gaps: any gaps or areas needing more research
+- confidence: confidence in the analysis 0-1`
+
+  const result: AgentResult = {
+    agent: 'Analyst',
+    findings: analysis as string[],
+    confidence: (confidence as number) || 0.6,
+  }
+
+  console.log(`[Analyst Agent] Generated ${result.findings.length} insights`)
+  return result
+}
+
+/**
+ * Synthesizer Agent - Creates final summary
+ */
+async function synthesizerAgent(allResults: AgentResult[]): Promise<string> {
+  console.log('\n[Synthesizer Agent] Creating final synthesis...')
+
+  const allFindings = allResults.flatMap((r) => r.findings)
+
+  const synthesis = await write`Create a comprehensive research summary from these findings:
+
+${allFindings.map((f, i) => `- ${f}`).join('\n')}
+
+Structure the summary with:
+1. Executive Summary (2-3 sentences)
+2. Key Findings (bullet points)
+3. Analysis & Insights
+4. Recommendations
+5. Areas for Further Research`
+
+  return synthesis
+}
+
+// ============================================================================
+// Coordinator - Orchestrates the Multi-Agent Workflow
+// ============================================================================
+
+class ResearchCoordinator {
+  private topic: string
+  private results: AgentResult[] = []
+
+  constructor(topic: string) {
+    this.topic = topic
+  }
+
+  async run(): Promise<string> {
+    console.log(`\n${'='.repeat(60)}`)
+    console.log(`Research Topic: ${this.topic}`)
+    console.log('='.repeat(60))
+
+    // Phase 1: Planning
+    const questions = await plannerAgent(this.topic)
+
+    // Phase 2: Parallel Research
+    console.log('\n[Coordinator] Starting parallel research phase...')
+    const researchPromises = questions.slice(0, 3).map((q) => factFinderAgent(q))
+    const researchResults = await Promise.all(researchPromises)
+    this.results.push(...researchResults)
+
+    // Phase 3: Analysis
+    const allFacts = researchResults.flatMap((r) => r.findings)
+    const analysisResult = await analystAgent(allFacts)
+    this.results.push(analysisResult)
+
+    // Phase 4: Synthesis
+    const finalReport = await synthesizerAgent(this.results)
+
+    // Phase 5: Quality Check
+    const isQualityOk =
+      await is`This research summary is well-structured and comprehensive: "${finalReport.substring(
+        0,
+        200
+      )}..."`
+
+    if (!isQualityOk) {
+      console.log('[Coordinator] Quality check failed, requesting revision...')
+      // In production, you might iterate on the summary
+    }
+
+    return finalReport
+  }
+
+  getResults(): AgentResult[] {
+    return this.results
+  }
+}
+
+// ============================================================================
+// Tool-Based Research Agent (Alternative Approach)
+// ============================================================================
+
+const searchTool = createTool({
+  name: 'search',
+  description: 'Search for information on a topic',
+  parameters: {
+    query: z.string().describe('Search query'),
+  },
+  execute: async ({ query }) => {
+    // Simulate search results
+    console.log(`  [Tool] Searching: ${query}`)
+    return {
+      results: [
+        `Result 1 for "${query}": Found relevant information...`,
+        `Result 2 for "${query}": Additional context...`,
+      ],
+    }
+  },
+})
+
+const analyzeTool = createTool({
+  name: 'analyze',
+  description: 'Analyze and synthesize information',
+  parameters: {
+    data: z.string().describe('Data to analyze'),
+    perspective: z.string().describe('Analysis perspective'),
+  },
+  execute: async ({ data, perspective }) => {
+    console.log(`  [Tool] Analyzing from ${perspective} perspective...`)
+    return {
+      analysis: `Analysis of "${data.substring(
+        0,
+        30
+      )}..." from ${perspective} perspective: Key insights identified.`,
+    }
+  },
+})
+
+async function toolBasedResearch(topic: string): Promise<void> {
+  console.log('\n--- Tool-Based Research Agent ---')
+
+  const loop = new AgenticLoop({
+    tools: createToolset(searchTool, analyzeTool),
+    maxSteps: 5,
+    onStep: (step) => {
+      console.log(`[Step ${step.stepNumber}] Tool calls: ${step.toolCalls.length}`)
+    },
+  })
+
+  // This requires a model that supports tool calling
+  // For demonstration, we'll skip the actual execution
+  console.log('Tool-based agent configured with:', loop.getToolsForSDK())
+}
+
+// ============================================================================
+// Main Example
+// ============================================================================
+
+async function main() {
+  console.log('\n=== Multi-Agent Research Workflow ===\n')
+
+  // Configure the AI provider
+  configure({
+    model: 'sonnet',
+    provider: 'anthropic',
+  })
+
+  // Run the research workflow
+  const coordinator = new ResearchCoordinator(
+    'The impact of Large Language Models on software development practices'
+  )
+
+  const report = await coordinator.run()
+
+  console.log('\n' + '='.repeat(60))
+  console.log('FINAL RESEARCH REPORT')
+  console.log('='.repeat(60))
+  console.log(report)
+
+  // Show agent statistics
+  console.log('\n--- Agent Statistics ---')
+  const results = coordinator.getResults()
+  for (const result of results) {
+    console.log(
+      `${result.agent}: ${result.findings.length} findings (confidence: ${result.confidence})`
+    )
+  }
+
+  // Demonstrate tool-based approach
+  await toolBasedResearch('AI in healthcare')
+}
+
+main()
+  .then(() => {
+    console.log('\n=== Example Complete ===\n')
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error('\nError:', error.message)
+    process.exit(1)
+  })

package/examples/03-email-classification.ts

@@ -0,0 +1,379 @@
+/**
+ * Email Classification and Routing Example
+ *
+ * This example demonstrates building an email classification and routing system
+ * using ai-functions. It shows how to:
+ * - Classify emails into categories
+ * - Extract key information from emails
+ * - Route to appropriate handlers
+ * - Handle priority and urgency
+ *
+ * @example
+ * ```bash
+ * ANTHROPIC_API_KEY=sk-... npx tsx examples/03-email-classification.ts
+ * ```
+ */
+
+import { ai, is, list, extract, configure, decide } from '../src/index.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Email {
+  id: string
+  from: string
+  to: string
+  subject: string
+  body: string
+  timestamp: Date
+}
+
+interface ClassificationResult {
+  category: string
+  subcategory: string
+  priority: 'low' | 'medium' | 'high' | 'urgent'
+  sentiment: 'positive' | 'neutral' | 'negative'
+  requiresResponse: boolean
+  suggestedTeam: string
+}
+
+interface ExtractedInfo {
+  senderIntent: string
+  keyEntities: string[]
+  actionItems: string[]
+  deadlines: string[]
+  attachmentReferences: string[]
+}
+
+interface RoutingDecision {
+  team: string
+  handler: string
+  autoResponse: boolean
+  escalate: boolean
+  suggestedResponse?: string
+}
+
+// ============================================================================
+// Sample Emails
+// ============================================================================
+
+const sampleEmails: Email[] = [
+  {
+    id: 'email-1',
+    from: 'john.smith@bigcorp.com',
+    to: 'sales@ourcompany.com',
+    subject: 'Enterprise License Inquiry - 500 seats',
+    body: `Hi,
+
+We are interested in your enterprise solution for our organization.
+We have approximately 500 developers who would need access.
+
+Could you please provide:
+1. Enterprise pricing for 500 seats
+2. Volume discount options
+3. Security compliance certifications (SOC2, HIPAA)
+4. On-premise deployment options
+
+We're looking to make a decision within the next 2 weeks.
+
+Best regards,
+John Smith
+VP of Engineering, BigCorp Inc.`,
+    timestamp: new Date(),
+  },
+  {
+    id: 'email-2',
+    from: 'frustrated.user@example.com',
+    to: 'support@ourcompany.com',
+    subject: 'URGENT: System down - Production blocked!',
+    body: `Our production system has been down for 3 hours!!!
+
+Error: "Connection timeout to API endpoint"
+
+We're losing thousands of dollars per hour. We need immediate assistance.
+Our contract includes 24/7 premium support.
+
+Account ID: ENT-12345
+Contact: 555-123-4567
+
+This needs to be fixed NOW.`,
+    timestamp: new Date(),
+  },
+  {
+    id: 'email-3',
+    from: 'newsletter@techblog.com',
+    to: 'team@ourcompany.com',
+    subject: 'Weekly AI Newsletter - Top Stories',
+    body: `This week in AI:
+
+- GPT-5 rumors continue to swirl
+- New open-source models released
+- Industry adoption trends
+
+Click to read more...
+
+Unsubscribe: techblog.com/unsubscribe`,
+    timestamp: new Date(),
+  },
+  {
+    id: 'email-4',
+    from: 'hr@ourcompany.com',
+    to: 'team@ourcompany.com',
+    subject: 'Company All-Hands Meeting - Friday 3pm',
+    body: `Hi everyone,
+
+Reminder: Our monthly all-hands meeting is this Friday at 3pm.
+
+Agenda:
+- Q4 Results Review
+- 2025 Planning
+- Team Awards
+
+Please submit any questions beforehand.
+
+Best,
+HR Team`,
+    timestamp: new Date(),
+  },
+]
+
+// ============================================================================
+// Email Classifier
+// ============================================================================
+
+async function classifyEmail(email: Email): Promise<ClassificationResult> {
+  console.log(`\nClassifying: "${email.subject}"`)
+
+  const { category, subcategory, priority, sentiment, requiresResponse, suggestedTeam } =
+    await ai`Classify this email:
+
+From: ${email.from}
+Subject: ${email.subject}
+Body: ${email.body}
+
+Provide:
+- category: one of [sales, support, marketing, internal, spam, other]
+- subcategory: more specific classification
+- priority: one of [low, medium, high, urgent]
+- sentiment: one of [positive, neutral, negative]
+- requiresResponse: boolean - does this need a reply?
+- suggestedTeam: which team should handle this`
+
+  return {
+    category: category as string,
+    subcategory: subcategory as string,
+    priority: priority as 'low' | 'medium' | 'high' | 'urgent',
+    sentiment: sentiment as 'positive' | 'neutral' | 'negative',
+    requiresResponse: requiresResponse as boolean,
+    suggestedTeam: suggestedTeam as string,
+  }
+}
+
+// ============================================================================
+// Information Extractor
+// ============================================================================
+
+async function extractInfo(email: Email): Promise<ExtractedInfo> {
+  console.log(`  Extracting key information...`)
+
+  const { senderIntent, keyEntities, actionItems, deadlines, attachmentReferences } =
+    await ai`Extract key information from this email:
+
+Subject: ${email.subject}
+Body: ${email.body}
+
+Provide:
+- senderIntent: what the sender wants (1 sentence)
+- keyEntities: array of important entities (names, companies, products, account IDs)
+- actionItems: array of action items or requests
+- deadlines: array of mentioned deadlines or timeframes
+- attachmentReferences: any references to attachments or documents`
+
+  return {
+    senderIntent: senderIntent as string,
+    keyEntities: keyEntities as string[],
+    actionItems: actionItems as string[],
+    deadlines: deadlines as string[],
+    attachmentReferences: attachmentReferences as string[],
+  }
+}
+
+// ============================================================================
+// Router
+// ============================================================================
+
+async function routeEmail(
+  email: Email,
+  classification: ClassificationResult,
+  info: ExtractedInfo
+): Promise<RoutingDecision> {
+  console.log(`  Determining routing...`)
+
+  // Check if escalation is needed
+  const needsEscalation = await is`This email requires immediate escalation to management:
+Category: ${classification.category}
+Priority: ${classification.priority}
+Sentiment: ${classification.sentiment}
+Intent: ${info.senderIntent}`
+
+  // Determine if auto-response is appropriate
+  const canAutoRespond = await is`This email can be handled with an automated response:
+Category: ${classification.category}
+Intent: ${info.senderIntent}
+Action Items: ${info.actionItems.join(', ')}`
+
+  // Route based on category
+  const routingMap: Record<string, { team: string; handler: string }> = {
+    sales: { team: 'Sales', handler: 'sales-queue' },
+    support: {
+      team: 'Support',
+      handler: classification.priority === 'urgent' ? 'urgent-queue' : 'support-queue',
+    },
+    marketing: { team: 'Marketing', handler: 'marketing-inbox' },
+    internal: { team: 'Internal', handler: 'internal-comms' },
+    spam: { team: 'None', handler: 'spam-filter' },
+    other: { team: 'Triage', handler: 'general-queue' },
+  }
+
+  const route = routingMap[classification.category] || routingMap.other
+
+  let suggestedResponse: string | undefined
+  if (canAutoRespond) {
+    suggestedResponse = await generateAutoResponse(email, classification, info)
+  }
+
+  return {
+    team: route.team,
+    handler: route.handler,
+    autoResponse: canAutoRespond,
+    escalate: needsEscalation,
+    suggestedResponse,
+  }
+}
+
+// ============================================================================
+// Auto-Response Generator
+// ============================================================================
+
+async function generateAutoResponse(
+  email: Email,
+  classification: ClassificationResult,
+  info: ExtractedInfo
+): Promise<string> {
+  console.log(`  Generating auto-response...`)
+
+  const response = await ai`Generate a brief, professional auto-response for this email:
+
+Original Subject: ${email.subject}
+Category: ${classification.category}
+Sender Intent: ${info.senderIntent}
+
+The response should:
+- Acknowledge receipt
+- Set expectations for response time
+- Provide any immediately helpful information
+- Be concise (3-4 sentences max)
+
+Return just the response text.`
+
+  return response as string
+}
+
+// ============================================================================
+// Batch Classification
+// ============================================================================
+
+async function batchClassifyEmails(emails: Email[]): Promise<void> {
+  console.log(`\n${'='.repeat(60)}`)
+  console.log('Batch Email Classification Results')
+  console.log('='.repeat(60))
+
+  for (const email of emails) {
+    const classification = await classifyEmail(email)
+    const info = await extractInfo(email)
+    const routing = await routeEmail(email, classification, info)
+
+    console.log(`
+ID: ${email.id}
+Subject: ${email.subject}
+---
+Classification:
+  Category: ${classification.category} / ${classification.subcategory}
+  Priority: ${classification.priority}
+  Sentiment: ${classification.sentiment}
+  Requires Response: ${classification.requiresResponse}
+
+Extracted Info:
+  Intent: ${info.senderIntent}
+  Entities: ${info.keyEntities.join(', ') || 'none'}
+  Action Items: ${info.actionItems.length}
+  Deadlines: ${info.deadlines.join(', ') || 'none'}
+
+Routing:
+  Team: ${routing.team}
+  Handler: ${routing.handler}
+  Auto-Response: ${routing.autoResponse}
+  Escalate: ${routing.escalate}
+${
+  routing.suggestedResponse
+    ? `\nSuggested Response:\n  "${routing.suggestedResponse.substring(0, 100)}..."`
+    : ''
+}
+${'='.repeat(60)}`)
+  }
+}
+
+// ============================================================================
+// Priority Comparison
+// ============================================================================
+
+async function prioritizeEmails(emails: Email[]): Promise<Email[]> {
+  console.log('\n--- Prioritizing Emails ---')
+
+  // Use decide to compare email urgency
+  if (emails.length < 2) return emails
+
+  // For demo, just compare first two
+  const moreUrgent = await decide`which email is more urgent and should be handled first`(
+    { subject: emails[0].subject, body: emails[0].body.substring(0, 100) },
+    { subject: emails[1].subject, body: emails[1].body.substring(0, 100) }
+  )
+
+  console.log(`Most urgent: "${(moreUrgent as Email).subject}"`)
+  return emails
+}
+
+// ============================================================================
+// Main Example
+// ============================================================================
+
+async function main() {
+  console.log('\n=== Email Classification & Routing Example ===\n')
+
+  // Configure the AI provider
+  configure({
+    model: 'sonnet',
+    provider: 'anthropic',
+  })
+
+  // Process all sample emails
+  await batchClassifyEmails(sampleEmails)
+
+  // Prioritize emails
+  await prioritizeEmails(sampleEmails.slice(0, 2))
+
+  // Show statistics
+  console.log('\n--- Processing Statistics ---')
+  console.log(`Total emails processed: ${sampleEmails.length}`)
+}
+
+main()
+  .then(() => {
+    console.log('\n=== Example Complete ===\n')
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error('\nError:', error.message)
+    process.exit(1)
+  })