# AI Human-in-the-Loop Assistant

A sophisticated AI assistant that demonstrates the human-in-the-loop pattern, where AI tools require explicit human approval before execution. Features interactive chat interface with approval workflows, rate limiting, and comprehensive tool management for safe AI interactions.

## ✨ Features

- **🤖 Human-in-the-Loop Pattern**: AI tools pause for human approval before execution
- **💬 Interactive Chat Interface**: Real-time conversation with AI using streaming responses
- **🛡️ Safe Tool Execution**: Tools requiring approval vs. auto-execute tools
- **⚡ Real-time Approval Workflow**: Instant approval/rejection with immediate feedback
- **📊 Multiple Tool Categories**: Weather, moderation, shopping, user management, payments
- **🔒 Rate Limiting**: Built-in protection against abuse with Redis-based limiting
- **📱 Responsive Design**: Clean, modern interface with status indicators
- **🎯 Predefined Use Cases**: Quick-start examples for common scenarios
- **🔄 State Management**: Robust conversation state with tool result handling
- **⚙️ Type-Safe Implementation**: Full TypeScript support with proper error handling

## 🏗️ Architecture

### Human-in-the-Loop Pattern
This block demonstrates the official AI SDK v5 human-in-the-loop pattern where:
- **Approval-Required Tools**: Pause execution and wait for human confirmation
- **Auto-Execute Tools**: Run immediately without requiring approval
- **Mixed Tool Types**: Seamlessly handle both patterns in a single conversation
- **Tool Result Streaming**: Real-time feedback on tool execution results

### Clean Component Structure
This block demonstrates best practices for React component organization with clear separation of concerns:

```
components/
├── human-in-loop-chat.tsx    # Main orchestrator (318 lines)
├── intro-heading.tsx         # Header with status indicators
lib/
├── tools.ts                  # Tool definitions (96 lines)
├── utils.ts                  # Tool processing utilities (147 lines)
├── rate-limit.ts            # Rate limiting implementation
app/
├── api/human-in-loop/route.ts # API endpoint with streaming
├── page.tsx                  # Main page component
└── layout.tsx               # Layout wrapper
```

### Core Components

#### Main Components
- **`HumanInLoopChat`**: Main orchestrator managing conversation state and tool approvals
- **`HeaderSection`**: Dynamic header with status indicators and SDK information
- **`Conversation`**: Chat interface with message handling and streaming
- **`Tool`**: Interactive tool approval interface with input/output display

#### Tool Management
- **`tools.ts`**: Defines all available tools with approval requirements
- **`utils.ts`**: Processes tool calls and handles approval workflows
- **`processToolCalls`**: Main function for handling tool execution logic

### Tool Categories

#### Approval-Required Tools
- **Weather Information**: Get weather data for any city
- **Content Moderation**: Moderate user-generated content
- **Shopping Cart**: Add items to cart with approval
- **User Approval**: Approve or deny user registrations
- **Payment Processing**: Process payments with confirmation

#### Auto-Execute Tools
- **Web Search**: Search the web for current information
- **Local Time**: Get current time for any location

### AI Integration
- **AI SDK v5**: Latest AI SDK with streaming and tool support
- **OpenAI GPT-4**: Advanced language model for intelligent responses
- **Tool Streaming**: Real-time tool execution with immediate feedback
- **Context Management**: Maintains conversation context across tool calls

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- OpenAI API key
- Upstash Redis (for rate limiting)

### Environment Variables
```bash
# Required
OPENAI_API_KEY=your_openai_api_key_here

# Required for rate limiting (recommended for production)
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token
```

### Installation
1. **Install core dependencies:**
```bash
npm install @ai-sdk/react @ai-sdk/openai ai sonner lucide-react
```

2. **Add shadcn/ui components:**
```bash
npx shadcn@latest add button card tooltip
```

3. **Copy the block files** to your project

## 💻 Usage

### Basic Implementation
```tsx
import HumanInLoopChat from "./components/human-in-loop-chat";

export function HumanInLoopPage() {
  return (
    <div className="mx-auto min-h-full w-screen md:min-h-screen">
      <HumanInLoopChat />
    </div>
  );
}
```

