# MM Madam Chat Widget Integration Guide

This guide shows how to integrate the MM Madam chat widget into your existing website with minimal engineering effort.

## Architecture Overview

The solution consists of:
1. **Backend API** (`api_server.py`) - FastAPI server that handles chat logic
2. **Frontend Widget** (`chat-widget.js`) - Embeddable JavaScript widget
3. **Original Streamlit App** - Remains unchanged for internal use

## Backend Setup

### 1. Install Dependencies

```bash
pip install -r api_requirements.txt
```

### 2. Environment Configuration

Create a `.env` file or set these environment variables:

```bash
export GEMINI_API_KEY="your_gemini_api_key"
export CHARTS_DATA_API="your_charts_data_api_url"
export KNOWLEDGE_CSV_API="your_knowledge_csv_api_url"
export SYSTEM_PROMPT_URL="your_system_prompt_url"
export GITHUB_GIST_API="your_github_gist_api_url"  # Optional
export GITHUB_ACCESS_TOKEN="your_github_token"      # Optional
```

### 3. Run the API Server

```bash
# Development
python api_server.py

# Production (with Gunicorn)
pip install gunicorn
gunicorn api_server:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

### 4. API Endpoints

- `POST /chat` - Main chat endpoint
- `GET /health` - Health check
- `GET /models` - Available models and pricing

## Frontend Integration

### Option 1: Simple JavaScript Include (Recommended)

Add this single line to your website's HTML, preferably before the closing `</body>` tag:

```html
<script src="https://your-domain.com/chat-widget.js"></script>
```

### Option 2: Self-Hosted with Custom Configuration

```html
<script>
  // Optional: Set custom API URL
  window.MM_CHAT_API_URL = 'https://your-api-domain.com';
</script>
<script src="path/to/chat-widget.js"></script>
```

### Option 3: Manual Initialization

```html
<script src="path/to/chat-widget.js"></script>
<script>
  // Initialize with custom config
  MMChatWidget.init({
    apiUrl: 'https://your-api-domain.com'
  });
</script>
```

## Features

### Chat Widget Features
- 💬 Floating chat bubble with smooth animations
- 🎨 Modern, responsive design that works on mobile
- ⚙️ Configurable settings panel
- 🧠 Optional conversation memory
- 💎 User type detection (paid/free)
- 📊 Multiple data source toggles

### Configuration Options
- **Paid User Features**: Charts, Quickie, Blog, EDM reports
- **Free User Features**: Help Center, Stock/ETF info, Google Search
- **Memory**: Toggle conversation history (5 turns)
- **Data Sources**: Granular control over what information to include

## Customization

### Styling
The widget uses CSS custom properties and can be styled by overriding CSS variables:

```css
.mm-chat-widget {
  --primary-color: #667eea;
  --secondary-color: #764ba2;
  --border-radius: 12px;
}
```

### Position
Change the widget position by modifying CSS:

```css
.mm-chat-widget {
  bottom: 20px;   /* Distance from bottom */
  right: 20px;    /* Distance from right */
  left: auto;     /* Use 'left: 20px; right: auto;' for left side */
}
```

### API Configuration
Customize the widget behavior by passing config to the init function:

```javascript
MMChatWidget.init({
  apiUrl: 'https://your-api.com',
  // Add more config options as needed
});
```

## Deployment Considerations

### Backend Deployment
1. **Cloud Hosting**: Deploy on AWS, GCP, or Azure with load balancers
2. **Container**: Use Docker for easy deployment
3. **Environment**: Use environment variables for sensitive configuration
4. **CORS**: Update CORS settings in `api_server.py` to allow your domain

### Frontend Deployment
1. **CDN**: Host `chat-widget.js` on a CDN for faster loading
2. **Caching**: Set appropriate cache headers for the widget script
3. **Fallback**: Consider adding error handling for API failures

### Security
1. **API Keys**: Never expose API keys in frontend code
2. **Rate Limiting**: Implement rate limiting on the backend
3. **CORS**: Restrict CORS to your specific domains in production
4. **Authentication**: Consider adding user authentication if needed

## Testing

### Local Testing
1. Start the API server: `python api_server.py`
2. Open `chat-widget.html` in a browser
3. Test all features and configurations

### Production Testing
1. Deploy backend and update API URL in widget
2. Test widget integration on staging website
3. Verify all data sources work correctly
4. Test mobile responsiveness

## Monitoring

### API Monitoring
- Monitor `/health` endpoint for uptime
- Track response times and error rates
- Monitor token usage and costs

### Frontend Monitoring
- Track JavaScript errors
- Monitor widget load times
- Analyze user engagement metrics

## Migration from Streamlit

The integration preserves all existing functionality:
- ✅ Same AI model and logic
- ✅ Same data sources and retrieval
- ✅ Same configuration options
- ✅ Streamlit app remains unchanged
- ✅ No disruption to current workflows

## Support

For technical issues:
1. Check API health endpoint
2. Verify environment variables
3. Check browser console for JavaScript errors
4. Review CORS configuration

The widget is designed to fail gracefully and provide user-friendly error messages.