luca-ai-chatbot/README.md

A modern, responsive AI chatbot widget for websites

# Reppy AI Chatbot - OpenAI Assistant API Integration

A modern, interactive AI chatbot built with OpenAI's Assistant API v2, featuring dynamic button generation, typewriter effects, and a responsive design.

## 🚀 Features

- **OpenAI Assistant API v2** integration with GPT-4o
- **Interactive Action Buttons** - Initial greeting buttons and dynamic AI-generated buttons
- **Typewriter Effect** - Smooth character-by-character response display
- **Smart Button Detection** - Automatically converts AI button suggestions into clickable elements
- **Text Formatting** - Supports markdown-style formatting (*bold*, _italic_, `code`)
- **Responsive Design** - Works seamlessly on desktop and mobile
- **File Upload Support** - Ready for image and document attachments
- **Error Handling** - User-friendly error messages and connection management
- **Finnish Language Support** - Optimized for Finnish conversations with Luca AI assistant

## 📋 Prerequisites

- OpenAI API key with Assistant API access
- Modern web browser with JavaScript enabled
- Web server (for production deployment)

## 🛠️ Setup Instructions

### 1. Get Your OpenAI API Key

1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)
2. Sign in or create an account
3. Navigate to API keys and create a new key
4. Copy your API key (format: `sk-proj-...`)

### 2. Configure the Chatbot

1. Open `script.js`
2. Find line 11: `const API_KEY = "..."`
3. Replace with your actual API key
4. Optional: Update the assistant ID on line 15 if you have a specific assistant

### 3. Deploy

- **Local Testing**: Open `index.html` in your browser
- **Production**: Upload all files to your web server

## 🎛️ Configuration Options

### Assistant Settings

Update the assistant configuration in `script.js`:

```javascript
// Line 15: Use your existing assistant ID
let assistantId = "asst_your_assistant_id_here";

// Or modify the createOrGetAssistant function for auto-creation
```

### Customization

**Initial Action Buttons** (lines 40-44):
```javascript
const buttons = [
  { emoji: '🤖', text: 'Automaatioasiat', action: 'automation' },
  { emoji: '✉️', text: 'Ota yhteyttä', action: 'contact' },
  { emoji: '❓', text: 'Muu kysymys', action: 'other' }
];
```

**Typewriter Speed** (line 380):
```javascript
typewriterEffect(messageElement, processedText, 30); // 30ms per character
```

**AI Model** (modify assistant creation):
```javascript
model: "gpt-4o", // or "gpt-4", "gpt-3.5-turbo"
```

## 🔧 Dynamic Button Feature

The chatbot automatically detects when the AI provides button options and converts them into clickable buttons.

### For AI Prompt Engineering

To enable dynamic buttons, instruct your AI to include button options in responses like this:

```
"Here are your options:

Option 1 text, Option 2 text, Option 3 text"
```

The system will:
1. Remove the button text from the message
2. Create clickable buttons below the response
3. Handle button clicks as user inputs

### Supported Button Formats

- Comma-separated options with emojis
- Finnish text patterns (e.g., "Minulla on idea, Minulla ei ole ideaa")
- Multiple options on a single line

### Text Formatting Support

The chatbot supports markdown-style text formatting:

- **Bold text**: `*text*` → **text**
- **Italic text**: `_text_` → *text*
- **Code**: `` `text` `` → `text`
- **Line breaks**: `\n` → line break

Example AI response:
```
Welcome to *Reppy*! We offer _customized AI solutions_ with `advanced automation` features.
```

This will render as: Welcome to **Reppy**! We offer *customized AI solutions* with `advanced automation` features.

## 🎨 Styling

The chatbot uses a modern purple theme that can be customized in `style.css`:

**Primary Colors:**
- Main: `#5350C4`
- Hover: `#3d39ac`
- Background: `#F2F2FF`

**Button Styles:**
- Rounded corners (`border-radius: 25px`)
- Smooth transitions
- Mobile-responsive design

## 📱 Mobile Support

- Responsive design adapts to mobile screens
- Touch-friendly button sizes
- Optimized input handling
- Smooth scrolling and animations

## 🔒 Security Features

- Input validation and sanitization
- Rate limiting awareness
- Error message sanitization
- Secure API key handling (client-side)

**Note:** For production use, consider implementing server-side API key management to avoid exposing keys in client code.

## 🐛 Troubleshooting

### Common Issues

**"Authentication error"**
- Check your API key is correct
- Ensure API key has Assistant API permissions

**"I'm receiving too many requests"**
- You've hit OpenAI's rate limits
- Wait a moment and try again

**"Connection error"**
- Check internet connection
- Verify OpenAI API status

**Buttons not appearing**
- Check browser console for errors
- Ensure AI is providing properly formatted button options

### Debug Mode

Temporarily add debug logging by uncommenting console.log statements in the code for detailed troubleshooting.

## 📊 Performance

- **Typewriter Effect**: 30ms per character (adjustable)
- **Button Detection**: Real-time parsing
- **API Calls**: Optimized with proper error handling
- **Mobile Performance**: Optimized for touch devices

## 🔄 Updates and Maintenance

The chatbot is built with OpenAI's latest Assistant API v2 and includes:
- Automatic assistant creation/retrieval
- Thread management for conversation persistence
- Modern error handling
- Responsive design patterns

## 📞 Support

For issues or questions:
- Check the browser console for error details
- Verify OpenAI API key permissions
- Ensure all files are properly uploaded
- Test with simple messages first

## 🏆 Production Checklist

- [ ] API key configured
- [ ] Assistant ID set (if using existing assistant)
- [ ] All files uploaded to server
- [ ] HTTPS enabled (recommended for API calls)
- [ ] Error handling tested
- [ ] Mobile responsiveness verified
- [ ] Button functionality confirmed

---

**Built with OpenAI Assistant API v2 | Optimized for GPT-4o | Mobile-Ready**