### API Route
The block includes a complete API route at `app/api/human-in-loop/route.ts` that handles:
- Message streaming with AI SDK v5
- Tool execution with human approval workflows
- Rate limiting (configurable per IP)
- Error handling with proper HTTP status codes
- Tool result streaming back to client

### Tool Approval Workflow
The human-in-the-loop pattern works as follows:

1. **User Request**: User sends a message requiring tool execution
2. **Tool Detection**: AI identifies which tools are needed
3. **Approval Required**: Tools without `execute` functions pause for approval
4. **Human Decision**: User approves or denies the tool execution
5. **Tool Execution**: Approved tools run and return results
6. **Response**: AI processes results and responds to user

### Example Use Cases
The block includes 5 predefined use cases to get you started:

1. **Weather Check** - "What's the weather like in New York?"
2. **Content Moderation** - Moderate user comments for inappropriate content
3. **Shopping Cart** - Add expensive items with approval workflow
4. **User Approval** - Approve or deny user registration requests
5. **Payment Processing** - Process payments with confirmation

### Example Commands
Try these natural language commands to see the human-in-the-loop pattern:

**Approval-Required Tools:**
- "What's the weather in Tokyo?" (requires approval)
- "Moderate this comment: 'This is terrible!'" (requires approval)
- "Add a MacBook Pro to my cart" (requires approval)
- "Approve user registration for john@example.com" (requires approval)
- "Process a $500 payment" (requires approval)

**Auto-Execute Tools:**
- "Search for latest AI news" (executes immediately)
- "What time is it in London?" (executes immediately)

## 🏛️ Architecture Deep Dive

### State Management
- **AI SDK React**: Handles chat messages and streaming state
- **Tool State**: Manages approval workflows and execution results
- **Rate Limiting**: Redis-based protection with configurable limits
- **Type Safety**: Full TypeScript support throughout the application

### Data Flow
1. **User Input** → Message sent to AI via chat interface
2. **Tool Analysis** → AI identifies required tools and their approval status
3. **Approval Workflow** → Tools requiring approval pause for human decision
4. **Tool Execution** → Approved tools execute and stream results
5. **Response Generation** → AI processes results and responds to user

### Rate Limiting Configuration
The API includes built-in rate limiting using Upstash Redis:
- **Configurable Limits**: Set per IP address or user
- **Sliding Window**: Time-based rate limiting
- **Headers**: Includes rate limit information in responses
- **Error Response**: Returns 429 status with retry information

To configure rate limiting:
1. Set up an Upstash Redis database
2. Add environment variables for Redis connection
3. Rate limiting will be automatically applied to all API requests

### Performance Optimizations
- **Component Splitting**: Modular architecture reduces bundle size
- **Efficient Re-renders**: Optimized state management prevents unnecessary updates
- **Streaming Responses**: Real-time updates without blocking UI
- **Lazy Loading**: Components load only when needed
- **Tool Caching**: Efficient tool execution with result caching

## 🎨 Customization

### Adding New Tools
1. **Define Tool**: Add new tool in `lib/tools.ts` with or without `execute` function
2. **Add Execute Function**: If auto-execute, add implementation in API route
3. **Update Types**: Ensure TypeScript definitions are current
4. **Test Workflow**: Verify approval process works correctly

### Tool Configuration
```typescript
// Approval-required tool (no execute function)
const myTool = tool({
  description: "description of what the tool does",
  inputSchema: z.object({ param: z.string() }),
  outputSchema: z.string(),
  // No execute function = requires human approval
});

// Auto-execute tool (with execute function)
const myAutoTool = tool({
  description: "description of what the tool does",
  inputSchema: z.object({ param: z.string() }),
  outputSchema: z.string(),
  execute: async ({ param }) => {
    // Implementation here
    return "Tool result";
  },
});
```

### Styling & Theming
- **Tailwind CSS**: Utility-first styling approach
- **Responsive Design**: Mobile-first with desktop enhancements
- **Dark/Light Mode**: Built-in theme support
- **Custom Components**: Easy to extend with your own styles
- **Status Indicators**: Visual feedback for tool states

### Extending Functionality
- **New Tool Categories**: Add tools for different domains
- **Advanced Approval**: Implement complex approval workflows
- **Custom UI**: Create specialized approval interfaces
- **Integration**: Connect with external approval systems

## 🔧 Technical Details

