docs: Add LLM-assisted attendant documentation

New Documentation: - chapter-11-features/attendant-llm-assist.md - Full guide for AI copilot features - chapter-11-features/transfer-to-human.md - Human handoff and needs_human flag Updated Documentation: - executive-vision.md - Added investor highlights, competitive advantages, LLM assist overview - SUMMARY.md - Added new chapters - appendix-external-services/README.md - Added CRM/attendant config options - appendix-external-services/llm-providers.md - Updated model names to current/generic - chapter-02/gbai.md - Updated model name examples Features Documented: - needs_human flag and how it routes messages - WhatsApp attendant commands (/queue, /tips, /polish, etc.) - All 5 LLM assist features with config.csv options - Analytics and insights APIs - Troubleshooting guide
2025-12-05 13:50:28 -03:00 · 2025-12-05 13:50:28 -03:00 · 80f1041263
commit 80f1041263
parent c4d209352d
7 changed files with 1243 additions and 21 deletions
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@ -300,6 +300,8 @@
  - [Multi-Agent Orchestration](./chapter-11-features/multi-agent-orchestration.md)
  - [Memory Management](./chapter-11-features/memory-management.md)
  - [Hybrid RAG Search](./chapter-11-features/hybrid-search.md)
+  - [Transfer to Human](./chapter-11-features/transfer-to-human.md)
+  - [LLM-Assisted Attendant](./chapter-11-features/attendant-llm-assist.md)

 # Part XI - Security

--- a/src/appendix-external-services/README.md
+++ b/src/appendix-external-services/README.md
@ -54,12 +54,21 @@ llm-model,gpt-4o
 weather-api-key,YOUR_OPENWEATHERMAP_KEY
 whatsapp-api-key,YOUR_WHATSAPP_KEY
 whatsapp-phone-number-id,YOUR_PHONE_ID
+whatsapp-verify-token,YOUR_WEBHOOK_VERIFY_TOKEN
 teams-app-id,YOUR_TEAMS_APP_ID
 teams-app-password,YOUR_TEAMS_PASSWORD
 instagram-access-token,YOUR_INSTAGRAM_TOKEN
 instagram-page-id,YOUR_PAGE_ID
 botmodels-enabled,true
 botmodels-url,http://localhost:5000
+
+# Human Handoff / CRM Features
+crm-enabled,true
+attendant-llm-tips,true
+attendant-polish-message,true
+attendant-smart-replies,true
+attendant-auto-summary,true
+attendant-sentiment-analysis,true
 ```

 ## Auto-Managed Services
--- a/src/appendix-external-services/llm-providers.md
+++ b/src/appendix-external-services/llm-providers.md
@ -47,15 +47,15 @@ Known for safety, helpfulness, and extended thinking capabilities.

 | Model | Context | Best For | Speed |
 |-------|---------|----------|-------|
-| Claude Opus 4.5 | 200K | Most capable, complex reasoning | Slow |
-| Claude Sonnet 4.5 | 200K | Best balance of capability/speed | Fast |
+| Claude Opus | 200K | Most capable, complex reasoning | Slow |
+| Claude Sonnet | 200K | Best balance of capability/speed | Fast |

 **Configuration (config.csv):**

 ```csv
 name,value
 llm-provider,anthropic
-llm-model,claude-sonnet-4.5
+llm-model,claude-sonnet
 ```

 **Strengths:**
@ -74,16 +74,15 @@ Google's multimodal AI models with strong reasoning capabilities.

 | Model | Context | Best For | Speed |
 |-------|---------|----------|-------|
-| Gemini 3 Pro | 2M | Complex reasoning, benchmarks | Medium |
-| Gemini 2.5 Pro | 2M | Extremely long documents | Medium |
-| Gemini 2.5 Flash | 1M | Fast multimodal | Fast |
+| Gemini Pro | 2M | Complex reasoning, benchmarks | Medium |
+| Gemini Flash | 1M | Fast multimodal tasks | Fast |

 **Configuration (config.csv):**

 ```csv
 name,value
 llm-provider,google
-llm-model,gemini-3-pro
+llm-model,gemini-pro
 ```

 **Strengths:**
@ -291,9 +290,9 @@ Use different models for different tasks:
 ```csv
 name,value
 llm-provider,anthropic
-llm-model,claude-sonnet-4.5
+llm-model,claude-sonnet
 llm-fast-provider,groq
-llm-fast-model,llama-4-scout
+llm-fast-model,llama-3.3-70b
 llm-fallback-provider,local
 llm-fallback-model,DeepSeek-R1-Distill-Qwen-1.5B
 embedding-provider,local
@ -306,15 +305,15 @@ embedding-model,bge-small-en-v1.5

 | Use Case | Recommended | Why |
 |----------|-------------|-----|
-| Customer support | Claude Sonnet 4.5 | Best at following guidelines |
-| Code generation | DeepSeek-R1, GPT-5 | Specialized for code |
-| Document analysis | Gemini 3 Pro | 2M context window |
-| Real-time chat | Groq Llama 4 Scout | Fastest responses |
+| Customer support | Claude Sonnet | Best at following guidelines |
+| Code generation | DeepSeek-R1, GPT-4o | Specialized for code |
+| Document analysis | Gemini Pro | 2M context window |
+| Real-time chat | Groq Llama 3.3 | Fastest responses |
 | Privacy-sensitive | Local DeepSeek-R1 | No external data transfer |
