path: root/tooling/vercel-ai-sdk/README.md

# Vercel AI SDK Claude Code Configuration 🤖

A comprehensive Claude Code configuration for building production-ready AI applications with the Vercel AI SDK. This configuration transforms Claude Code into an expert AI SDK developer with specialized agents, custom commands, and automated workflows.

## ✨ Features

This configuration provides:

- **🤖 Specialized AI Agents** - Expert agents for RAG, multi-modal, streaming, tools, and providers
- **⚡ Custom Commands** - Slash commands for rapid AI SDK development workflows  
- **🔄 Automated Hooks** - Development lifecycle automation with formatting and validation
- **🏗️ Architecture Patterns** - RAG systems, multi-modal apps, streaming interfaces, agent workflows
- **🚀 Production Ready** - Comprehensive error handling, security, monitoring, and optimization
- **📚 Expert Knowledge** - Deep understanding from official Vercel AI SDK documentation
- **🛠️ Multi-Provider Setup** - Anthropic, OpenAI, Google, Cohere with intelligent fallbacks
- **🧪 Testing Strategies** - Comprehensive testing patterns for AI applications

## 📦 Installation

1. Copy the complete configuration to your AI project:

```bash
cp -r vercel-ai-sdk/.claude your-ai-project/
cp vercel-ai-sdk/CLAUDE.md your-ai-project/
```

2. Install the Vercel AI SDK dependencies:

```bash
npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google @ai-sdk/cohere
```

3. Set up your environment variables:

```bash
# Copy and configure your API keys
cp .env.example .env.local
```

4. Start Claude Code - the configuration loads automatically and activates expert mode! 🚀

## 🎯 What You Get

### 🤖 Specialized AI Agents

| Agent | Expertise | Use Cases |
|-------|-----------|-----------|
| **RAG Developer** | Embeddings, vector databases, semantic search | Knowledge bases, document retrieval, Q&A systems |
| **Multi-Modal Expert** | Image/PDF processing, file uploads | Document analysis, visual AI, media processing |
| **Streaming Expert** | Real-time responses, chat interfaces | Chat apps, live updates, progressive enhancement |
| **Tool Integration Specialist** | Function calling, external APIs | Agents, workflows, system integrations |
| **Provider Configuration Expert** | Multi-provider setup, optimization | Cost management, reliability, performance |

### ⚡ Custom Slash Commands

| Command | Purpose | Arguments |
|---------|---------|-----------|
| `/ai-chat-setup` | Complete chat interface setup | `basic\|advanced\|multimodal\|rag\|agent` |
| `/ai-streaming-setup` | Streaming implementation | `text\|object\|chat\|completion` |
| `/ai-tools-setup` | Tool and function calling | `simple\|database\|api\|multimodal\|agent` |
| `/ai-provider-setup` | Provider configuration | `single\|multi\|fallback [provider]` |
| `/ai-rag-setup` | RAG system implementation | `basic\|advanced\|conversational\|agentic` |

### 🏗️ Architecture Patterns

| Pattern | Description | Key Features |
|---------|-------------|-------------|
| **RAG Systems** | Retrieval-augmented generation | Embeddings, vector search, context injection |
| **Multi-Modal Apps** | Image/PDF/media processing | File uploads, vision models, document analysis |
| **Streaming Interfaces** | Real-time AI responses | Progressive updates, error recovery, interruption |
| **Agent Workflows** | Tool-calling AI systems | Multi-step execution, external integrations |
| **Provider Management** | Multi-provider architecture | Fallbacks, cost optimization, health monitoring |

## 🚀 Quick Start Examples

### 1. Create a Basic Chat Interface

```bash
# Use the custom command to set up everything
/ai-chat-setup basic
```

This automatically creates:

- API route with streaming
- React component with proper error handling
- TypeScript types and validation
- Tailwind CSS styling

### 2. Set Up RAG System

```bash
# Create a complete RAG implementation
/ai-rag-setup basic
```

Generates:

- Database schema with vector support
- Embedding pipeline with chunking
- Semantic search functionality
- RAG API with context injection

### 3. Multi-Modal Application

```bash
# Build image and PDF processing
/ai-chat-setup multimodal
```

Includes:

- File upload handling
- Image/PDF processing
- Multi-modal chat interface
- Proper validation and security

### 4. Provider Configuration

```bash
# Set up multi-provider architecture
/ai-provider-setup multi anthropic
```

Creates:

- Provider abstraction layer
- Fallback mechanisms
- Cost tracking
- Health monitoring

### 5. Agent with Tools

```bash
# Build function-calling agents
/ai-tools-setup agent
```

Implements:

- Tool definitions with Zod schemas
- Multi-step execution
- Error handling and retry logic
- Security and rate limiting

## 🔧 Environment Setup

Create `.env.local`:

```env
# Provider API Keys
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-openai-key-here
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key-here
COHERE_API_KEY=your-cohere-key-here

# Provider Configuration
DEFAULT_PROVIDER=anthropic
DEFAULT_MODEL_TIER=balanced
ENABLE_PROVIDER_FALLBACK=true
FALLBACK_PROVIDERS=anthropic,openai,google

# Usage Limits (Optional)
MAX_TOKENS_PER_REQUEST=4096
DAILY_TOKEN_LIMIT=100000
COST_LIMIT_USD=50

# Database (for RAG systems)
DATABASE_URL=postgresql://...
VECTOR_DIMENSIONS=1536
```

## 🔄 Development Lifecycle Automation

This configuration includes automated hooks that:

- **Format code** automatically with Prettier after edits
- **Validate API routes** and remind about security best practices
- **Track dependencies** and notify about AI SDK installations
- **Provide checklists** for streaming, error handling, and testing
- **Monitor development** and suggest optimizations

## 📊 Monitoring & Analytics

- **Usage tracking** across all providers
- **Cost calculation** and budget monitoring
- **Performance metrics** for streaming and tools
- **Error rate tracking** with automated alerts
- **Health checks** for provider availability

## 🛡️ Security & Compliance

- **API key protection** with environment validation
- **Input sanitization** and validation with Zod
- **Rate limiting** and abuse prevention
- **Audit logging** for sensitive operations
- **Privacy controls** for data handling

## 🧪 Testing Strategy

- **Unit tests** for all AI components
- **Integration tests** for streaming and tools
- **Performance tests** under load
- **Security tests** for validation and safety
- **End-to-end tests** for complete workflows

## 🚀 Deployment Ready

- **Vercel Deployment** - Optimized for Vercel's Edge Runtime
- **Environment Configuration** - Proper staging/production setup
- **Monitoring Setup** - Usage tracking and error monitoring
- **Scaling Considerations** - Auto-scaling and cost optimization

## 📚 Resources

- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
- [Provider Setup Guides](https://sdk.vercel.ai/providers/ai-sdk-providers)
- [Example Applications](https://github.com/vercel/ai/tree/main/examples)
- [Community Support](https://discord.gg/vercel)

## 🔗 Integration

This configuration works well with:

- **Next.js 15** - App Router and Server Components
- **shadcn/ui** - Beautiful chat interfaces
- **Tailwind CSS** - Styling for AI applications
- **Prisma/Drizzle** - Chat history persistence
- **Vercel** - Optimal deployment platform

---

**Ready to build next-generation AI applications with Claude Code and the Vercel AI SDK!** 🚀

🌟 **Star this configuration** if it enhances your AI development workflow!