# AI Chatbot Configuration Guide

Guide to configure and optimize AI-powered chatbot using OpenAI or Azure OpenAI.

## Overview

The AI Chatbot uses GPT-4 or GPT-3.5 to provide intelligent, context-aware responses to customer messages. It can understand natural language, maintain conversation context, and provide helpful information.

## Choosing AI Provider

### Option 1: OpenAI

**Pros**:
- ✅ Easy setup
- ✅ Pay-as-you-go pricing
- ✅ Latest models (GPT-4 Turbo)
- ✅ Good for global deployment

**Cons**:
- ❌ External API (latency)
- ❌ Data processed outside your region

**Setup**:
1. Create account at [platform.openai.com](https://platform.openai.com/)
2. Generate API key from **API Keys** page
3. Add credits to billing account

```bash
# .env configuration
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxx"
OPENAI_MODEL="gpt-4-turbo"
```

### Option 2: Azure OpenAI

**Pros**:
- ✅ Enterprise security & compliance
- ✅ Data residency control
- ✅ SLA guarantees
- ✅ VNET integration

**Cons**:
- ❌ More complex setup
- ❌ Requires Azure subscription
- ❌ Slower model updates

**Setup**:
1. Create Azure OpenAI resource in Azure Portal
2. Deploy model (e.g., `gpt-4`)
3. Copy endpoint and key

```bash
# .env configuration
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
AZURE_OPENAI_KEY="your-key-here"
AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4"
```

---

## Model Selection

| Model | Best For | Cost | Speed |
|-------|----------|------|-------|
| **GPT-4 Turbo** | Complex reasoning, accurate responses | $$ | Medium |
| **GPT-4** | High quality, nuanced understanding | $$$ | Slow |
| **GPT-3.5 Turbo** | Fast responses, simple queries | $ | Fast |

**Recommendation**:
- **E-commerce Support**: `gpt-3.5-turbo` (fast & cost-effective)
- **Technical Support**: `gpt-4-turbo` (better accuracy)
- **Multilingual Support**: `gpt-4-turbo` (better language handling)

---

## System Prompt Best Practices

### E-commerce Example

```
You are the AI assistant for "GoodGo Shop", a multi-category e-commerce platform in Vietnam.

PRODUCTS:
- Electronics (phones, laptops, accessories)
- Fashion (clothing, shoes, bags)
- Home & Living (furniture, kitchenware)

CAPABILITIES:
- Check order status (ask for order ID)
- Provide product information
- Explain shipping & return policies
- Help with account issues

TONE:
- Friendly and conversational
- Use Vietnamese when customer uses Vietnamese
- Use simple language, avoid jargon

LIMITATIONS:
- Cannot process refunds (refer to human agent)
- Cannot modify orders (refer to customer service)
- Cannot access payment information

When you cannot help, say: "Let me connect you with our customer service team for this request."
```

---

## Configuration Parameters

### Temperature

Controls randomness (0.0 - 2.0)

| Value | Behavior | Use Case |
|-------|----------|----------|
| **0.0 - 0.3** | Deterministic, focused | FAQ, policy questions |
| **0.4 - 0.7** | Balanced creativity | General customer service |
| **0.8 - 1.0** | More creative | Marketing, engagement |

**Recommendation**: `0.7` for customer service

### Max Tokens

Maximum length of response

| Tokens | Words | Use Case |
|--------|-------|----------|
| 150 | ~100 | Quick answers |
| 300 | ~200 | Standard responses |
| 500 | ~350 | Detailed explanations |

**Recommendation**: `300-500` tokens for most cases

### Top P (Nucleus Sampling)

Alternative to temperature (0.0 - 1.0)

- **0.9**: Recommended default
- Use either `temperature` OR `top_p`, not both

---

## Context Management

### Conversation History

Include recent messages for context:

```csharp
var messages = new List<ChatMessage>
{
    new ChatMessage(ChatRole.System, systemPrompt),
    new ChatMessage(ChatRole.User, "What are your opening hours?"),
    new ChatMessage(ChatRole.Assistant, "We're open 10AM - 10PM daily."),
    new ChatMessage(ChatRole.User, "Can I order delivery now?"),
};
```

**Best Practice**:
- Keep last **5-10 messages** for context
- Trim old messages to save tokens
- Always include System message

### Token Budget

| Component | Tokens | Note |
|-----------|--------|------|
| System Prompt | 100-200 | Fixed |
| Conversation History | 50-100 per message | Variable |
| Max Response | 300-500 | Configurable |
| **Total per request** | ~500-1500 | Estimate |

**Cost Estimation** (GPT-4 Turbo):
- Input: $0.01 / 1K tokens
- Output: $0.03 / 1K tokens
- **Average cost per conversation**: $0.02 - $0.05

---

## Fallback Strategies

### 1. Fallback to Automation

When AI confidence is low, fallback to automation rules.

### 2. Human Handoff

Escalate to human agent for complex issues.

**Trigger Phrases** (in AI response):
- "I'm not sure"
- "Let me connect you"
- "human agent"

**Action**: Update conversation status to `NeedsHumanAgent`

### 3. Timeout Handling

If OpenAI API times out, use fallback response:
```
"I apologize for the delay. Let me connect you with our team."
```

---

## Multilingual Support

### Auto-detect Language

GPT-4 can auto-detect and respond in the customer's language.

**System Prompt**:
```
You are a multilingual customer service assistant.
- Detect the customer's language
- Respond in the same language
- Support: English, Vietnamese, Thai, Chinese
```

---

## Testing & Optimization

### A/B Testing System Prompts

| Metric | Target | Measurement |
|--------|--------|-------------|
| **Response Quality** | User satisfaction > 80% | Thumbs up/down |
| **Resolution Rate** | > 70% without human | Track escalations |
| **Response Time** | < 3 seconds | API latency |
| **Cost per Conversation** | < $0.05 | Token usage |

---

## Cost Optimization

### 1. Use Shorter System Prompts

```diff
- You are a helpful customer service assistant for GoodGo Shop, an e-commerce platform selling electronics, fashion, home & living...
+ You are a customer service AI for GoodGo, an e-commerce platform.
```

**Savings**: ~50 tokens per request

### 2. Limit Conversation History

```csharp
// Only keep recent 5 messages
var contextMessages = conversation.Messages
    .OrderByDescending(m => m.SentAt)
    .Take(5)
    .Reverse();
```

**Savings**: ~200-400 tokens per request

### 3. Use GPT-3.5 for Simple Queries

```csharp
if (IsSimpleQuery(message)) // FAQ, product lookup
{
    model = "gpt-3.5-turbo"; // 10x cheaper
}
else
{
    model = "gpt-4-turbo";
}
```

### 4. Cache Common Responses

Cache responses for FAQs in Redis.

---

## Example Configurations

### Configuration 1: High-Quality Support

```json
{
  "provider": "OpenAI",
  "model": "gpt-4-turbo",
  "systemPrompt": "Detailed customer service prompt...",
  "temperature": 0.6,
  "maxTokens": 500
}
```

**Use Case**: Premium brands, complex products  
**Cost**: ~$0.04 per conversation

### Configuration 2: Fast & Cost-Effective

```json
{
  "provider": "OpenAI",
  "model": "gpt-3.5-turbo",
  "systemPrompt": "Concise customer service prompt...",
  "temperature": 0.7,
  "maxTokens": 300
}
```

**Use Case**: High-volume, simple queries  
**Cost**: ~$0.005 per conversation

---

## Troubleshooting

### Issue 1: Responses Too Generic

**Solution**:
- ✅ Add more context to system prompt
- ✅ Include conversation history
- ✅ Lower temperature (0.5)

### Issue 2: High Costs

**Solution**:
- ✅ Shorten system prompt
- ✅ Limit conversation history
- ✅ Use GPT-3.5 for simple queries
- ✅ Cache common FAQs

### Issue 3: Slow Responses

**Solution**:
- ✅ Use GPT-3.5 Turbo (faster)
- ✅ Reduce max_tokens
- ✅ Enable streaming
- ✅ Use Azure OpenAI (regional deployment)

### Issue 4: AI Hallucinates

**Solution**:
- ✅ Add: "Do not make up information"
- ✅ Lower temperature (0.3-0.5)
- ✅ Provide factual context in system prompt

---

## Resources

### Official Documentation
- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
- [Azure OpenAI Documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
- [GPT Best Practices](https://platform.openai.com/docs/guides/prompt-engineering)

### Tools
- [OpenAI Playground](https://platform.openai.com/playground)
- [Tokenizer](https://platform.openai.com/tokenizer)
- [Azure OpenAI Studio](https://oai.azure.com/)

### Internal Docs
- [API Documentation](./API.md)
- [Architecture Documentation](./ARCHITECTURE.md)
- [Facebook Setup Guide](./FACEBOOK_SETUP.md)