-| Cost-sensitive | DeepSeek-V3.1, Local | Lowest cost per token |
-| Complex reasoning | Claude Opus 4.5, Gemini 3 Pro | Best reasoning ability |
-| Real-time research | Grok 4 | Live data access |
-| Long context (10M) | Llama 4 Scout | Largest context window |
+| Cost-sensitive | DeepSeek, Local models | Lowest cost per token |
+| Complex reasoning | Claude Opus, Gemini Pro | Best reasoning ability |
+| Real-time research | Grok | Live data access |
+| Long context | Gemini Pro, Claude | Largest context windows |

 ### By Budget

--- a/src/chapter-02/gbai.md
+++ b/src/chapter-02/gbai.md
@ -82,7 +82,7 @@ Each folder becomes a searchable collection. Drop files in, bot learns automatic
 Single `config.csv` file with key-value pairs:

 ```csv
-llm-model,gpt-3.5-turbo
+llm-model,your-preferred-model
 temperature,0.7
 max-tokens,2000
 welcome-message,Hello! How can I help?
@ -147,7 +147,7 @@ TALK "Ticket #" + ticket_id + " created"

 `config.csv`:
 ```csv
-llm-model,gpt-3.5-turbo
+llm-model,your-preferred-model
 bot-name,TechSupport
 greeting,Welcome to support!
 ```
--- a/src/chapter-11-features/attendant-llm-assist.md
+++ b/src/chapter-11-features/attendant-llm-assist.md
@ -0,0 +1,497 @@
+# LLM-Assisted Attendant Features
+
+General Bots provides AI-powered assistance to human attendants during customer conversations. These features help attendants respond faster, more professionally, and with better context awareness.
+
+## Overview
+
+When the bot transfers a conversation to a human attendant (via `TRANSFER TO HUMAN`), the LLM orchestrator continues working in the background to assist the human. This creates a hybrid experience where AI augments human capability rather than replacing it.
+
+The system uses the same `PROMPT.md` and bot personality configured for the bot, ensuring consistency between bot responses and attendant assistance.
+
+## Features
+
+| Feature | Config Key | Description |
+|---------|-----------|-------------|
+| **Real-time Tips** | `attendant-llm-tips` | Contextual tips when customer messages arrive |
+| **Message Polish** | `attendant-polish-message` | Improve grammar and tone before sending |
+| **Smart Replies** | `attendant-smart-replies` | Generate 3 contextual reply suggestions |
+| **Auto Summary** | `attendant-auto-summary` | Summarize conversation when attendant joins |
+| **Sentiment Analysis** | `attendant-sentiment-analysis` | Real-time emotional state tracking |
+
+## Configuration
+
+Add these settings to your bot's `config.csv`:
+
+```csv
+name,value
+
+# Enable all LLM assist features
+attendant-llm-tips,true
+attendant-polish-message,true
+attendant-smart-replies,true
+attendant-auto-summary,true
+attendant-sentiment-analysis,true
+
+# Optional: Set bot personality for context
+bot-system-prompt,You are a friendly customer service assistant for Acme Corp
+bot-description,Premium support for enterprise customers
+```
+
+### Selective Enablement
+
+Enable only the features you need:
+
+```csv
+name,value
+attendant-smart-replies,true
+attendant-sentiment-analysis,true
+```
+
+---
+
+## Feature Details
+
+### 1. Real-time Tips (`attendant-llm-tips`)
+
+When a customer sends a message, the LLM analyzes it and provides actionable tips to the attendant.
+
+#### Tip Types
+
+| Type | Icon | Description |
+|------|------|-------------|
+| `intent` | 🎯 | What the customer wants |
+| `action` | ✅ | Suggested action to take |
+| `warning` | ⚠️ | Sentiment or escalation concern |
+| `knowledge` | 📚 | Relevant info to share |
+| `history` | 📜 | Insight from conversation history |
+| `general` | 💡 | General helpful advice |
+
+#### Example Tips
+
+Customer says: *"This is ridiculous! I've been waiting 3 days for a response!"*
+
+Tips generated:
+- ⚠️ Customer is frustrated - use empathetic language and apologize
+- 🎯 Customer has been waiting for support response
+- ✅ Acknowledge the delay and provide immediate assistance
+
+#### API Usage
+
+```basic
+' Internal API - automatically called by UI
+POST /api/attendance/llm/tips
+{
+    "session_id": "uuid",
+    "customer_message": "message text",
+    "history": [{"role": "customer", "content": "..."}]
+}
+```
+
+---
+
+### 2. Message Polish (`attendant-polish-message`)
+
+Before sending, attendants can polish their message with one click. The LLM improves grammar, clarity, and tone while preserving the original meaning.
+
+#### Supported Tones
+
+- `professional` (default)
+- `friendly`
+- `empathetic`
+- `formal`
+
+#### Example
+
+**Original:** *"ya we can do that but u need to wait til tmrw"*
+
+**Polished:** *"Yes, we can certainly help with that! Please allow until tomorrow for us to process your request."*
+
+**Changes:** Fixed grammar, improved clarity, added professional tone
+
+#### API Usage
+
+```basic
+POST /api/attendance/llm/polish
+{
+    "session_id": "uuid",
+    "message": "original message",
+    "tone": "professional"
+}
+```
+
+**Response:**
+```json
+{
+    "success": true,
+    "original": "ya we can do that...",
+    "polished": "Yes, we can certainly...",
+    "changes": ["Fixed grammar", "Improved tone"]
+}
+```
+
+---
+
+### 3. Smart Replies (`attendant-smart-replies`)
+
+Generate three contextually appropriate reply suggestions based on the conversation history and bot personality.
+
+#### Reply Categories
+
+- `greeting` - Opening responses
+- `answer` - Direct answers to questions
+- `acknowledgment` - Empathetic acknowledgments
+- `solution` - Problem-solving responses
+- `follow_up` - Continuation questions
+- `closing` - Conversation wrap-up
+
+#### Example
+
+Customer: *"How do I reset my password?"*
+
+**Suggested Replies:**
+
+1. **Empathetic:** "I understand how frustrating it can be when you can't access your account. I'll help you reset your password right away."
+
+2. **Solution-focused:** "To reset your password, please go to the login page and click 'Forgot Password'. You'll receive an email with reset instructions."
+
+3. **Follow-up:** "I can help you with that! Are you trying to reset the password for your main account or a sub-account?"
+
+#### API Usage
+
+```basic
+POST /api/attendance/llm/smart-replies
+{
+    "session_id": "uuid",
+    "history": [
+        {"role": "customer", "content": "How do I reset my password?"},
+        {"role": "attendant", "content": "Hi! Let me help you with that."}
+    ]
+}
+```
+
+---
+
+### 4. Auto Summary (`attendant-auto-summary`)
+
+When an attendant takes a conversation, they receive an instant summary of what's happened so far. This is especially useful for:
+
+- Long conversations
+- Transfers between attendants
+- Complex multi-issue discussions
+
+#### Summary Contents
+
+| Field | Description |
+|-------|-------------|
+| `brief` | One-sentence overview |
+| `key_points` | Main discussion points |
+| `customer_needs` | What the customer wants |
+| `unresolved_issues` | Open items |
+| `sentiment_trend` | Improving/stable/declining |
+| `recommended_action` | What to do next |
+| `message_count` | Number of messages |
+| `duration_minutes` | Conversation length |
+
+#### Example Summary
+
+```json
+{
+    "brief": "Customer requesting refund for damaged product received yesterday",
+    "key_points": [
+        "Order #12345 arrived damaged",
+        "Customer sent photos as proof",
+        "Previous agent offered replacement"
+    ],
+    "customer_needs": [
+        "Full refund instead of replacement",
+        "Confirmation email"
+    ],
+    "unresolved_issues": [
+        "Refund approval pending"
+    ],
+    "sentiment_trend": "stable",
+    "recommended_action": "Escalate to supervisor for refund approval"
+}
+```
+
+#### API Usage
+
+```basic
+GET /api/attendance/llm/summary/{session_id}
+```
+
+---
+
+### 5. Sentiment Analysis (`attendant-sentiment-analysis`)
+
+Real-time analysis of customer emotional state to help attendants respond appropriately.
+
+#### Analysis Components
+
+| Component | Values | Description |
+|-----------|--------|-------------|
+| `overall` | positive, neutral, negative | General sentiment |
+| `score` | -1.0 to 1.0 | Numeric sentiment score |
+| `emotions` | List | Detected emotions with intensity |
+| `escalation_risk` | low, medium, high | Risk of escalation |
+| `urgency` | low, normal, high, urgent | Message urgency |
+| `emoji` | 😊😐😟 | Visual indicator |
+
+#### Example Analysis
+
+**Customer message:** *"I've been trying to get help for TWO WEEKS! This is absolutely unacceptable!"*
+
+```json
+{
+    "overall": "negative",
+    "score": -0.8,
+    "emotions": [
+        {"name": "frustration", "intensity": 0.9},
+        {"name": "anger", "intensity": 0.7}
+    ],
+    "escalation_risk": "high",
+    "urgency": "high",
+    "emoji": "😟"
+}
+```
+
+The UI shows a warning: ⚠️ High escalation risk detected
+
+#### API Usage
+
+```basic
+POST /api/attendance/llm/sentiment
+{
+    "session_id": "uuid",
+    "message": "customer message",
+    "history": []
+}
+```
+
+---
+
+## WhatsApp Attendant Commands
+
+Attendants using WhatsApp can access LLM assist features via commands:
+
+### Queue Management
+
+| Command | Description |
+|---------|-------------|
+| `/queue` or `/fila` | View waiting conversations |
+| `/take` or `/pegar` | Take next conversation |
+| `/status [online\|busy\|away\|offline]` | Set your status |
+| `/transfer @name` or `/transferir` | Transfer conversation |
+| `/resolve` or `/resolver` | Mark as resolved |
+
+### AI Assistance
+
+| Command | Description |
+|---------|-------------|
+| `/tips` or `/dicas` | Get tips for current conversation |
+| `/polish <message>` or `/polir` | Polish a message before sending |
+| `/replies` or `/respostas` | Get smart reply suggestions |
+| `/summary` or `/resumo` | Get conversation summary |
+| `/help` or `/ajuda` | Show all commands |
+
+### Example Usage
+
+```
+Attendant: /queue
+Bot: 📋 Queue (3 waiting)
+     1. John Smith (whatsapp)
+        Status: waiting | ID: abc123
+     2. Maria Santos (web)
+        Status: waiting | ID: def456
+     ...
+
+Attendant: /take
+Bot: ✅ Conversation assigned
+     Customer: John Smith
+     Session: abc123
+     
+Attendant: /tips
+Bot: 💡 Tips for this conversation
+
+     🎯 Customer is asking about billing
+     ✅ Check their account status before responding
+     ⚠️ Previous conversation ended unresolved
+     
+Attendant: /polish thank u for waiting ill check ur account now
+Bot: ✨ Polished message
+
+     "Thank you for your patience! I'll check your account right now."
+     
+     Changes:
+     • Fixed grammar
+     • Improved professionalism
+     
+Attendant: /resolve
+Bot: ✅ Conversation resolved
+     Session abc123 marked as resolved.
+```
+
+---
+
+## Web Attendant Console
+
+The web attendant console (`/suite/attendant/`) integrates LLM assist features directly:
+
+### Insights Panel
+
+The right sidebar shows:
+- **Customer Sentiment** - Real-time with emoji indicator
+- **Detected Intent** - What the customer wants
+- **Conversation Summary** - Auto-generated when you select a conversation
+
+### Suggested Replies
+
+Below the insights, three AI-generated reply suggestions appear. Click any suggestion to insert it into the message input.
+
+### Polish Button
+
+The ✨ button next to the message input polishes your text before sending.
+
+### Tips Notifications
+
+When a customer sends a message:
+1. Tips appear in the insights panel
+2. High-priority tips show as toast notifications
+3. Warning tips (escalation risk) are highlighted
+
+---
+
+## Bot Personality Integration
+
+LLM assist uses your bot's personality when generating suggestions. Set this in `config.csv`:
+
+```csv
+name,value
+bot-system-prompt,You are a friendly tech support agent for CloudSoft Inc. Be helpful and patient.
+bot-description,Enterprise software support
+```
+
+Or in your `start.bas` header:
+
+```basic
+REM CloudSoft Support Bot
+REM Friendly, patient, and technically knowledgeable
+REM Always offer to escalate complex issues
+
+TALK "Welcome to CloudSoft Support!"
+```
+
+The LLM reads these comments to understand the bot's personality and applies the same tone to:
+- Smart reply suggestions
+- Message polishing
+- Tips generation
+
+---
+
+## API Reference
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/attendance/llm/tips` | Generate tips |
+| POST | `/api/attendance/llm/polish` | Polish message |
+| POST | `/api/attendance/llm/smart-replies` | Generate replies |
+| GET | `/api/attendance/llm/summary/{session_id}` | Get summary |
+| POST | `/api/attendance/llm/sentiment` | Analyze sentiment |
+| GET | `/api/attendance/llm/config/{bot_id}` | Get config |
+
+### Check Configuration
+
+```basic
+GET /api/attendance/llm/config/{bot_id}
+
+Response:
+{
+    "tips_enabled": true,
+    "polish_enabled": true,
+    "smart_replies_enabled": true,
+    "auto_summary_enabled": true,
+    "sentiment_enabled": true,
+    "any_enabled": true
+}
+```
+
+---
+
+## Fallback Behavior
+
+When LLM is unavailable, the system provides fallback functionality:
+
+| Feature | Fallback |
+|---------|----------|
+| Tips | Keyword-based analysis (urgent, problem, question) |
+| Polish | Returns original message |
+| Smart Replies | Generic template replies |
+| Summary | Basic message count and duration |
+| Sentiment | Keyword-based positive/negative detection |
+
+---
+
+## Best Practices
+
+### 1. Start with Smart Replies
+
+If you're unsure which features to enable, start with `attendant-smart-replies`. It provides immediate value with low overhead.
+
+### 2. Enable Sentiment for High-Volume Support
+
+For teams handling many conversations, `attendant-sentiment-analysis` helps prioritize frustrated customers.
+
+### 3. Use Polish for Quality Consistency
+
+Enable `attendant-polish-message` to ensure consistent, professional communication regardless of individual writing skills.
+
+### 4. Tips for Complex Products
+
+For products with many features or complex workflows, `attendant-llm-tips` helps attendants quickly understand context.
+
+### 5. Summary for Shift Changes
+
+Enable `attendant-auto-summary` if your team has shift changes or frequent transfers between attendants.
+
+---
+
+## Troubleshooting
+
+### "Feature is disabled" Message
+
+Add the feature to your `config.csv`:
+
+```csv
+attendant-smart-replies,true
+```
+
+### Slow Response Times
+
+LLM calls add latency. If responses are slow:
+- Use a faster LLM model
+- Enable only essential features
+- Check your `llm-url` configuration
+
+### Generic Suggestions
+
+If suggestions seem generic:
+- Set `bot-system-prompt` in config.csv
+- Add personality comments to `start.bas`
+- Ensure conversation history is being passed
+
+### WhatsApp Commands Not Working
+
+1. Verify the attendant is registered in `attendant.csv`
+2. Check that the phone number matches exactly
+3. Ensure `crm-enabled,true` is set
+
+---
+
+## See Also
+
+- [Transfer to Human](./transfer-to-human.md) - Bot-to-human handoff
+- [Attendance Queue](../appendix-external-services/attendance-queue.md) - Queue configuration
+- [LLM Configuration](../chapter-08-config/llm-config.md) - LLM setup
+- [config.csv Format](../chapter-08-config/config-csv.md) - Configuration reference
--- a/src/chapter-11-features/transfer-to-human.md
+++ b/src/chapter-11-features/transfer-to-human.md
@ -0,0 +1,634 @@
+# Transfer to Human
+
+The `TRANSFER TO HUMAN` keyword enables seamless handoff from bot conversations to human attendants. This is a critical feature for hybrid support workflows where complex issues require human intervention.
+
+## Overview
+
+When a conversation requires human attention—whether due to customer request, issue complexity, or emotional escalation—the bot can transfer the conversation to a human attendant using the `TRANSFER TO HUMAN` keyword.
+
+The system sets `needs_human = true` in the session context, which routes all subsequent messages from that customer to human attendants instead of the bot.
+
+## How It Works
+
+```
+Customer Message → Check needs_human
+                        ↓
+        ┌───────────────┴───────────────┐
+        ↓                               ↓
+  needs_human=false               needs_human=true
+        ↓                               ↓
+   Bot Processing              Human Attendant
+        ↓                               ↓
+  TRANSFER TO HUMAN?            Respond via
+        ↓                       Console/WhatsApp
+  Set needs_human=true                ↓
+        ↓                       /resolve command
+  Notify Attendants                   ↓
+                              needs_human=false
+                                      ↓
+                              Back to Bot
+```
+
+## Configuration
+
+### Enable CRM Features
+
+Add the following to your bot's `config.csv`:
+
+```csv
+name,value
+
+# Required: Enable CRM/Transfer functionality
+crm-enabled,true
+
+# Optional: Enable LLM-assisted attendant features
+attendant-llm-tips,true
+attendant-polish-message,true
+attendant-smart-replies,true
+attendant-auto-summary,true
+attendant-sentiment-analysis,true
+```
+
+The `crm-enabled` setting activates:
+- Transfer to human functionality
+- Attendant queue management
+- WebSocket notifications
+- LLM assist features (if configured)
+
+### Configure Attendants
+
+Create `attendant.csv` in your bot's `.gbai` folder:
+
+```csv
+id,name,channel,preferences,department,aliases
+att-001,John Smith,all,sales,commercial,john;johnny;js
+att-002,Jane Doe,web,support,customer-service,jane
+att-003,Bob Wilson,whatsapp,technical,engineering,bob;bobby
+att-004,Maria Santos,all,collections,finance,maria
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Unique identifier for the attendant |
+| `name` | Display name shown to customers |
+| `channel` | Channel they handle: `all`, `web`, `whatsapp`, `teams`, etc. |
+| `preferences` | Type of work they prefer |
+| `department` | Department for routing |
+| `aliases` | Semicolon-separated nicknames for name matching |
+
+---
+
+## The `needs_human` Flag
+
+When `TRANSFER TO HUMAN` is called, the system sets `needs_human = true` in the session's context data. This flag controls message routing:
+
+| `needs_human` Value | Behavior |
+|---------------------|----------|
+| `false` (default) | Messages go to bot for processing |
+| `true` | Messages go to human attendant |
+
+### Checking the Flag in BASIC
+
+```basic
+' Check if conversation needs human
+IF session.needs_human THEN
+    TALK "You're connected to our support team."
+ELSE
+    TALK "I'm your AI assistant. How can I help?"
+END IF
+```
+
+### Manual Flag Control (Advanced)
+
+```basic
+' Force transfer without using keyword
+SET SESSION "needs_human", true
+SET SESSION "transfer_reason", "Customer requested human"
+
+' Return to bot mode (usually done by attendant via /resolve)
+SET SESSION "needs_human", false
+```
+
+---
+
+## Basic Usage
+
+### Transfer to Any Available Attendant
+
+```basic
+' Simple transfer to next available human
+TRANSFER TO HUMAN
+
+TALK result.message
+```
+
+### Transfer to Specific Person
+
+```basic
+' Transfer to a specific attendant by name
+TRANSFER TO HUMAN "John Smith"
+
+' Also works with aliases
+TRANSFER TO HUMAN "johnny"
+
+' Or by ID
+TRANSFER TO HUMAN "att-001"
+```
+
+### Transfer to Department
+
+```basic
+' Transfer to sales department
+TRANSFER TO HUMAN "sales"
+
+' Transfer with priority
+result = TRANSFER TO HUMAN "support", "high"
+
+IF result.success THEN
+    TALK "You are now connected to " + result.assigned_to_name
+ELSE
+    TALK result.message
+END IF
+```
+
+### Transfer with Context
+
+```basic
+' Transfer with department, priority, and context
+TRANSFER TO HUMAN "technical", "urgent", "Customer needs help with API integration"
+```
+
+---
+
+## Advanced Usage
+
+### Extended Transfer with Named Parameters
+
+```basic
+' Using transfer_to_human_ex for full control
+params = #{
+    name: "John",
+    department: "support",
+    priority: "high",
+    reason: "Complex billing issue",
+    context: "Customer has been a member since 2020, premium tier"
+}
+
+result = transfer_to_human_ex(params)
+
+IF result.success THEN
+    TALK "Transferring you to " + result.assigned_to_name
+    TALK "Estimated wait time: " + result.estimated_wait_seconds + " seconds"
+ELSE
+    TALK "Sorry, " + result.message
+END IF
+```
+
+### Conditional Transfer
+
+```basic
+' Transfer based on conversation context
+sentiment = ANALYZE SENTIMENT conversation
+
+IF sentiment.score < -0.5 THEN
+    ' Frustrated customer - high priority
+    TRANSFER TO HUMAN "support", "urgent", "Customer appears frustrated"
+ELSE IF topic = "billing" THEN
+    TRANSFER TO HUMAN "billing"
+ELSE IF topic = "technical" THEN
+    TRANSFER TO HUMAN "technical"
+ELSE
+    TRANSFER TO HUMAN
+END IF
+```
+
+### Check Availability Before Transfer
+
+```basic
+' Check if any attendants are available
+attendants = GET "/api/attendance/attendants"
+
+available = 0
+FOR EACH att IN attendants
+    IF att.status = "online" THEN
+        available = available + 1
+    END IF
+NEXT
+
+IF available > 0 THEN
+    TRANSFER TO HUMAN
+ELSE
+    TALK "Our team is currently unavailable. Would you like to:"
+    TALK "1. Leave a message"
+    TALK "2. Schedule a callback"
+    TALK "3. Continue with our AI assistant"
+    HEAR choice
+END IF
+```
+
+---
+
+## Transfer Result
+
+The `TRANSFER TO HUMAN` keyword returns a result object:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `success` | Boolean | Whether the transfer was successful |
+| `status` | String | Status: `queued`, `assigned`, `connected`, `no_attendants`, `crm_disabled`, `attendant_not_found`, `error` |
+| `queue_position` | Integer | Position in queue (if queued) |
+| `assigned_to` | String | Attendant ID (if assigned) |
+| `assigned_to_name` | String | Attendant name (if assigned) |
+| `estimated_wait_seconds` | Integer | Estimated wait time |
+| `message` | String | Human-readable message |
+
+### Handling Different Statuses
+
+```basic
+result = TRANSFER TO HUMAN "sales"
+
+SELECT CASE result.status
+    CASE "assigned"
+        TALK "Great news! " + result.assigned_to_name + " will be with you shortly."
+        
+    CASE "queued"
+        TALK "You are #" + result.queue_position + " in line."
+        TALK "Estimated wait: " + (result.estimated_wait_seconds / 60) + " minutes."
+        
+    CASE "connected"
+        TALK "You are now connected with " + result.assigned_to_name
+        
+    CASE "no_attendants"
+        TALK "No attendants are currently available."
+        TALK "Would you like to leave a message?"
+        
+    CASE "attendant_not_found"
+        TALK "That person is not available. Let me find someone else."
+        TRANSFER TO HUMAN
+        
+    CASE "crm_disabled"
+        TALK "I'm sorry, human support is not configured for this bot."
+        
+    CASE ELSE
+        TALK "Something went wrong. Please try again."
+END SELECT
+```
+
+---
+
+## LLM Tool Integration
+
+The `TRANSFER TO HUMAN` keyword is automatically registered as an LLM tool, allowing the AI to decide when to transfer:
+
+### Tool Schema
+
+```json
+{
+    "name": "transfer_to_human",
+    "description": "Transfer the conversation to a human attendant. Use when the customer explicitly asks to speak with a person, when the issue is too complex, or when emotional support is needed.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "If someone wants to talk to somebody specific, provide their name or alias"
+            },
+            "department": {
+                "type": "string",
+                "description": "Department to transfer to: sales, support, technical, billing, etc."
+            },
+            "priority": {
+                "type": "string",
+                "enum": ["normal", "high", "urgent"],
+                "default": "normal"
+            },
+            "reason": {
+                "type": "string",
+                "description": "Brief reason for the transfer"
+            }
+        }
+    }
+}
+```
+
+### AI-Initiated Transfer Example
+
+When a customer says "I want to talk to a real person," the LLM can automatically invoke:
+
+```json
+{
+    "tool": "transfer_to_human",
+    "arguments": {
+        "reason": "Customer requested human assistance"
+    }
+}
+```
+
+---
+
+## Priority Levels
+
+| Priority | Value | Use Case |
+|----------|-------|----------|
+| `low` | 0 | Non-urgent inquiries |
+| `normal` | 1 | Standard requests (default) |
+| `high` | 2 | Important customers, time-sensitive issues |
+| `urgent` | 3 | Escalations, complaints, VIP customers |
+
+Higher priority conversations are served first in the queue.
+
+---
+
+## Attendant Status
+
+Attendants can have the following statuses:
+
+| Status | Description |
+|--------|-------------|
+| `online` | Available and ready for conversations |
+| `busy` | Currently handling conversations |
+| `away` | Temporarily unavailable |
+| `offline` | Not working |
+
+Only `online` attendants receive new conversation assignments.
+
+---
+
+## Queue Status
+
+Conversations in the queue have these statuses:
+
+| Status | Description |
+|--------|-------------|
+| `waiting` | Waiting for an attendant |
+| `assigned` | Assigned but not yet active |
+| `active` | Conversation in progress |
+| `resolved` | Conversation completed |
+| `abandoned` | Customer left before assignment |
+
+---
+
+## REST API Endpoints
+
+### Queue Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/attendance/queue` | GET | List conversations in queue |
+| `/api/attendance/attendants` | GET | List all attendants |
+| `/api/attendance/assign` | POST | Assign conversation to attendant |
+| `/api/attendance/transfer` | POST | Transfer between attendants |
+| `/api/attendance/resolve/:session_id` | POST | Mark conversation resolved |
+| `/api/attendance/insights` | GET | Get queue insights |
+
+### Example: Manual Transfer via API
+
+```basic
+' Transfer using direct API call
+body = #{
+    session_id: session.id,
+    from_attendant_id: "att-001",
+    to_attendant_id: "att-002",
+    reason: "Specialist needed for technical issue"
+}
+
+result = POST "/api/attendance/transfer", body
+```
+
+---
+
+## Attendant Console
+
+When CRM is enabled, the **Attendant Console** becomes available at `/suite/attendant/`. This provides a full-featured interface for human agents:
+
+### Features
+
+- **Queue Management**: View and filter waiting conversations
+- **Real-time Updates**: WebSocket-powered live updates
+- **AI Insights**: Sentiment analysis, intent detection, suggested replies
+- **Transfer**: Transfer conversations between attendants
+- **Customer Details**: View customer history and information
+- **Quick Responses**: Pre-configured response templates
+
+### Accessing the Console
+
+1. Enable `crm-enabled,true` in config.csv
+2. Create `attendant.csv` with your team
+3. Navigate to `/suite/attendant/` or click "Attendant" in the Suite menu
+
+---
+
+## WhatsApp Attendant Mode
+
+Attendants can manage conversations directly from WhatsApp using commands:
+
+### Queue Commands
+
+| Command | Description |
+|---------|-------------|
+| `/queue` or `/fila` | View waiting conversations |
+| `/take` or `/pegar` | Take next conversation |
+| `/status [online\|busy\|away\|offline]` | Set availability |
+| `/transfer @name` or `/transferir` | Transfer to another attendant |
+| `/resolve` or `/resolver` | Mark complete, set `needs_human=false` |
+
+### AI Assist Commands
+
+| Command | Description |
+|---------|-------------|
+| `/tips` or `/dicas` | Get AI tips for current conversation |
+| `/polish <msg>` or `/polir` | Polish message before sending |
+| `/replies` or `/respostas` | Get 3 smart reply suggestions |
+| `/summary` or `/resumo` | Get conversation summary |
+| `/help` or `/ajuda` | Show all commands |
+
+### Example WhatsApp Session
+
+```
+Attendant: /queue
+Bot: 📋 Queue (2 waiting)
+     1. João Silva (whatsapp) - Status: waiting
+     2. Maria Santos (web) - Status: waiting
+
+Attendant: /take
+Bot: ✅ Conversation assigned
+     Customer: João Silva
+     Session: abc12345
+
+[Customer message arrives]
+Customer: Preciso de ajuda com meu pedido
+
+Attendant: /tips
+Bot: 💡 Tips:
+     🎯 Customer needs help with order
+     ✅ Ask for order number
+     📚 Check order status in system
+
+Attendant: /polish oi joao, vou verificar seu pedido agora
+Bot: ✨ Polished:
+     "Olá João! Vou verificar seu pedido agora mesmo."
+
+Attendant: Olá João! Vou verificar seu pedido agora mesmo.
+[Message sent to customer]
+
+Attendant: /resolve
+Bot: ✅ Conversation resolved
+     Customer returned to bot mode.
+```
+
+---
+
+## Best Practices
+
+### 1. Set Clear Expectations
+
+```basic
+result = TRANSFER TO HUMAN
+
+IF result.success AND result.status = "queued" THEN
+    TALK "You're now in line to speak with a team member."
+    TALK "Your position: #" + result.queue_position
+    TALK "While you wait, I can still help with simple questions."
+END IF
+```
+
+### 2. Provide Context to Attendants
+
+```basic
+' Build context from conversation
+context = "Customer inquiry about: " + detected_topic + ". "
+context = context + "Sentiment: " + sentiment + ". "
+context = context + "Key entities: " + entities.join(", ")
+
+TRANSFER TO HUMAN "support", "normal", context
+```
+
+### 3. Handle Off-Hours
+
+```basic
+' Check business hours
+hour = HOUR(NOW())
+day = WEEKDAY(NOW())
+
+IF day >= 1 AND day <= 5 AND hour >= 9 AND hour < 18 THEN
+    TRANSFER TO HUMAN
+ELSE
+    TALK "Our team is available Monday-Friday, 9 AM - 6 PM."
+    TALK "Would you like to leave a message or schedule a callback?"
+END IF
+```
+
+### 4. VIP Routing
+
+```basic
+' Check if customer is VIP
+customer = FIND "customers", "email='" + user.email + "'"
+
+IF customer.tier = "premium" OR customer.tier = "enterprise" THEN
+    TRANSFER TO HUMAN "vip-support", "high", "Premium customer"
+ELSE
+    TRANSFER TO HUMAN
+END IF
+```
+
+---
+
+## Troubleshooting
+
+### "CRM not enabled" Error
+
+Add `crm-enabled,true` to your config.csv file.
+
+### "No attendants configured" Error
+
+Create `attendant.csv` in your bot's `.gbai` folder with at least one attendant.
+
+### Transfer Not Finding Attendant by Name
+
+- Check that the name or alias is spelled correctly
+- Verify the attendant exists in `attendant.csv`
+- Aliases are case-insensitive and separated by semicolons
+
+### Queue Not Updating
+
+- Ensure WebSocket connection is active
+- Check that the attendant status is `online`
+- Verify the bot has proper database permissions
+
+---
+
+## Analytics & Insights
+
+The attendance system provides analytics through the API:
+
+### Queue Insights
+
+```basic
+GET /api/attendance/insights/{session_id}
+
+Response:
+{
+    "session_id": "uuid",
+    "sentiment": "neutral",
+    "message_count": 15,
+    "suggested_reply": "How can I help?",
+    "key_topics": ["billing", "refund"],
+    "priority": "normal",
+    "language": "pt"
+}
+```
+
+### LLM-Powered Analytics
+
+When `attendant-sentiment-analysis` is enabled:
+
+```basic
+POST /api/attendance/llm/sentiment
+
+Response:
+{
+    "overall": "negative",
+    "score": -0.6,
+    "emotions": [{"name": "frustration", "intensity": 0.8}],
+    "escalation_risk": "high",
+    "urgency": "high",
+    "emoji": "😟"
+}
+```
+
+---
+
+## Troubleshooting
+
+### Customer Stuck in Human Mode
+
+If a customer is stuck with `needs_human=true` after the issue is resolved:
+
+1. Attendant uses `/resolve` command
+2. Or manually via API:
+```basic
+POST /api/attendance/resolve/{session_id}
+```
+
+### Messages Not Reaching Attendant
+
+1. Check `crm-enabled,true` in config.csv
+2. Verify attendant.csv exists with valid entries
+3. Ensure attendant status is `online`
+4. Check WebSocket connection in browser console
+
+### Attendant Commands Not Working on WhatsApp
+
+1. Verify phone number is in attendant.csv
+2. Phone must match exactly (with country code)
+3. Check that bot is receiving webhooks
+
+---
+
+## See Also
+
+- [LLM-Assisted Attendant](./attendant-llm-assist.md) - AI copilot features
+- [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Full queue configuration
+- [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md) - Approval workflows
+- [CRM Automations](../appendix-external-services/attendance-queue.md#crm-automations) - Sales, collections, scheduling
+- [WhatsApp Setup](../chapter-04-gbui/how-to/connect-whatsapp.md) - Channel configuration
--- a/src/executive-vision.md
+++ b/src/executive-vision.md
@ -4,11 +4,28 @@

 General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovereignty. Own your infrastructure, control your data, deploy anywhere.

+---
+
+## INVESTOR HIGHLIGHTS
+
+| **Differentiator** | **What Sets Us Apart** |
+|-------------------|------------------------|
+| **LLM Orchestrator** | Single PROMPT.md per project defines bot personality across all channels and features |
+| **Hybrid AI+Human** | Seamless bot-to-human handoff with AI-assisted attendants |
+| **True Omnichannel** | WhatsApp, Teams, Instagram, Telegram, Web - ONE codebase, ONE personality |
+| **No Vendor Lock-in** | Self-hosted, export anytime, migrate freely |
+| **Industry-Standard CRM** | Built-in collections, scheduling, follow-ups, sales automation |
+
+---
+
 ## FEATURE OVERVIEW

 | **CAPABILITY** | **WHAT IT DOES** | **BUSINESS IMPACT** | **TIME TO VALUE** |
 |----------------|------------------|---------------------|-------------------|
-| **AI-POWERED CONVERSATIONS** | Multi-channel bot orchestration with LLM integration (GPT-4, Claude, Llama, DeepSeek) | Significant reduction in customer service costs | < 1 hour |
+| **AI-POWERED CONVERSATIONS** | Multi-channel bot orchestration with any LLM (OpenAI, Anthropic, Groq, local models) | Significant reduction in customer service costs | < 1 hour |
+| **LLM-ASSISTED ATTENDANTS** | Real-time tips, smart replies, message polish, sentiment analysis for human agents | 50% faster response times | Immediate |
+| **TRANSFER TO HUMAN** | Seamless bot-to-human handoff with full context | Hybrid support workflows | 5 minutes |
+| **WHATSAPP ATTENDANT** | Human agents respond via WhatsApp with /commands | Mobile workforce support | Immediate |
 | **KNOWLEDGE BASES** | Vector-indexed document collections with semantic search (Qdrant/FAISS) | Faster information retrieval | 15 minutes |
 | **EMAIL AUTOMATION** | Full IMAP/SMTP integration with intelligent routing | Automated inbox management | 5 minutes |
 | **LLM-ASSISTED BASIC** | Plain English programming with LLM code generation | No programming skills needed | Immediate |
@ -31,6 +48,32 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere
 | **API GATEWAY** | REST, GraphQL, Webhooks, WebSocket support | Integration ready | Ready |
 | **USER DIRECTORY** | LDAP/AD replacement, SSO, group management | Central authentication | 15 minutes |
 | **VOICE PROCESSING** | Speech-to-text, text-to-speech, voice commands | Voice interfaces | 5 minutes |
+| **CRM AUTOMATIONS** | Follow-ups, collections, scheduling, sales pipelines | Revenue operations | 10 minutes |
+
+---
+
+## LLM-ASSISTED ATTENDANT FEATURES
+
+When conversations transfer from bot to human, the LLM continues working as a copilot:
+
+| **Feature** | **Description** | **Investor Appeal** |
+|-------------|-----------------|---------------------|
+| **Real-time Tips** | AI analyzes customer message and provides actionable tips | "AI copilot for support" |
+| **Message Polish** | One-click grammar and tone improvement | Reduces training costs |
+| **Smart Replies** | 3 contextual reply suggestions | 50% faster responses |
+| **Auto Summary** | Instant conversation summary on handoff | Faster transfers |
+| **Sentiment Analysis** | Real-time emotional state + escalation warnings | Prevent churn |
+
+**WhatsApp Commands for Attendants:**
+```
+/queue    - View waiting customers
+/take     - Take next conversation
+/tips     - Get AI tips
+/polish   - Improve message
+/replies  - Get suggestions
+/summary  - Conversation summary
+/resolve  - Mark complete
+```

 ## DEPLOYMENT OPTIONS

@ -52,6 +95,18 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere
 - Move between hosting options freely
 - No vendor lock-in

+---
+
+## COMPETITIVE ADVANTAGE
+
+| **vs Competitors** | **General Bots Advantage** |
+|--------------------|---------------------------|
+| **Zendesk/Intercom** | Self-hosted, AI-first, no per-seat pricing |
+| **Dialogflow** | Native WhatsApp, human handoff, CRM built-in |
+| **Botpress** | LLM orchestration, multi-channel, enterprise features |
+| **n8n/Zapier** | Conversational AI, not just workflows |
+| **Custom Development** | 90% faster deployment, proven architecture |
+
 ## TECHNICAL ARCHITECTURE

 | **COMPONENT** | **TECHNOLOGY** | **PERFORMANCE** |
@ -92,12 +147,38 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere
 ### Enterprise Edition
 - All Standard features plus:
 - Compliance monitoring (LGPD/GDPR/HIPAA)
- Attendance tracking
+- Attendance tracking with LLM assist
 - Vector database (Qdrant)
 - NVIDIA GPU acceleration
 - Advanced monitoring
 - gRPC support
 - Multi-channel messaging (WhatsApp, Teams, Instagram)
+- Human handoff with AI copilot
+- CRM automations (collections, scheduling, sales)
+
+---
+
+## QUICK START
+
+```csv
+# config.csv - Enable all features
+name,value
+crm-enabled,true
+attendant-llm-tips,true
+attendant-polish-message,true
+attendant-smart-replies,true
+attendant-auto-summary,true
+attendant-sentiment-analysis,true
+```
+
+```csv
+# attendant.csv - Configure your team
+id,name,channel,preferences,department,aliases
+att-001,John Smith,all,sales,commercial,john;johnny
+att-002,Maria Santos,whatsapp,support,customer-service,maria
+```
+
+**Result:** Full hybrid AI+Human support system in minutes.

 ### Full Edition
 - All features enabled