ai-functions 2.1.3 → 2.4.0

package/examples/01-rag-chatbot.ts

@@ -0,0 +1,212 @@
+/**
+ * RAG Chatbot Example
+ *
+ * This example demonstrates building a Retrieval-Augmented Generation (RAG) chatbot
+ * using ai-functions. It shows how to:
+ * - Generate embeddings for documents
+ * - Perform semantic search
+ * - Generate context-aware responses
+ *
+ * @example
+ * ```bash
+ * ANTHROPIC_API_KEY=sk-... npx tsx examples/01-rag-chatbot.ts
+ * ```
+ */
+
+import {
+  write,
+  list,
+  configure,
+  EmbeddingCache,
+  MemoryCache,
+  GenerationCache,
+  withRetry,
+} from '../src/index.js'
+
+// ============================================================================
+// Document Store (In-memory for this example)
+// ============================================================================
+
+interface Document {
+  id: string
+  content: string
+  embedding?: number[]
+}
+
+const documents: Document[] = [
+  {
+    id: 'doc-1',
+    content:
+      'ai-functions is a TypeScript library that simplifies AI integration. It provides template literals for natural AI calls like `const poem = await write`a haiku about TypeScript``.',
+  },
+  {
+    id: 'doc-2',
+    content:
+      'The library supports batch processing with 50% cost savings through provider batch APIs. Use createBatch() to process large workloads efficiently.',
+  },
+  {
+    id: 'doc-3',
+    content:
+      'Built-in retry logic with exponential backoff handles rate limits automatically. Use withRetry() or RetryPolicy for custom retry behavior.',
+  },
+  {
+    id: 'doc-4',
+    content:
+      'Budget tracking monitors token usage and costs. BudgetTracker supports alerts at configurable thresholds and enforces spending limits.',
+  },
+  {
+    id: 'doc-5',
+    content:
+      'The list primitive generates arrays with automatic batching. Use list`5 ideas`.map() to process each item in parallel.',
+  },
+]
+
+// ============================================================================
+// Simple Embedding Simulation (replace with real embeddings in production)
+// ============================================================================
+
+function simulateEmbedding(text: string): number[] {
+  // Simple word-based embedding simulation
+  // In production, use a real embedding model
+  const words = text.toLowerCase().split(/\s+/)
+  const embedding = new Array(128).fill(0)
+
+  for (const word of words) {
+    const hash = word.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0)
+    embedding[hash % 128] += 1
+  }
+
+  // Normalize
+  const magnitude = Math.sqrt(embedding.reduce((acc, val) => acc + val * val, 0))
+  return embedding.map((val) => (magnitude > 0 ? val / magnitude : 0))
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dotProduct = 0
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i]
+  }
+  return dotProduct
+}
+
+// ============================================================================
+// RAG Chatbot Implementation
+// ============================================================================
+
+class RAGChatbot {
+  private documents: Document[]
+  private responseCache: GenerationCache
+
+  constructor(documents: Document[]) {
+    this.documents = documents
+    this.responseCache = new GenerationCache({
+      defaultTTL: 3600000, // 1 hour cache
+    })
+
+    // Generate embeddings for all documents
+    for (const doc of this.documents) {
+      doc.embedding = simulateEmbedding(doc.content)
+    }
+  }
+
+  /**
+   * Find the most relevant documents for a query
+   */
+  private findRelevantDocs(query: string, topK: number = 3): Document[] {
+    const queryEmbedding = simulateEmbedding(query)
+
+    const scored = this.documents.map((doc) => ({
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding!),
+    }))
+
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK)
+      .map(({ doc }) => doc)
+  }
+
+  /**
+   * Generate a response using RAG
+   */
+  async chat(userMessage: string): Promise<string> {
+    console.log(`\nUser: ${userMessage}`)
+    console.log('---')
+
+    // Step 1: Retrieve relevant documents
+    const relevantDocs = this.findRelevantDocs(userMessage)
+    console.log(`Found ${relevantDocs.length} relevant documents`)
+
+    // Step 2: Build context from retrieved documents
+    const context = relevantDocs.map((doc, i) => `[Source ${i + 1}]: ${doc.content}`).join('\n\n')
+
+    // Step 3: Generate response with context
+    const response =
+      await write`You are a helpful assistant that answers questions about ai-functions library.
+
+Context from documentation:
+${context}
+
+User Question: ${userMessage}
+
+Please provide a helpful, accurate response based on the context above. If the context doesn't contain enough information, say so.`
+
+    console.log(`Assistant: ${response}`)
+    return response
+  }
+
+  /**
+   * Generate follow-up questions
+   */
+  async suggestFollowUps(topic: string): Promise<string[]> {
+    const suggestions =
+      await list`3 follow-up questions someone might ask about ${topic} related to ai-functions library`
+    return suggestions
+  }
+}
+
+// ============================================================================
+// Main Example
+// ============================================================================
+
+async function main() {
+  console.log('\n=== RAG Chatbot Example ===\n')
+
+  // Configure the AI provider
+  configure({
+    model: 'sonnet',
+    provider: 'anthropic',
+  })
+
+  // Initialize the chatbot with our documents
+  const chatbot = new RAGChatbot(documents)
+
+  // Example conversation
+  const questions = [
+    'How do I generate a list of items?',
+    'What are the cost savings for batch processing?',
+    'How does retry handling work?',
+  ]
+
+  for (const question of questions) {
+    await chatbot.chat(question)
+    console.log('')
+  }
+
+  // Generate follow-up suggestions
+  console.log('\n--- Suggested follow-up questions ---')
+  const followUps = await chatbot.suggestFollowUps('batch processing')
+  for (const suggestion of followUps) {
+    console.log(`- ${suggestion}`)
+  }
+}
+
+main()
+  .then(() => {
+    console.log('\n=== Example Complete ===\n')
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error('\nError:', error.message)
+    process.exit(1)
+  })

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