### Core Dependencies
```json
{
  "@ai-sdk/react": "AI SDK React hooks and components",
  "@ai-sdk/openai": "OpenAI integration",
  "ai": "Core AI SDK functionality",
  "sonner": "Toast notifications",
  "lucide-react": "Icon components",
  "@upstash/ratelimit": "Rate limiting",
  "@upstash/redis": "Redis client for rate limiting",
  "zod": "Schema validation"
}
```

### Tool Processing Logic
The `processToolCalls` function handles the core human-in-the-loop logic:

1. **Tool Detection**: Identifies tools requiring approval vs. auto-execute
2. **Approval Check**: Looks for "Yes, confirmed." or "No, denied." responses
3. **Execution**: Runs approved tools with proper error handling
4. **Streaming**: Sends results back to client in real-time
5. **State Management**: Updates conversation state with tool results

### Error Handling
- **Tool Errors**: Graceful handling of tool execution failures
- **Rate Limiting**: Proper 429 responses with retry information
- **Network Issues**: Robust error boundaries and fallbacks
- **Validation**: Zod schema validation for all tool inputs

### Shadcn/UI Components
- **button**: Interactive approval buttons
- **card**: Content containers and tool displays
- **tooltip**: Helpful user guidance
- **Custom Components**: Specialized AI elements for chat interface

### Performance Characteristics
- **Bundle Size**: Optimized with tree-shaking and code splitting
- **Memory Usage**: Efficient state management with minimal re-renders
- **Rendering**: Optimized React patterns for smooth interactions
- **Streaming**: Real-time updates without performance impact

## 🎯 Use Cases

### Business Applications
- **Content Moderation**: Safe AI-powered content review with human oversight
- **E-commerce**: Shopping cart management with approval workflows
- **User Management**: Registration approval with human verification
- **Financial Operations**: Payment processing with confirmation requirements
- **Customer Service**: AI assistance with human escalation points

### Development & Learning
- **AI Safety**: Learn how to implement safe AI tool execution
- **Human-AI Collaboration**: Understand approval workflow patterns
- **Tool Management**: Study advanced tool orchestration techniques
- **TypeScript**: See advanced TypeScript usage with AI SDK

### Educational Tools
- **AI Ethics**: Demonstrate responsible AI tool usage
- **Workflow Design**: Learn approval pattern implementation
- **Tool Architecture**: Understand tool definition and execution
- **Rate Limiting**: Study production-ready rate limiting patterns

## 🤝 Contributing

### Development Guidelines
When extending this block, follow these best practices:

1. **Tool Design**: Clearly define approval requirements for each tool
2. **TypeScript**: Keep all types up-to-date and comprehensive
3. **Error Handling**: Implement proper error boundaries and fallbacks
4. **Testing**: Test approval workflows with various scenarios
5. **Documentation**: Update README and code comments for new features
6. **Performance**: Consider bundle size and rendering performance

### Code Organization
- Keep tools focused on single responsibilities
- Use consistent naming conventions for approval responses
- Maintain clear separation between approval-required and auto-execute tools
- Add proper JSDoc comments for complex functions

### Testing Checklist
- [ ] Test approval workflows with various tools
- [ ] Verify auto-execute tools work correctly
- [ ] Check rate limiting functionality
- [ ] Test error handling scenarios
- [ ] Validate TypeScript compilation
- [ ] Test streaming responses
- [ ] Verify tool result processing

## 📄 License

This block is part of the Cult UI Pro registry and follows the project's licensing terms.

---

## 🚀 Getting Started Checklist

- [ ] Install dependencies
- [ ] Set up environment variables
- [ ] Configure Redis for rate limiting
- [ ] Copy block files to your project
- [ ] Configure API routes
- [ ] Test with sample use cases
- [ ] Customize tools for your needs
- [ ] Deploy and enjoy!

**Need help?** Check the [Cult UI Pro documentation](https://cultui.com) or open an issue in the repository.

## 🔗 Related Resources

- [AI SDK v5 Documentation](https://ai-sdk.dev/docs/introduction)
- [Human-in-the-Loop Pattern](https://ai-sdk.dev/cookbook/next/human-in-the-loop)
- [Tool Function Reference](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool)
- [Streaming with AI SDK](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream)
ai-human-in-the-loop
