USAGE_GUIDE.md

# Qwen3-14B Chatbot - Quick Usage Guide

## 🎯 Three Ways to Control Thinking Mode

### 1. **Hard Switch: Enable Thinking Mode Checkbox**

Located in the sidebar, this is the main control:

- ✅ **Checked (ON)**: Thinking mode is available
  - Model can show reasoning process
  - Supports `/think` and `/no_think` soft switches
  - Best for: Math, coding, complex reasoning
  - Parameters: Temp=0.6, TopP=0.95, TopK=20

- ❌ **Unchecked (OFF)**: Thinking mode is disabled
  - No thinking process shown
  - Faster responses
  - Soft switches are ignored
  - Best for: General chat, quick questions
  - Parameters: Temp=0.7, TopP=0.8, TopK=20

---

### 2. **Soft Switch: `/think` Tag**

Force thinking for a specific message (only works when checkbox is ON):

```
User: How many r's are in "strawberry"? /think
```

**Result:**
```
🤔 Thinking Process:
Let me count each letter carefully:
s-t-r-a-w-b-e-r-r-y
The r's appear at positions 3, 8, and 9.

💬 Response:
There are 3 r's in the word "strawberry".
```

---

### 3. **Soft Switch: `/no_think` Tag**

Skip thinking for a specific message (only works when checkbox is ON):

```
User: What is 2+2? /no_think
```

**Result:**
```
💬 Response:
2+2 equals 4.
```

---

## 📊 Comparison Table

| Feature | Checkbox ON + `/think` | Checkbox ON + `/no_think` | Checkbox ON (default) | Checkbox OFF |
|---------|----------------------|--------------------------|---------------------|--------------|
| Shows thinking | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| `<think>` tags | ✅ With content | ⚠️ Empty | ✅ With content | ❌ None |
| Speed | 🐢 Slower | 🚀 Faster | 🐢 Slower | 🚀 Fastest |
| Best for | Complex problems | Quick answers | Reasoning tasks | General chat |

---

## 💡 Real-World Examples

### Example 1: Math Problem (Use Thinking)

```
User: Solve: If x^2 + 5x + 6 = 0, what are the values of x? /think

Bot:
🤔 Thinking Process:
This is a quadratic equation. I can solve it by factoring:
x^2 + 5x + 6 = 0
(x + 2)(x + 3) = 0
So x + 2 = 0 or x + 3 = 0
Therefore x = -2 or x = -3

💬 Response:
The values of x are -2 and -3.
```

### Example 2: Quick Fact (Skip Thinking)

```
User: What is the capital of Iraq? /no_think

Bot:
💬 Response:
The capital of Iraq is Baghdad (بغداد).
```

### Example 3: Multi-Turn Conversation

```
User: How many r's in "strawberry"? /think
Bot: 🤔 [shows counting process] 💬 There are 3 r's.

User: What about "blueberry"? /no_think
Bot: 💬 There are 2 r's in "blueberry".

User: Are you sure? /think
Bot: 🤔 [recounts carefully] 💬 Yes, confirmed: 2 r's in "blueberry".
```

---

## 🎓 Best Practices

### ✅ DO Use Thinking Mode For:
- 🧮 Math equations and calculations
- 💻 Code generation and debugging
- 🧩 Logic puzzles and riddles
- 📊 Data analysis questions
- 🔍 Complex reasoning tasks
- 📝 Step-by-step explanations

### ❌ DON'T Use Thinking Mode For:
- 💬 Simple greetings
- ❓ Basic factual questions
- 🎨 Creative writing
- 🗣️ Casual conversation
- ⚡ When you need quick responses

---

## ⚙️ Settings Explained

### System Prompt
Customizes the AI's personality and language style.

**Default (Iraqi Arabic):**
```
انت موديل عراقي ذكي من بغداد. تتحدث باللهجة العراقية فقط...
```

**English Alternative:**
```
You are a helpful AI assistant. Provide clear, detailed answers.
```

### Max New Tokens
Controls response length (100 - 32,768 tokens).

- **512**: Short answers
- **2,048**: Standard (default)
- **8,192**: Long explanations
- **32,768**: Maximum (for very complex problems)

---

## 🐛 Troubleshooting

### Issue: Soft switches not working
**Solution**: Make sure "Enable Thinking Mode" checkbox is ON

### Issue: Empty thinking blocks
**Cause**: You used `/no_think` or the model decided not to think
**Solution**: This is normal behavior; use `/think` to force thinking

### Issue: Responses too slow
**Solution**: 
1. Disable thinking mode checkbox, OR
2. Use `/no_think` for specific messages, OR
3. Reduce Max New Tokens

### Issue: Not enough detail in responses
**Solution**:
1. Enable thinking mode checkbox
2. Use `/think` tag
3. Increase Max New Tokens
4. Adjust system prompt for more detailed responses

---

## 🚀 Quick Start Checklist

1. ✅ Open the chatbot interface
2. ✅ Check if "Enable Thinking Mode" is ON (for complex tasks) or OFF (for chat)
3. ✅ Adjust "Max New Tokens" based on expected response length
4. ✅ (Optional) Customize System Prompt
5. ✅ Type your message
6. ✅ (Optional) Add `/think` or `/no_think` at the end
7. ✅ Press Enter and wait for response

---

## 📚 Additional Resources

- **Model Page**: https://huggingface.co/Qwen/Qwen3-14B
- **Documentation**: https://qwenlm.github.io/blog/qwen3/
- **Unsloth Version**: https://huggingface.co/unsloth/Qwen3-14B

---

## 💬 Need Help?

If you encounter issues or have questions:
1. Check the CHANGES.md file for detailed technical information
2. Review the examples above
3. Experiment with different settings
4. Read the official Qwen3 documentation

Happy chatting! 🎉