ai-functions 2.1.1 → 2.3.0

package/examples/00-quickstart.ts

@@ -0,0 +1,232 @@
+/**
+ * Quickstart Example
+ *
+ * This example demonstrates the core primitives of ai-functions in a simple,
+ * easy-to-follow format. It covers:
+ * - Basic text generation with `write`
+ * - List generation with `list`
+ * - Boolean checks with `is`
+ * - Structured output with `ai`
+ * - Configuration options
+ *
+ * @example
+ * ```bash
+ * ANTHROPIC_API_KEY=sk-... npx tsx examples/00-quickstart.ts
+ * ```
+ */
+
+import { ai, write, list, is, extract, configure, withContext } from '../src/index.js'
+
+// ============================================================================
+// Setup
+// ============================================================================
+
+// Configure the AI provider (optional - will use env vars by default)
+configure({
+  model: 'sonnet', // or 'gpt-4o', 'claude-3-5-haiku-latest', etc.
+  provider: 'anthropic', // or 'openai'
+})
+
+// ============================================================================
+// Text Generation
+// ============================================================================
+
+async function textGenerationExamples() {
+  console.log('\n=== Text Generation ===\n')
+
+  // Simple text generation
+  const haiku = await write`a haiku about TypeScript`
+  console.log('Haiku:', haiku)
+
+  // With more context
+  const email = await write`a professional email declining a meeting invitation.
+  Keep it brief and polite.`
+  console.log('\nEmail:', email)
+}
+
+// ============================================================================
+// List Generation
+// ============================================================================
+
+async function listGenerationExamples() {
+  console.log('\n=== List Generation ===\n')
+
+  // Generate a simple list
+  const ideas = await list`5 startup ideas in the AI space`
+  console.log('Startup Ideas:')
+  ideas.forEach((idea, i) => console.log(`  ${i + 1}. ${idea}`))
+
+  // Using map for processing (batched automatically)
+  console.log('\nProcessing ideas with map...')
+  const evaluated = await Promise.all(
+    ideas.slice(0, 3).map(async (idea) => ({
+      idea,
+      feasible: await is`"${idea}" is technically feasible with current technology`,
+    }))
+  )
+
+  console.log('\nFeasibility Check:')
+  evaluated.forEach((e) => {
+    console.log(`  ${e.feasible ? '✓' : '✗'} ${e.idea}`)
+  })
+}
+
+// ============================================================================
+// Boolean Checks
+// ============================================================================
+
+async function booleanCheckExamples() {
+  console.log('\n=== Boolean Checks ===\n')
+
+  // Simple true/false questions
+  const checks = [
+    await is`"TypeScript" is a programming language`,
+    await is`42 is a prime number`,
+    await is`Paris is the capital of France`,
+    await is`HTML is a programming language`,
+  ]
+
+  console.log('Boolean Checks:')
+  console.log(`  TypeScript is a programming language: ${checks[0]}`)
+  console.log(`  42 is a prime number: ${checks[1]}`)
+  console.log(`  Paris is capital of France: ${checks[2]}`)
+  console.log(`  HTML is a programming language: ${checks[3]}`)
+
+  // Content validation example
+  const userInput = 'Buy our amazing product at discount.com!!!'
+  const isSpam = await is`This text is spam or promotional: "${userInput}"`
+  console.log(`\n  "${userInput}" is spam: ${isSpam}`)
+}
+
+// ============================================================================
+// Structured Output
+// ============================================================================
+
+async function structuredOutputExamples() {
+  console.log('\n=== Structured Output ===\n')
+
+  // Extract structured data from text
+  const article = `
+    Apple Inc. announced today that CEO Tim Cook will be presenting
+    the new iPhone 16 at the September 2024 event in Cupertino, California.
+    The device is expected to feature AI capabilities and cost around $999.
+  `
+
+  // Using destructuring to define the schema
+  const { company, product, person, location, price, date } = await ai`
+    Extract key information from this article:
+    ${article}
+
+    Provide:
+    - company: company name
+    - product: product mentioned
+    - person: person mentioned
+    - location: location mentioned
+    - price: price if mentioned
+    - date: date or time mentioned
+  `
+
+  console.log('Extracted Information:')
+  console.log(`  Company: ${company}`)
+  console.log(`  Product: ${product}`)
+  console.log(`  Person: ${person}`)
+  console.log(`  Location: ${location}`)
+  console.log(`  Price: ${price}`)
+  console.log(`  Date: ${date}`)
+
+  // Generate structured content
+  const { title, description, tags } = await ai`
+    Create a blog post metadata for a post about "Getting Started with AI Functions":
+    - title: engaging blog post title
+    - description: SEO description (under 160 chars)
+    - tags: array of 5 relevant tags
+  `
+
+  console.log('\nGenerated Blog Metadata:')
+  console.log(`  Title: ${title}`)
+  console.log(`  Description: ${description}`)
+  console.log(`  Tags: ${(tags as string[]).join(', ')}`)
+}
+
+// ============================================================================
+// Data Extraction
+// ============================================================================
+
+async function extractionExamples() {
+  console.log('\n=== Data Extraction ===\n')
+
+  const text = `
+    Contact us at support@example.com or sales@company.io.
+    Call John at 555-123-4567 or reach Sarah at 555-987-6543.
+    Meeting scheduled for March 15, 2024 and follow-up on April 1st.
+  `
+
+  const emails = await extract`all email addresses from: ${text}`
+  console.log('Emails:', emails)
+
+  const phones = await extract`all phone numbers from: ${text}`
+  console.log('Phone Numbers:', phones)
+
+  const dates = await extract`all dates from: ${text}`
+  console.log('Dates:', dates)
+}
+
+// ============================================================================
+// Scoped Configuration
+// ============================================================================
+
+async function scopedConfigExamples() {
+  console.log('\n=== Scoped Configuration ===\n')
+
+  // Use different settings for specific operations
+  const result = await withContext(
+    {
+      model: 'claude-3-5-haiku-latest', // Use faster model
+      temperature: 0.1, // More deterministic
+    },
+    async () => {
+      console.log('  Using Haiku model with low temperature...')
+      return write`What is 2+2? Answer with just the number.`
+    }
+  )
+
+  console.log(`  Result: ${result}`)
+
+  // Back to default configuration
+  const creative = await write`Give a creative name for a cat`
+  console.log(`  Creative cat name: ${creative}`)
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('\n========================================')
+  console.log('  ai-functions Quickstart')
+  console.log('========================================')
+
+  await textGenerationExamples()
+  await listGenerationExamples()
+  await booleanCheckExamples()
+  await structuredOutputExamples()
+  await extractionExamples()
+  await scopedConfigExamples()
+
+  console.log('\n========================================')
+  console.log('  Quickstart Complete!')
+  console.log('========================================')
+  console.log(`
+Next steps:
+- Try the other examples in this directory
+- Read the README.md for the full API reference
+- Check out test/ for more usage patterns
+`)
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error('\nError:', error.message)
+    process.exit(1)
+  })

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