GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Refactor: CRM automations, monitoring homepage, webhook examples, docs standards

Browse source 
- Environment Variables: Simplified to ONLY VAULT_* vars, everything else in config.csv
- Attendant Module: Added CRM automations (follow-ups, collections/cobranças, scheduling/agendamentos, sales/vendas)
- NEW: Hosting, DNS, MDA integration docs (Namecheap, Stalwart, LLM providers)
- Monitoring: Updated as live operations homepage with real data endpoints
- Examples: Renamed to 'Webhook Integrations and Jobs', removed loop-based examples 1 & 5, added lead nurturing, payment collection, appointment scheduling
- Documentation Standards: WhatsApp HTML style as canonical conversation format, SVG for interfaces
- Reading Flow: Improved Executive Vision → Quick Start → Chapter 01 transitions with navigation tables
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-03 21:59:49 -03:00
parent 292d6625b7
commit 2110995b7f
11 changed files with 1692 additions and 796 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
src/SUMMARY.md
View file

@ -112,7 +112,7 @@
- [store.bas](./chapter-06-gbdialog/templates/store.md) - [store.bas](./chapter-06-gbdialog/templates/store.md)
- [talk-to-data.bas](./chapter-06-gbdialog/templates/talk-to-data.md) - [talk-to-data.bas](./chapter-06-gbdialog/templates/talk-to-data.md)
- [whatsapp.bas](./chapter-06-gbdialog/templates/whatsapp.md) - [whatsapp.bas](./chapter-06-gbdialog/templates/whatsapp.md)
- [Consolidated Examples](./chapter-06-gbdialog/examples-consolidated.md) - [Webhook Integrations and Jobs](./chapter-06-gbdialog/examples-consolidated.md)
- [Data Sync Tools](./chapter-06-gbdialog/tools-data-sync.md) - [Data Sync Tools](./chapter-06-gbdialog/tools-data-sync.md)
- [Keywords Reference](./chapter-06-gbdialog/keywords.md) - [Keywords Reference](./chapter-06-gbdialog/keywords.md)
- [TALK](./chapter-06-gbdialog/keyword-talk.md) - [TALK](./chapter-06-gbdialog/keyword-talk.md)
@ -357,6 +357,7 @@
- [Storage Services](./appendix-external-services/storage.md) - [Storage Services](./appendix-external-services/storage.md)
- [Directory Services](./appendix-external-services/directory.md) - [Directory Services](./appendix-external-services/directory.md)
- [Attendance Queue](./appendix-external-services/attendance-queue.md) - [Attendance Queue](./appendix-external-services/attendance-queue.md)
- [Hosting, DNS, and MDA](./appendix-external-services/hosting-dns.md)
- [Time-Series Database](./appendix-external-services/timeseries.md) - [Time-Series Database](./appendix-external-services/timeseries.md)
- [NVIDIA GPU](./appendix-external-services/nvidia.md) - [NVIDIA GPU](./appendix-external-services/nvidia.md)
- [Multimodal](./appendix-external-services/multimodal.md) - [Multimodal](./appendix-external-services/multimodal.md)
@ -365,6 +366,7 @@
- [Appendix C: Environment Variables](./appendix-env-vars/README.md) - [Appendix C: Environment Variables](./appendix-env-vars/README.md)
- [Appendix D: Documentation Style](./appendix-docs-style/conversation-examples.md) - [Appendix D: Documentation Style](./appendix-docs-style/conversation-examples.md)
- [SVG and Conversation Standards](./appendix-docs-style/svg.md)
[Glossary](./glossary.md) [Glossary](./glossary.md)
[Contact](./contact/README.md) [Contact](./contact/README.md)

191
src/appendix-docs-style/svg.md Normal file
View file

@ -0,0 +1,191 @@
# Documentation Style Standards
All interface layouts in this documentation use SVG-based wireframe representations for screenshots and diagrams. Conversation examples use the WhatsApp-style HTML format for consistent, visually appealing rendering.
---
## Interface Wireframes (SVG)
All interface screenshots and layouts should use SVG wireframes located in `/assets/`.
### Directory Structure
```
assets/
├── suite/
│ ├── chat-screen.svg
│ ├── drive-screen.svg
│ ├── calendar-screen.svg
│ ├── mail-screen.svg
│ ├── tasks-screen.svg
│ ├── meet-screen.svg
│ ├── live-monitoring-organism.svg
│ └── ...
├── chapter-01/
│ ├── bootstrap-process.svg
│ └── session-states.svg
└── chapter-04/
└── analytics-interface.svg
```
### Referencing SVG Wireframes
Use standard HTML image syntax with responsive styling:
```html
<img src="../assets/suite/chat-screen.svg" alt="Chat Interface" style="max-width: 100%; height: auto;">
```
---
## Conversation Examples (WhatsApp Style)
All conversation examples throughout the book use the WhatsApp-style HTML format. This provides a familiar, visually consistent representation of bot interactions.
### Standard Format
```html
<div class="wa-chat">
<div class="wa-message user">
<div class="wa-bubble">
<p>User message goes here</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>Bot response goes here</p>
<div class="wa-time">10:30</div>
</div>
</div>
</div>
```
### Complete Example
```html
<div class="wa-chat">
<div class="wa-message bot">
<div class="wa-bubble">
<p>Hello! How can I help you today?</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>I want to enroll in computer science</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>I'll help you enroll! What's your name?</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>Sarah Chen</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>✅ Welcome to Computer Science, Sarah!</p>
<p>Your enrollment ID is: ENR-2025-0142</p>
<div class="wa-time">10:31</div>
</div>
</div>
</div>
```
### Message Classes
| Class | Usage |
|-------|-------|
| `wa-chat` | Container for the conversation |
| `wa-message` | Individual message wrapper |
| `wa-message user` | User message (right-aligned, colored) |
| `wa-message bot` | Bot message (left-aligned) |
| `wa-bubble` | Message bubble with styling |
| `wa-time` | Timestamp display |
### Formatting Guidelines
1. **User messages** — Use `wa-message user` class
2. **Bot messages** — Use `wa-message bot` class
3. **Timestamps** — Include `wa-time` div with realistic times
4. **Multi-line responses** — Use separate `<p>` tags for each line
5. **Emojis** — Use sparingly for status indicators (✅, ❌, 📧, 📅, 📁)
6. **Bold text** — Use `<strong>` for emphasis
7. **Attachments** — Indicate with 📎 emoji and filename
### File Attachments Example
```html
<div class="wa-chat">
<div class="wa-message user">
<div class="wa-bubble">
<p>Upload the quarterly report</p>
<p>📎 Q4-Report.pdf</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>✅ File uploaded successfully!</p>
<p>📄 Q4-Report.pdf (2.4 MB)</p>
<p>📁 Saved to: My Drive</p>
<div class="wa-time">10:30</div>
</div>
</div>
</div>
```
---
## CSS Styling
The WhatsApp chat styling is defined in `whatsapp-chat.css` and automatically included in the book build. The styles provide:
- Familiar messaging app appearance
- Proper alignment (user right, bot left)
- Bubble styling with shadows
- Responsive layout
- Timestamp formatting
---
## When to Use Each Format
| Content Type | Format |
|--------------|--------|
| Interface screenshots | SVG wireframe |
| System architecture | SVG diagram |
| Data flow diagrams | SVG diagram |
| Bot conversations | WhatsApp HTML |
| API examples | Code blocks |
| Configuration | Code blocks |
---
## Global Conversation Style Reference
For all conversation examples throughout the book, follow the format established in:
**[BASIC vs Automation Tools](../chapter-06-gbdialog/basic-vs-automation-tools.md)**
This document serves as the canonical reference for:
- Conversation formatting
- Multi-channel message representation
- Bot response styling
- User input examples
---
## See Also
- [Conversation Examples](./conversation-examples.md) — Example patterns
- [BASIC vs Automation Tools](../chapter-06-gbdialog/basic-vs-automation-tools.md) — Canonical conversation style
- [Chapter 04 Apps](../chapter-04-gbui/apps/README.md) — Interface documentation

135
src/appendix-env-vars/README.md
View file

@ -1,14 +1,10 @@
# Appendix C: Environment Variables # Appendix C: Environment Variables
General Bots uses a minimal set of environment variables. All configuration is managed through `config.csv` files within each bot's `.gbot` folder, with secrets stored securely in Vault. General Bots uses a **minimal set of environment variables**. All configuration is managed through `config.csv` files within each bot's `.gbot` folder, with secrets stored securely in Vault.
## Required Environment Variables ## Required Environment Variables
Only Vault-related environment variables are used by General Bots: Only Vault-related environment variables are required by General Bots:
### VAULT_* Variables
**Purpose**: HashiCorp Vault integration for secure secrets management.
| Variable | Description | Example | | Variable | Description | Example |
|----------|-------------|---------| |----------|-------------|---------|
@ -16,63 +12,18 @@ Only Vault-related environment variables are used by General Bots:
| `VAULT_TOKEN` | Authentication token | Auto-generated during bootstrap | | `VAULT_TOKEN` | Authentication token | Auto-generated during bootstrap |
| `VAULT_NAMESPACE` | Vault namespace (optional) | `admin` | | `VAULT_NAMESPACE` | Vault namespace (optional) | `admin` |
**Example**:
```bash
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=hvs.your-vault-token
```
## Auto-Managed Services
The following services are automatically configured through Vault:
| Service | Management |
|---------|------------|
| PostgreSQL | Connection credentials in Vault |
| S3-Compatible Storage | Access keys in Vault |
| Cache | Connection managed via Vault |
| Email (Stalwart) | Credentials in Vault |
| LLM API Keys | Stored in Vault |
You do **not** need to set environment variables for these services. Vault handles credential distribution and rotation automatically.
## What NOT to Use Environment Variables For
**All application configuration belongs in `config.csv`**:
| Configuration | Where to Configure |
|--------------|-------------------|
| Database connection | Managed by Vault |
| Storage credentials | Managed by Vault |
| LLM API keys | Managed by Vault |
| LLM provider | `config.csv`: `llm-url` |
| Email settings | `config.csv`: `email-*` |
| Channel tokens | `config.csv`: `whatsapp-*`, etc. |
| Bot settings | `config.csv`: all bot-specific settings |
| Feature flags | `config.csv`: various keys |
## Configuration Philosophy
General Bots follows these principles:
1. **Vault-First**: All secrets are managed by Vault
2. **Minimal Environment**: Only Vault address and token use environment variables
3. **config.csv for Settings**: All application configuration is in `config.csv`
4. **Per-Bot Configuration**: Each bot has its own `config.csv` in its `.gbot` folder
5. **No Hardcoded Secrets**: Never store secrets in code or config files
## Setting Environment Variables ## Setting Environment Variables
### Linux/macOS ### Linux/macOS
```bash ```botbook/src/appendix-env-vars/example.sh#L1-2
export VAULT_ADDR=http://localhost:8200 export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=hvs.your-vault-token export VAULT_TOKEN=hvs.your-vault-token
``` ```
### Systemd Service ### Systemd Service
```ini ```botbook/src/appendix-env-vars/example.service#L1-3
[Service] [Service]
Environment="VAULT_ADDR=http://localhost:8200" Environment="VAULT_ADDR=http://localhost:8200"
Environment="VAULT_TOKEN=hvs.your-vault-token" Environment="VAULT_TOKEN=hvs.your-vault-token"
@ -80,31 +31,79 @@ Environment="VAULT_TOKEN=hvs.your-vault-token"
### LXC Container ### LXC Container
When using LXC deployment, environment variables are set in the container configuration: ```botbook/src/appendix-env-vars/example-lxc.sh#L1-2
```bash
lxc config set container-name environment.VAULT_ADDR="http://localhost:8200" lxc config set container-name environment.VAULT_ADDR="http://localhost:8200"
lxc config set container-name environment.VAULT_TOKEN="hvs.your-vault-token" lxc config set container-name environment.VAULT_TOKEN="hvs.your-vault-token"
``` ```
## Security Notes ## Auto-Managed Services
1. **Never commit tokens**: Use `.env` files (gitignored) or secrets management The following services are **automatically configured through Vault** during bootstrap:
2. **Rotate regularly**: Vault tokens should be rotated periodically
3. **Limit access**: Only the botserver process needs these variables | Service | Management |
4. **Use TLS**: Always use HTTPS for Vault in production |---------|------------|
| PostgreSQL | Connection credentials stored in Vault |
| S3-Compatible Storage | Access keys stored in Vault |
| Cache | Connection managed via Vault |
| Email (Stalwart) | Credentials stored in Vault |
| LLM API Keys | Stored in Vault |
You do **not** need environment variables for these services. Vault handles credential distribution and rotation automatically.
## Everything Else Goes in config.csv
**All application configuration belongs in `config.csv`**, not environment variables:
| Configuration | Where to Configure |
|--------------|-------------------|
| LLM provider/model | `config.csv`: `llm-url`, `llm-model` |
| Email settings | `config.csv`: `email-*` |
| Channel tokens | `config.csv`: `whatsapp-*`, `telegram-*`, etc. |
| Bot settings | `config.csv`: all bot-specific settings |
| Feature flags | `config.csv`: various keys |
| Theme settings | `config.csv`: `theme-*` |
| Server port | `config.csv`: `server_port` |
### Example config.csv
```botbook/src/appendix-env-vars/example-config.csv#L1-8
name,value
llm-url,http://localhost:8081
llm-model,model.gguf
server_port,8080
theme-color1,#0d2b55
whatsapp-business-id,your-business-id
admin-email,admin@example.com
```
## Configuration Philosophy
General Bots follows these principles:
1. **Vault-First** — All secrets are managed by Vault
2. **Minimal Environment** — Only Vault address and token use environment variables
3. **config.csv for Settings** — All application configuration is in `config.csv`
4. **Per-Bot Configuration** — Each bot has its own `config.csv` in its `.gbot` folder
5. **No Hardcoded Secrets** — Never store secrets in code or config files
## Bootstrap Process ## Bootstrap Process
During bootstrap, General Bots: During bootstrap, General Bots:
1. Connects to Vault using `VAULT_*` variables 1. Connects to Vault using `VAULT_*` variables
2. Retrieves credentials for all managed services 2. Retrieves or generates credentials for all managed services
3. Configures database, storage, cache, and other services 3. Configures database, storage, cache, and other services
4. Stores service endpoints securely 4. Stores service credentials securely in Vault
This eliminates the need for manual credential management. This eliminates the need for manual credential management.
## Security Notes
1. **Never commit tokens** — Use `.env` files (gitignored) or secrets management
2. **Rotate regularly** — Vault tokens should be rotated periodically
3. **Limit access** — Only the botserver process needs these variables
4. **Use TLS** — Always use HTTPS for Vault in production
## Troubleshooting ## Troubleshooting
### Vault Connection Failed ### Vault Connection Failed
@ -124,13 +123,13 @@ Verify:
If a managed service (database, storage, cache) is unavailable: If a managed service (database, storage, cache) is unavailable:
1. Check Vault is running and unsealed 1. Check Vault is running and unsealed
2. Verify secrets exist in Vault 2. Verify secrets exist in Vault at expected paths
3. Check service container/process status 3. Check service container/process status
4. Review logs for connection errors 4. Review logs for connection errors
## See Also ## See Also
- [config.csv Format](../chapter-08-config/config-csv.md) - Bot configuration - [config.csv Format](../chapter-08-config/config-csv.md) — Bot configuration reference
- [Secrets Management](../chapter-08-config/secrets-management.md) - Vault integration details - [Secrets Management](../chapter-08-config/secrets-management.md) — Vault integration details
- [Drive Integration](../chapter-08-config/drive.md) - Storage setup - [Drive Integration](../chapter-08-config/drive.md) — Storage setup
- [Authentication](../chapter-12-auth/README.md) - Security features - [Authentication](../chapter-12-auth/README.md) — Security features

390
src/appendix-external-services/attendance-queue.md
View file

@ -1,22 +1,27 @@
# Attendance Queue Module # Attendance Queue Module
Human-attendant queue management for hybrid bot/human support workflows. Human-attendant queue management for hybrid bot/human support workflows, plus CRM automations for follow-ups, collections, scheduling, and sales.
## Overview ## Overview
The attendance queue module manages handoffs from bot to human agents, tracking conversation queues, attendant availability, and real-time assignment. The attendance queue module manages handoffs from bot to human agents, tracking conversation queues, attendant availability, and real-time assignment. It also provides automated CRM workflows that run without human intervention.
---
## Configuration ## Configuration
Create `attendant.csv` in your bot's `.gbai` folder: Create `attendant.csv` in your bot's `.gbai` folder:
```csv ```csv
id,name,channel,preferences id,name,channel,preferences,department
att-001,John Smith,whatsapp,sales att-001,John Smith,whatsapp,sales,commercial
att-002,Jane Doe,web,support att-002,Jane Doe,web,support,customer-service
att-003,Bob Wilson,all,technical att-003,Bob Wilson,all,technical,engineering
att-004,Maria Santos,whatsapp,collections,finance
``` ```
---
## Queue Status ## Queue Status
| Status | Description | | Status | Description |
@ -36,12 +41,298 @@ att-003,Bob Wilson,all,technical
| `away` | Temporarily unavailable | | `away` | Temporarily unavailable |
| `offline` | Not working | | `offline` | Not working |
---
## CRM Automations
The attendant module includes built-in CRM automations that handle common business workflows automatically.
### Follow-Up Automation
Automated follow-up sequences for leads and customers.
```basic
' follow-up.bas
' Automated follow-up workflow
SET SCHEDULE "follow-ups", "0 9 * * 1-5"
' Find leads needing follow-up
leads_1_day = FIND "leads", "status='new' AND DATEDIFF(NOW(), last_contact) = 1"
leads_3_day = FIND "leads", "status='contacted' AND DATEDIFF(NOW(), last_contact) = 3"
leads_7_day = FIND "leads", "status='contacted' AND DATEDIFF(NOW(), last_contact) = 7"
' 1-day follow-up: Thank you message
FOR EACH lead IN leads_1_day
SEND TEMPLATE lead.phone, "follow_up_thanks", lead.name, lead.interest
UPDATE "leads", "id=" + lead.id, "contacted", NOW()
INSERT "activities", lead.id, "follow_up", "1-day thank you sent", NOW()
NEXT lead
' 3-day follow-up: Value proposition
FOR EACH lead IN leads_3_day
SEND TEMPLATE lead.phone, "follow_up_value", lead.name, lead.interest
UPDATE "leads", "id=" + lead.id, "nurturing", NOW()
INSERT "activities", lead.id, "follow_up", "3-day value prop sent", NOW()
NEXT lead
' 7-day follow-up: Special offer
FOR EACH lead IN leads_7_day
SEND TEMPLATE lead.phone, "follow_up_offer", lead.name, "10%"
UPDATE "leads", "id=" + lead.id, "offer_sent", NOW()
INSERT "activities", lead.id, "follow_up", "7-day offer sent", NOW()
' Alert sales team for hot leads
IF lead.score >= 70 THEN
attendant = FIND "attendants", "department='commercial' AND status='online'"
IF attendant THEN
SEND MAIL attendant.email, "Hot Lead Follow-up: " + lead.name, "Lead " + lead.name + " received 7-day offer. Score: " + lead.score
END IF
END IF
NEXT lead
PRINT "Follow-ups completed: " + UBOUND(leads_1_day) + " 1-day, " + UBOUND(leads_3_day) + " 3-day, " + UBOUND(leads_7_day) + " 7-day"
```
### Collections Automation (Cobranças)
Automated payment reminders and collection workflow.
```basic
' collections.bas
' Automated payment collection workflow
SET SCHEDULE "collections", "0 8 * * 1-5"
' Find overdue invoices by age
due_today = FIND "invoices", "status='pending' AND due_date = CURDATE()"
overdue_3 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 3"
overdue_7 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 7"
overdue_15 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 15"
overdue_30 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) >= 30"
' Due today: Friendly reminder via WhatsApp
FOR EACH invoice IN due_today
customer = FIND "customers", "id=" + invoice.customer_id
SEND TEMPLATE customer.phone, "payment_due_today", customer.name, invoice.id, invoice.amount
INSERT "collection_log", invoice.id, "reminder_due_today", NOW()
NEXT invoice
' 3 days overdue: First collection notice
FOR EACH invoice IN overdue_3
customer = FIND "customers", "id=" + invoice.customer_id
SEND TEMPLATE customer.phone, "payment_overdue_3", customer.name, invoice.id, invoice.amount
SEND MAIL customer.email, "Pagamento Pendente - Fatura #" + invoice.id, "Sua fatura está vencida há 3 dias. Valor: R$ " + invoice.amount
UPDATE "invoices", "id=" + invoice.id, "first_notice_sent", NOW()
INSERT "collection_log", invoice.id, "first_notice", NOW()
NEXT invoice
' 7 days overdue: Second notice with urgency
FOR EACH invoice IN overdue_7
customer = FIND "customers", "id=" + invoice.customer_id
SEND TEMPLATE customer.phone, "payment_overdue_7", customer.name, invoice.id, invoice.amount
UPDATE "invoices", "id=" + invoice.id, "second_notice_sent", NOW()
INSERT "collection_log", invoice.id, "second_notice", NOW()
' Notify collections team
SEND MAIL "cobranca@empresa.com", "Cobrança 7 dias: " + customer.name, "Cliente: " + customer.name + "\nFatura: " + invoice.id + "\nValor: R$ " + invoice.amount
NEXT invoice
' 15 days overdue: Final notice before action
FOR EACH invoice IN overdue_15
customer = FIND "customers", "id=" + invoice.customer_id
late_fee = invoice.amount * 0.02
interest = invoice.amount * 0.01 * 15
total_due = invoice.amount + late_fee + interest
SEND TEMPLATE customer.phone, "payment_final_notice", customer.name, invoice.id, total_due
UPDATE "invoices", "id=" + invoice.id, late_fee, interest, total_due, "final_notice_sent", NOW()
INSERT "collection_log", invoice.id, "final_notice", NOW()
' Assign to human attendant for follow-up call
attendant = FIND "attendants", "department='finance' AND status='online'"
IF attendant THEN
INSERT "queue", invoice.customer_id, attendant.id, "collection_call", "high", NOW()
END IF
NEXT invoice
' 30+ days overdue: Escalate to collections
FOR EACH invoice IN overdue_30
IF invoice.status <> "collections" THEN
customer = FIND "customers", "id=" + invoice.customer_id
UPDATE "invoices", "id=" + invoice.id, "collections", NOW()
UPDATE "customers", "id=" + customer.id, "suspended"
SEND MAIL "juridico@empresa.com", "Inadimplência 30+ dias: " + customer.name, "Cliente enviado para cobrança jurídica.\n\nCliente: " + customer.name + "\nFatura: " + invoice.id + "\nValor total: R$ " + invoice.total_due
INSERT "collection_log", invoice.id, "sent_to_collections", NOW()
END IF
NEXT invoice
PRINT "Collections processed: " + UBOUND(due_today) + " due today, " + UBOUND(overdue_30) + " sent to collections"
```
### Scheduling Automation (Agendamentos)
Automated appointment scheduling and reminders.
```basic
' scheduling.bas
' Automated appointment scheduling and reminders
SET SCHEDULE "appointment-reminders", "0 7 * * *"
' Find appointments for today and tomorrow
today_appointments = FIND "appointments", "DATE(scheduled_at) = CURDATE() AND status='confirmed'"
tomorrow_appointments = FIND "appointments", "DATE(scheduled_at) = DATE_ADD(CURDATE(), INTERVAL 1 DAY) AND status='confirmed'"
' Send day-before reminders
FOR EACH appt IN tomorrow_appointments
customer = FIND "customers", "id=" + appt.customer_id
staff = FIND "staff", "id=" + appt.staff_id
appt_time = FORMAT(appt.scheduled_at, "HH:mm")
appt_date = FORMAT(appt.scheduled_at, "DD/MM/YYYY")
SEND TEMPLATE customer.phone, "appointment_reminder_24h", customer.name, appt.service, appt_date, appt_time, staff.name
UPDATE "appointments", "id=" + appt.id, "reminder_24h_sent", NOW()
NEXT appt
' Send same-day reminders (2 hours before)
FOR EACH appt IN today_appointments
IF DATEDIFF_HOURS(appt.scheduled_at, NOW()) <= 2 AND appt.reminder_2h_sent IS NULL THEN
customer = FIND "customers", "id=" + appt.customer_id
staff = FIND "staff", "id=" + appt.staff_id
appt_time = FORMAT(appt.scheduled_at, "HH:mm")
SEND TEMPLATE customer.phone, "appointment_reminder_2h", customer.name, appt.service, appt_time
UPDATE "appointments", "id=" + appt.id, "reminder_2h_sent", NOW()
' Notify staff
SEND TEMPLATE staff.phone, "staff_appointment_alert", staff.name, customer.name, appt.service, appt_time
END IF
NEXT appt
' Check for no-shows (30 min past appointment time)
past_appointments = FIND "appointments", "scheduled_at < DATE_SUB(NOW(), INTERVAL 30 MINUTE) AND status='confirmed'"
FOR EACH appt IN past_appointments
customer = FIND "customers", "id=" + appt.customer_id
UPDATE "appointments", "id=" + appt.id, "no_show"
INSERT "activities", appt.customer_id, "no_show", "Missed appointment: " + appt.service, NOW()
' Send reschedule offer
SEND TEMPLATE customer.phone, "missed_appointment", customer.name, appt.service
NEXT appt
PRINT "Reminders sent: " + UBOUND(tomorrow_appointments) + " for tomorrow, " + UBOUND(today_appointments) + " for today"
```
### Sales Automation (Vendas)
Automated sales pipeline and lead scoring.
```basic
' sales-automation.bas
' Automated sales pipeline management
SET SCHEDULE "sales-automation", "0 8,14,18 * * 1-5"
' Score and prioritize leads
new_leads = FIND "leads", "score IS NULL OR score = 0"
FOR EACH lead IN new_leads
score = 0
' Score based on source
IF lead.source = "website" THEN score = score + 20
IF lead.source = "referral" THEN score = score + 30
IF lead.source = "campaign" THEN score = score + 15
' Score based on company size
IF lead.company_size = "enterprise" THEN score = score + 25
IF lead.company_size = "mid-market" THEN score = score + 20
IF lead.company_size = "small" THEN score = score + 10
' Score based on engagement
page_views = FIND "analytics", "lead_id=" + lead.id + " AND type='page_view'"
score = score + MIN(UBOUND(page_views) * 2, 20)
' Score based on email opens
email_opens = FIND "email_tracking", "lead_id=" + lead.id + " AND opened=true"
score = score + MIN(UBOUND(email_opens) * 5, 25)
UPDATE "leads", "id=" + lead.id, score, NOW()
NEXT lead
' Auto-assign hot leads to sales reps
hot_leads = FIND "leads", "score >= 70 AND assigned_to IS NULL"
FOR EACH lead IN hot_leads
' Round-robin assignment
available_reps = FIND "attendants", "department='commercial' AND status='online'"
IF UBOUND(available_reps) > 0 THEN
' Get rep with fewest active leads
rep = available_reps[0]
min_leads = 999
FOR EACH r IN available_reps
rep_leads = FIND "leads", "assigned_to='" + r.id + "' AND status NOT IN ('converted', 'lost')"
IF UBOUND(rep_leads) < min_leads THEN
min_leads = UBOUND(rep_leads)
rep = r
END IF
NEXT r
UPDATE "leads", "id=" + lead.id, rep.id, NOW()
' Notify sales rep via WhatsApp
SEND TEMPLATE rep.phone, "new_hot_lead", rep.name, lead.name, lead.company, lead.score
' Create follow-up task
CREATE TASK "Contact hot lead: " + lead.name, rep.email, NOW()
END IF
NEXT lead
' Move stale opportunities
stale_opportunities = FIND "opportunities", "DATEDIFF(NOW(), last_activity) > 14 AND stage NOT IN ('closed_won', 'closed_lost')"
FOR EACH opp IN stale_opportunities
owner = FIND "attendants", "id=" + opp.owner_id
' Send reminder to owner
SEND TEMPLATE owner.phone, "stale_opportunity", owner.name, opp.name, opp.amount, DATEDIFF(NOW(), opp.last_activity)
' Create urgent task
CREATE TASK "URGENT: Update stale opportunity - " + opp.name, owner.email, NOW()
INSERT "activities", opp.id, "stale_alert", "Opportunity marked as stale", NOW()
NEXT opp
' Generate daily pipeline report
pipeline = FIND "opportunities", "stage NOT IN ('closed_won', 'closed_lost')"
total_value = AGGREGATE "SUM", pipeline, "amount"
weighted_value = 0
FOR EACH opp IN pipeline
weighted_value = weighted_value + (opp.amount * opp.probability / 100)
NEXT opp
report = "📊 Pipeline Diário\n\n"
report = report + "Total Pipeline: R$ " + FORMAT(total_value, "#,##0.00") + "\n"
report = report + "Valor Ponderado: R$ " + FORMAT(weighted_value, "#,##0.00") + "\n"
report = report + "Oportunidades Ativas: " + UBOUND(pipeline) + "\n"
report = report + "Leads Quentes: " + UBOUND(hot_leads)
SEND MAIL "vendas@empresa.com", "Pipeline Diário - " + FORMAT(NOW(), "DD/MM/YYYY"), report
PRINT "Sales automation completed. Hot leads assigned: " + UBOUND(hot_leads)
```
---
## REST API Endpoints ## REST API Endpoints
### GET /api/queue ### Queue Management
#### GET /api/queue
List conversations in queue. List conversations in queue.
### POST /api/queue/assign #### POST /api/queue/assign
Assign conversation to attendant. Assign conversation to attendant.
```json ```json
@ -51,7 +342,7 @@ Assign conversation to attendant.
} }
``` ```
### POST /api/queue/transfer #### POST /api/queue/transfer
Transfer conversation between attendants. Transfer conversation between attendants.
```json ```json
@ -63,16 +354,95 @@ Transfer conversation between attendants.
} }
``` ```
### GET /api/attendants ### Attendant Management
#### GET /api/attendants
List all attendants with stats. List all attendants with stats.
#### PUT /api/attendants/{id}/status
Update attendant status.
```json
{
"status": "online"
}
```
### CRM Automation
#### GET /api/automation/status
Check automation job status.
#### POST /api/automation/trigger/{job_name}
Manually trigger an automation job.
---
## BASIC Keywords ## BASIC Keywords
### Transfer to Human
```basic ```basic
' Transfer to any available human
TRANSFER TO HUMAN
' Transfer to specific department
TRANSFER TO HUMAN "sales" TRANSFER TO HUMAN "sales"
' Transfer with priority
TRANSFER TO HUMAN "support", "high" TRANSFER TO HUMAN "support", "high"
' Transfer with context
TRANSFER TO HUMAN "technical", "normal", "Customer needs help with API integration"
``` ```
### Create Lead
```basic
' Create lead from conversation
CREATE LEAD name, email, phone, source
' Create lead with company info
CREATE LEAD name, email, phone, "website", company, "enterprise"
```
### Schedule Appointment
```basic
' Schedule appointment
BOOK customer_email, service, date, time, staff_id
' Schedule with duration
BOOK customer_email, "Consultation", "2025-01-20", "14:00", staff_id, 60
```
---
## WhatsApp Templates
Configure these templates in your WhatsApp Business account:
| Template Name | Purpose | Variables |
|---------------|---------|-----------|
| `follow_up_thanks` | 1-day follow-up | name, interest |
| `follow_up_value` | 3-day value proposition | name, interest |
| `follow_up_offer` | 7-day special offer | name, discount |
| `payment_due_today` | Payment due reminder | name, invoice_id, amount |
| `payment_overdue_3` | 3-day overdue notice | name, invoice_id, amount |
| `payment_overdue_7` | 7-day overdue notice | name, invoice_id, amount |
| `payment_final_notice` | 15-day final notice | name, invoice_id, total |
| `appointment_reminder_24h` | Day-before reminder | name, service, date, time, staff |
| `appointment_reminder_2h` | 2-hour reminder | name, service, time |
| `missed_appointment` | No-show reschedule | name, service |
| `new_hot_lead` | Hot lead alert for sales | rep_name, lead_name, company, score |
| `stale_opportunity` | Stale deal reminder | rep_name, deal_name, amount, days |
---
## See Also ## See Also
- [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md) - [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md)
- [SEND TEMPLATE](../chapter-06-gbdialog/keyword-send-template.md)
- [SET SCHEDULE](../chapter-06-gbdialog/keyword-set-schedule.md)
- [CREATE LEAD](../chapter-06-gbdialog/keywords-lead-scoring.md)
- [Sales CRM Template](../chapter-02/template-crm.md)

325
src/appendix-external-services/hosting-dns.md Normal file
View file

@ -0,0 +1,325 @@
# Hosting, DNS, and MDA Integration
General Bots integrates with hosting providers, DNS services, and Mail Delivery Agents (MDA) for complete platform deployment.
---
## Overview
A complete General Bots deployment typically includes:
| Component | Purpose | Providers Supported |
|-----------|---------|---------------------|
| **Hosting** | Run BotServer | Any VPS, LXC, bare metal |
| **DNS** | Domain management | Namecheap, Cloudflare, Route53 |
| **MDA** | Email delivery | Stalwart, Postfix, external SMTP |
| **AI/LLM** | Language models | OpenAI, Anthropic, local models |
---
## Namecheap Integration
General Bots can automatically manage DNS records via the Namecheap API.
### Configuration
Add to your bot's `config.csv`:
```csv
name,value
namecheap-api-user,your-username
namecheap-api-key,stored-in-vault
namecheap-username,your-username
namecheap-client-ip,your-server-ip
```
> **Note**: API key is stored in Vault, not in config.csv. Only reference it by name.
### Automatic DNS Setup
When deploying a new bot instance, General Bots can:
1. Create A record pointing to your server
2. Create MX records for email
3. Create TXT records for SPF/DKIM/DMARC
4. Create CNAME for www subdomain
### BASIC Keywords for DNS
```basic
' Create DNS record
DNS SET "bot.example.com", "A", server_ip
' Create MX record for email
DNS SET "example.com", "MX", "mail.example.com", 10
' Create SPF record
DNS SET "example.com", "TXT", "v=spf1 mx a ip4:" + server_ip + " -all"
' List current records
records = DNS LIST "example.com"
```
### Supported DNS Providers
| Provider | API Support | Auto-SSL |
|----------|-------------|----------|
| Namecheap | ✅ Full | ✅ Let's Encrypt |
| Cloudflare | ✅ Full | ✅ Native |
| Route53 | ✅ Full | ✅ ACM |
| DigitalOcean | ✅ Full | ✅ Let's Encrypt |
| Manual | Via config | Manual |
---
## Hosting Options
### VPS Providers
General Bots runs on any Linux VPS:
| Provider | Minimum Spec | Recommended |
|----------|--------------|-------------|
| DigitalOcean | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
| Linode | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
| Vultr | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
| Hetzner | 2GB RAM, 2 vCPU | 4GB RAM, 2 vCPU |
| AWS EC2 | t3.small | t3.medium |
| GCP | e2-small | e2-medium |
### LXC Container Deployment
Recommended for production isolation:
```bash
# Create container
lxc launch ubuntu:22.04 botserver
# Configure resources
lxc config set botserver limits.memory 4GB
lxc config set botserver limits.cpu 2
# Forward ports
lxc config device add botserver http proxy listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:8080
lxc config device add botserver https proxy listen=tcp:0.0.0.0:443 connect=tcp:127.0.0.1:8443
# Set environment for Vault
lxc config set botserver environment.VAULT_ADDR="http://vault:8200"
# Deploy
lxc exec botserver -- ./botserver
```
### Docker Deployment
```yaml
version: '3.8'
services:
botserver:
image: generalbots/botserver:latest
ports:
- "8080:8080"
environment:
- VAULT_ADDR=http://vault:8200
volumes:
- ./bots:/app/bots
- ./botserver-stack:/app/botserver-stack
```
---
## MDA (Mail Delivery Agent) Integration
General Bots includes Stalwart mail server for complete email functionality.
### Built-in Stalwart
Stalwart is automatically configured during bootstrap:
| Feature | Status |
|---------|--------|
| IMAP | ✅ Enabled |
| SMTP | ✅ Enabled |
| JMAP | ✅ Enabled |
| Spam filtering | ✅ SpamAssassin |
| Virus scanning | ✅ ClamAV |
| DKIM signing | ✅ Auto-configured |
### Email Configuration
In `config.csv`:
```csv
name,value
email-domain,example.com
email-dkim-selector,mail
email-spam-threshold,5.0
email-max-size-mb,25
```
### DNS Records for Email
Required DNS records (auto-created with Namecheap integration):
| Record | Type | Value |
|--------|------|-------|
| `mail.example.com` | A | Your server IP |
| `example.com` | MX | `mail.example.com` (priority 10) |
| `example.com` | TXT | `v=spf1 mx a -all` |
| `mail._domainkey.example.com` | TXT | DKIM public key |
| `_dmarc.example.com` | TXT | `v=DMARC1; p=quarantine` |
### External SMTP
To use external email providers instead:
```csv
name,value
smtp-host,smtp.sendgrid.net
smtp-port,587
smtp-user,apikey
smtp-secure,tls
```
Credentials stored in Vault:
```bash
vault kv put secret/botserver/smtp password="your-api-key"
```
---
## AI/LLM Integration
### Supported Providers
| Provider | Models | Config Key |
|----------|--------|------------|
| OpenAI | GPT-4, GPT-3.5 | `llm-url=https://api.openai.com/v1` |
| Anthropic | Claude 3 | `llm-url=https://api.anthropic.com` |
| Groq | Llama, Mixtral | `llm-url=https://api.groq.com/openai/v1` |
| DeepSeek | DeepSeek-V2 | `llm-url=https://api.deepseek.com` |
| Local | Any GGUF | `llm-url=http://localhost:8081` |
### Local LLM Setup
Run local models with BotModels:
```bash
# Install BotModels
./botserver install llm
# Download a model
./botserver model download llama-3-8b
# Configure in config.csv
```
```csv
name,value
llm-url,http://localhost:8081
llm-model,llama-3-8b.gguf
llm-context-size,8192
llm-gpu-layers,35
```
### AI Features
| Feature | Description |
|---------|-------------|
| **Conversation** | Natural language chat |
| **RAG** | Knowledge base search |
| **Tool Calling** | Automatic BASIC tool invocation |
| **Embeddings** | Document vectorization |
| **Vision** | Image analysis (multimodal models) |
| **Voice** | Speech-to-text, text-to-speech |
---
## Complete Deployment Example
### 1. Provision Server
```bash
# On your VPS
wget https://github.com/GeneralBots/botserver/releases/latest/botserver
chmod +x botserver
```
### 2. Configure DNS (Namecheap)
```basic
' setup-dns.bas
domain = "mybot.example.com"
server_ip = "203.0.113.50"
DNS SET domain, "A", server_ip
DNS SET "mail." + domain, "A", server_ip
DNS SET domain, "MX", "mail." + domain, 10
DNS SET domain, "TXT", "v=spf1 mx a ip4:" + server_ip + " -all"
PRINT "DNS configured for " + domain
```
### 3. Start BotServer
```bash
./botserver
```
### 4. Configure SSL
```bash
# Auto-configured with Let's Encrypt
./botserver ssl enable mybot.example.com
```
### 5. Verify Email
```basic
' test-email.bas
SEND MAIL "test@gmail.com", "Test from General Bots", "Email is working!"
PRINT "Email sent successfully"
```
---
## Troubleshooting
### DNS Not Propagating
1. Check Namecheap API credentials
2. Verify client IP is whitelisted
3. Wait up to 48 hours for propagation
4. Use `dig` or `nslookup` to verify
### Email Marked as Spam
1. Verify SPF record is correct
2. Check DKIM signature is valid
3. Ensure DMARC policy is set
4. Check IP reputation at mxtoolbox.com
### SSL Certificate Errors
1. Verify DNS A record points to server
2. Check port 80 is accessible for ACME challenge
3. Review Let's Encrypt rate limits
4. Check certificate expiry
### LLM Connection Failed
1. Verify `llm-url` in config.csv
2. Check API key in Vault
3. Test endpoint with curl
4. Review BotServer logs
---
## See Also
- [LLM Providers](./llm-providers.md) — Detailed LLM configuration
- [Storage](./storage.md) — S3-compatible storage setup
- [Directory](./directory.md) — User authentication
- [Channels](./channels.md) — WhatsApp, Telegram, etc.
- [Installation](../chapter-01/installation.md) — Full installation guide

133
src/chapter-01/README.md
View file

@ -1,41 +1,130 @@
# Chapter 01: Run and Talk # Chapter 01: Run and Talk
Get General Bots running in 5 minutes. > **⚡ In a hurry?** Jump straight to [Quick Start](./quick-start.md) — you'll be chatting with your bot in 5 minutes.
## What You'll Learn Get General Bots running and have your first conversation.
- How to start General Bots ---
- Your first conversation
- How sessions work
- Basic bot interaction
## Quick Start ## What You'll Achieve
By the end of this chapter, you will:
- ✅ Have General Bots running on your machine
- ✅ Understand what happens during bootstrap
- ✅ Complete your first conversation with a bot
- ✅ Know how sessions and channels work
---
## Choose Your Path
| If You Want To... | Go To |
|-------------------|-------|
| Get running immediately | [Quick Start](./quick-start.md) |
| Understand the architecture first | [Overview](./overview.md) |
| See all installation options | [Installation](./installation.md) |
| Learn about conversations | [First Conversation](./first-conversation.md) |
| Understand session management | [Sessions and Channels](./sessions.md) |
---
## The 30-Second Version
Download and run:
```bash ```bash
./botserver ./botserver
``` ```
That's it. Everything installs automatically on first run. Open `http://localhost:8080`. Start chatting. That's it.
## What Happens Everything installs automatically on first run—PostgreSQL, storage, cache, and your first bot.
1. **Auto-Bootstrap**: Installs PostgreSQL, cache, storage, and LLM ---
2. **Load Bots**: Finds `.gbai` folders and loads them
3. **Start Server**: Opens on `http://localhost:8080`
4. **Ready**: Talk to your bot
## First Conversation ## How It Works
Open browser, type a message, get a response. Simple. <div class="wa-chat">
<div class="wa-message user">
<div class="wa-bubble">
<p>How do I get started with General Bots?</p>
<div class="wa-time">09:00</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>Just three steps:</p>
<p>1️⃣ Download <code>botserver</code></p>
<p>2️⃣ Run <code>./botserver</code></p>
<p>3️⃣ Open your browser to localhost:8080</p>
<p>The bootstrap process handles everything else automatically!</p>
<div class="wa-time">09:00</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>What gets installed?</p>
<div class="wa-time">09:01</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>📦 PostgreSQL (database)</p>
<p>📦 MinIO (file storage)</p>
<p>📦 Cache (Redis-compatible)</p>
<p>📦 Default bot templates</p>
<p>All in <code>botserver-stack/</code> — no system-wide installation!</p>
<div class="wa-time">09:01</div>
</div>
</div>
</div>
## Topics Covered ---
- [Overview](./overview.md) - What General Bots does ## Topics in This Chapter
- [Quick Start](./quick-start.md) - Get running fast
- [Installation](./installation.md) - Detailed setup options ### [Overview](./overview.md)
- [First Conversation](./first-conversation.md) - Using your bot What General Bots does and how it fits together.
- [Sessions](./sessions.md) - How conversations are managed
### [Quick Start](./quick-start.md)
The fastest path from zero to running bot.
### [Installation](./installation.md)
Detailed setup options including LXC containers and production deployment.
### [First Conversation](./first-conversation.md)
Understanding how the bot responds and learns.
### [Sessions and Channels](./sessions.md)
How conversations are managed across WhatsApp, Web, Telegram, and more.
---
## Coming From Executive Vision?
If you just read the [Executive Vision](../executive-vision.md), here's what to know:
1. **Everything in that feature table?** It's all included in the single `botserver` binary
2. **No configuration needed** — Bootstrap detects your system and sets everything up
3. **Start simple** — Run it, chat with it, then customize
The philosophy is: **get running first, understand later**.
---
## Prerequisites
- **Operating System**: Linux, macOS, or Windows (WSL2 recommended)
- **Disk Space**: ~2GB for botserver-stack
- **RAM**: 4GB minimum, 8GB recommended
- **Ports**: 8080 (web), 5432 (database), 9000 (storage)
No Docker required. No cloud accounts. No API keys to start.
---
## Next Step
**[Quick Start →](./quick-start.md)**
--- ---

32
src/chapter-04-gbui/apps/chat.md
View file

@ -77,6 +77,8 @@ Bot responses support full Markdown rendering:
- Links and images - Links and images
- Tables - Tables
---
## Keyboard Shortcuts ## Keyboard Shortcuts
| Shortcut | Action | | Shortcut | Action |
@ -87,6 +89,8 @@ Bot responses support full Markdown rendering:
| `/` | Open command menu | | `/` | Open command menu |
| `Escape` | Cancel current action | | `Escape` | Cancel current action |
---
## API Endpoints ## API Endpoints
### WebSocket Connection ### WebSocket Connection
@ -112,7 +116,7 @@ ws://your-server:8080/ws
| `/api/voice/stop` | POST | Stop voice recording | | `/api/voice/stop` | POST | Stop voice recording |
| `/api/suggestions` | GET | Get suggestion chips | | `/api/suggestions` | GET | Get suggestion chips |
---
## Example Conversations ## Example Conversations
@ -179,7 +183,7 @@ ws://your-server:8080/ws
</div> </div>
</div> </div>
---
## Accessibility ## Accessibility
@ -189,19 +193,7 @@ ws://your-server:8080/ws
- Adjustable font sizes - Adjustable font sizes
- ARIA labels on all interactive elements - ARIA labels on all interactive elements
```html ---
<main id="messages"
role="log"
aria-live="polite"
aria-label="Chat messages">
</main>
<button type="submit"
aria-label="Send message"
title="Send">
↑
</button>
```
## Troubleshooting ## Troubleshooting
@ -226,9 +218,11 @@ ws://your-server:8080/ws
3. Clear browser cache 3. Clear browser cache
4. Check for JavaScript errors 4. Check for JavaScript errors
---
## See Also ## See Also
- [HTMX Architecture](../htmx-architecture.md) - How Chat uses HTMX - [HTMX Architecture](../htmx-architecture.md) — How Chat uses HTMX
- [Suite Manual](../suite-manual.md) - Complete user guide - [Suite Manual](../suite-manual.md) — Complete user guide
- [Tasks App](./tasks.md) - Create tasks from chat - [Tasks App](./tasks.md) — Create tasks from chat
- [Mail App](./mail.md) - Email integration - [Mail App](./mail.md) — Email integration

345
src/chapter-04-gbui/monitoring.md
View file

@ -1,8 +1,8 @@
# Monitoring Dashboard # Monitoring Dashboard
The Monitoring Dashboard provides real-time visibility into your General Bots deployment through an animated, interactive SVG visualization showing system health, active sessions, and resource utilization. The Monitoring Dashboard is the **live operations homepage** for your General Bots deployment. It provides real-time visibility into system health, active sessions, and resource utilization through an animated, interactive SVG visualization.
## Live System Visualization ## Live System Architecture
<img src="../assets/suite/live-monitoring-organism.svg" alt="Live Monitoring Dashboard" style="max-width: 100%; height: auto;"> <img src="../assets/suite/live-monitoring-organism.svg" alt="Live Monitoring Dashboard" style="max-width: 100%; height: auto;">
@ -14,113 +14,109 @@ The dashboard displays BotServer at the center orchestrating all interactions, w
- **Top**: Real-time metrics panels for sessions, messages, and response time - **Top**: Real-time metrics panels for sessions, messages, and response time
- **Bottom**: Resource utilization bars and activity ticker - **Bottom**: Resource utilization bars and activity ticker
---
## Accessing the Dashboard ## Accessing the Dashboard
Access monitoring from the Suite interface: The monitoring dashboard is the **default homepage** when accessing Suite:
```/dev/null/monitoring-url.txt#L1
http://localhost:8080/monitoring
```
Or from within Suite:
1. Click the apps menu (⋮⋮⋮) 1. Click the apps menu (⋮⋮⋮)
2. Select **Monitoring** 2. Select **Monitoring**
3. Or navigate directly to `/monitoring`
## Dashboard Features ---
### Animated System Architecture ## Real-Time Metrics
The SVG visualization shows real-time data flow: ### Active Sessions Panel
| Component | Color | Description | Displays current conversation sessions:
|-----------|-------|-------------|
| **BotServer** | Blue/Purple | Central orchestrator with rotating ring | ```/dev/null/sessions-example.txt#L1-4
| **PostgreSQL** | Blue | Primary database with cylinder icon | Active Sessions: 12
| **Qdrant** | Purple | Vector database with triangle nodes | Peak Today: 47
| **MinIO** | Amber | Object storage with disk icon | Avg Duration: 8m 32s
| **BotModels** | Pink | AI/ML service with neural network icon | Trend: ↑ +3 in last hour
| **Cache** | Cyan | In-memory cache with lightning icon | ```
| **Vault** | Green | Secrets management with lock icon |
### Messages Panel
Shows message throughput:
```/dev/null/messages-example.txt#L1-4
Today: 1,234 messages
This Hour: 89
Avg Response: 1.2s
Rate: 14.8 msg/min
```
### Resource Utilization
Real-time system resources:
| Resource | Current | Threshold |
|----------|---------|-----------|
| **CPU** | 65% | Warning > 80% |
| **Memory** | 72% | Warning > 85% |
| **GPU** | 45% | Warning > 90% |
| **Disk** | 28% | Warning > 90% |
---
## Service Health Status
Each service has a status indicator:
| Service | Status | Health Check |
|---------|--------|--------------|
| **PostgreSQL** | 🟢 Running | Connection pool, query latency |
| **Qdrant** | 🟢 Running | Vector count, search time |
| **MinIO** | 🟢 Running | Storage usage, object count |
| **BotModels** | 🟢 Running | Token usage, response time |
| **Cache** | 🟢 Running | Hit rate, memory usage |
| **Vault** | 🟢 Running | Seal status, policy count |
### Status Indicators ### Status Indicators
Each service has a status dot:
| Status | Color | Animation | | Status | Color | Animation |
|--------|-------|-----------| |--------|-------|-----------|
| **Running** | 🟢 Green | Gentle pulse | | **Running** | 🟢 Green | Gentle pulse |
| **Warning** | 🟡 Amber | Fast pulse | | **Warning** | 🟡 Amber | Fast pulse |
| **Stopped** | 🔴 Red | No animation | | **Stopped** | 🔴 Red | No animation |
### Real-Time Metrics ---
Three metric panels at the top update automatically: ## Live Data Endpoints
| Panel | Update Interval | Description | The dashboard pulls real data from these HTMX endpoints:
|-------|-----------------|-------------|
| **Active Sessions** | 5 seconds | Current open conversations with trend |
| **Messages Today** | 10 seconds | Total messages with hourly rate |
| **Avg Response** | 10 seconds | Average response time in milliseconds |
### Resource Utilization
Resource bars show system health:
| Resource | Gradient | Warning Threshold |
|----------|----------|-------------------|
| **CPU** | Blue/Purple | > 80% |
| **Memory** | Green | > 85% |
| **GPU** | Purple | > 90% |
| **Disk** | Amber | > 90% |
### Activity Ticker
A live ticker at the bottom shows the latest system events with a pulsing green indicator.
## View Modes
Toggle between two views using the grid button or press `V`:
### Live View (Default)
The animated SVG visualization showing the complete system topology with flowing data packets.
### Grid View
Traditional panel-based layout with detailed tree views for each metric category:
- Sessions panel with active, peak, and duration
- Messages panel with counts and rates
- Resources panel with progress bars
- Services panel with health status
- Bots panel with active bot list
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `V` | Toggle between Live and Grid view |
| `R` | Refresh all metrics |
## HTMX Integration
The dashboard uses HTMX for real-time updates without full page reloads:
| Endpoint | Interval | Data | | Endpoint | Interval | Data |
|----------|----------|------| |----------|----------|------|
| `/api/monitoring/metric/sessions` | 5s | Session count | | `/api/monitoring/metric/sessions` | 5s | Session count, trend |
| `/api/monitoring/metric/messages` | 10s | Message count | | `/api/monitoring/metric/messages` | 10s | Message count, rate |
| `/api/monitoring/metric/response_time` | 10s | Avg response | | `/api/monitoring/metric/response_time` | 10s | Avg response time |
| `/api/monitoring/resources/bars` | 15s | Resource SVG bars | | `/api/monitoring/resources/bars` | 15s | CPU, memory, GPU, disk |
| `/api/monitoring/services/status` | 30s | Service health JSON | | `/api/monitoring/services/status` | 30s | Service health JSON |
| `/api/monitoring/activity/latest` | 5s | Activity text | | `/api/monitoring/activity/latest` | 5s | Activity ticker text |
| `/api/monitoring/timestamp` | 5s | Last updated time | | `/api/monitoring/bots/active` | 30s | Active bot list |
---
## API Access ## API Access
Access monitoring data programmatically: ### Full Status Endpoint
### Get Full Status ```/dev/null/api-call.txt#L1
```/dev/null/monitoring-api.txt
GET /api/monitoring/status GET /api/monitoring/status
``` ```
**Response:** Returns complete system status:
```/dev/null/monitoring-response.json ```/dev/null/monitoring-response.json#L1-25
{ {
"sessions": { "sessions": {
"active": 12, "active": 12,
@ -149,31 +145,89 @@ GET /api/monitoring/status
} }
``` ```
### Service-Specific Endpoints ### Active Bots Endpoint
| Endpoint | Returns | ```/dev/null/bots-api.txt#L1
|----------|---------| GET /api/monitoring/bots
| `/api/monitoring/services` | All service details | ```
| `/api/monitoring/bots` | Active bot list |
| `/api/monitoring/history?period=24h` | Historical metrics |
| `/api/monitoring/prometheus` | Prometheus format export |
## Component Health Details Returns list of deployed bots with metrics:
| Component | Health Check | Warning Signs | ```/dev/null/bots-response.json#L1-18
|-----------|--------------|---------------| {
| **PostgreSQL** | Connection count, query rate | > 80 connections, slow queries | "bots": [
| **Qdrant** | Vector count, search latency | > 50ms search time | {
| **MinIO** | Storage usage, object count | > 80% storage used | "name": "default",
| **BotModels** | Token usage, response latency | > 2s response time | "status": "active",
| **Vault** | Seal status, policy count | Unsealed without auth | "sessions_today": 34,
| **Cache** | Hit rate, memory usage | < 80% hit rate | "messages_today": 567,
"avg_response_ms": 980
},
{
"name": "support",
"status": "active",
"sessions_today": 12,
"messages_today": 234,
"avg_response_ms": 1100
}
]
}
```
## Alerts Configuration ### Historical Data
```/dev/null/history-api.txt#L1
GET /api/monitoring/history?period=24h
```
Returns time-series data for charting.
### Prometheus Export
```/dev/null/prometheus-api.txt#L1
GET /api/monitoring/prometheus
```
Returns metrics in Prometheus format for external monitoring systems.
---
## View Modes
Toggle between two views using the grid button or press `V`:
### Live View (Default)
The animated SVG visualization showing the complete system topology with flowing data packets. This is the recommended view for operations dashboards.
### Grid View
Traditional panel-based layout with detailed metrics:
- **Sessions Panel**: Active, peak, average duration
- **Messages Panel**: Counts, rates, response times
- **Resources Panel**: Progress bars with thresholds
- **Services Panel**: Health status for each component
- **Bots Panel**: List of active bots with metrics
---
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `V` | Toggle between Live and Grid view |
| `R` | Refresh all metrics immediately |
| `F` | Toggle fullscreen mode |
| `?` | Show keyboard shortcuts |
---
## Alert Configuration
Configure alert thresholds in `config.csv`: Configure alert thresholds in `config.csv`:
```/dev/null/config-alerts.csv ```/dev/null/config-alerts.csv#L1-6
name,value name,value
alert-cpu-threshold,80 alert-cpu-threshold,80
alert-memory-threshold,85 alert-memory-threshold,85
@ -182,78 +236,93 @@ alert-response-time-ms,5000
alert-email,admin@example.com alert-email,admin@example.com
``` ```
## Console Mode When thresholds are exceeded:
1. Service status turns amber/red
2. Alert notification sent to configured email
3. Activity ticker shows alert message
For terminal-based monitoring: ---
```/dev/null/console-command.bash ## Console Mode Monitoring
For terminal-based monitoring or headless servers:
```/dev/null/console-command.sh#L1
./botserver --console --monitor ./botserver --console --monitor
``` ```
Output: Output:
```/dev/null/console-output.txt
```/dev/null/console-output.txt#L1-6
[MONITOR] 2025-01-15 14:32:00 [MONITOR] 2025-01-15 14:32:00
Sessions: 12 active (peak: 47) Sessions: 12 active (peak: 47)
Messages: 1,234 today (89/hour) Messages: 1,234 today (89/hour)
CPU: 65% | MEM: 72% | GPU: 45% CPU: 65% | MEM: 72% | GPU: 45%
Services: 6/6 running Services: 6/6 running
Latest: User enrolled in Computer Science course
``` ```
## Tips & Best Practices ---
💡 **Watch the data packets** - Flowing animations indicate active communication between components ## Component Health Details
💡 **Monitor trends** - The session trend indicator (↑/↓) shows direction of change | Component | Metrics Monitored | Warning Signs |
|-----------|-------------------|---------------|
| **PostgreSQL** | Connection count, query rate, replication lag | > 80 connections, queries > 100ms |
| **Qdrant** | Vector count, search latency, memory | > 50ms search, > 80% memory |
| **MinIO** | Storage usage, object count, bandwidth | > 80% storage, high error rate |
| **BotModels** | Token usage, response latency, queue depth | > 2s response, queue > 10 |
| **Vault** | Seal status, policy count, auth failures | Sealed, repeated auth failures |
| **Cache** | Hit rate, memory usage, evictions | < 80% hit rate, frequent evictions |
💡 **Click services** - Click any service node in Live view to see detailed status ---
💡 **Set up alerts** - Configure thresholds before issues become critical ## Best Practices
💡 **Use keyboard shortcuts** - Press `R` for quick refresh, `V` to toggle views 1. **Keep monitoring visible** — Use a dedicated screen or dashboard monitor for operations
2. **Set appropriate thresholds** — Configure alerts before issues become critical
3. **Watch data flow** — Animated packets indicate active communication between components
4. **Monitor trends** — The session trend indicator (↑/↓) shows direction of change
5. **Use historical data** — Query `/api/monitoring/history` for trend analysis
6. **Enable Prometheus export** — Integrate with existing monitoring infrastructure
💡 **Check historical data** - Query `/api/monitoring/history` for trend analysis ---
## Troubleshooting ## Troubleshooting
### Dashboard not loading ### Dashboard Not Loading
**Possible causes:**
1. WebSocket connection failed
2. API endpoint unreachable
3. Browser blocking HTMX
**Solution:**
1. Check browser console for errors 1. Check browser console for errors
2. Verify `/api/monitoring/status` returns data 2. Verify `/api/monitoring/status` returns data
3. Refresh the page 3. Ensure WebSocket connection is established
4. Refresh the page
### Metrics showing "--" ### Metrics Showing "--"
**Possible causes:** 1. Wait 5-10 seconds for initial data load
1. Initial load in progress 2. Check network tab for failed API requests
2. API timeout 3. Verify all services are running
3. Service unavailable 4. Check BotServer logs for errors
**Solution:** ### Animations Stuttering
1. Wait 5-10 seconds for first update
2. Check network tab for failed requests
3. Verify services are running
### Animations stuttering 1. Close unused browser tabs
2. Enable hardware acceleration in browser settings
**Possible causes:**
1. High CPU usage
2. Many browser tabs open
3. Hardware acceleration disabled
**Solution:**
1. Close unused tabs
2. Enable hardware acceleration in browser
3. Use Grid view for lower resource usage 3. Use Grid view for lower resource usage
4. Check if system CPU is overloaded
### Service Showing Red
1. Check service-specific logs in `botserver-stack/logs/`
2. Verify Vault is unsealed
3. Check database connection limits
4. Restart the affected service
---
## See Also ## See Also
- [Monitoring API Reference](../chapter-10-api/monitoring-api.md) - [Console Mode](./console-mode.md) — Terminal-based interface
- [Console Mode](./console-mode.md) - [HTMX Architecture](./htmx-architecture.md) — How real-time updates work
- [Configuration Options](../chapter-08-config/README.md) - [Suite Manual](./suite-manual.md) — Complete user guide
- [Analytics App](./apps/analytics.md) - [Analytics App](./apps/analytics.md) — Business metrics and reporting

804
src/chapter-06-gbdialog/examples-consolidated.md
View file

File diff suppressed because it is too large Load diff

36
src/executive-vision.md
View file

@ -189,8 +189,40 @@ Pragmatismo develops General Bots as an open-source platform for enterprise AI a
--- ---
## QUICK START
Ready to see it in action? Skip to the hands-on guide:
**[⚡ Quick Start: Run Your First Bot in 5 Minutes →](./chapter-01/quick-start.md)**
Or continue reading for the full journey:
| Path | Time | Best For |
|------|------|----------|
| [Quick Start](./chapter-01/quick-start.md) | 5 min | Developers who want to dive in immediately |
| [Introduction](./introduction.md) | 10 min | Understanding the "No Forms" philosophy |
| [Chapter 01](./chapter-01/README.md) | 15 min | Complete installation and first conversation |
---
## NEXT STEPS ## NEXT STEPS
[Chapter 01: Run and Talk →](./chapter-01/README.md) <div class="wa-chat">
<div class="wa-message user">
<div class="wa-bubble">
<p>I want to try General Bots now</p>
<div class="wa-time">09:00</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>Great! Just run:</p>
<p><code>./botserver</code></p>
<p>Then open http://localhost:8080</p>
<p>That's it! 🚀</p>
<div class="wa-time">09:00</div>
</div>
</div>
</div>
Get started with your General Bots deployment in minutes. [Chapter 01: Run and Talk →](./chapter-01/README.md)

71
src/introduction.md
View file

@ -1,7 +1,16 @@
# Introduction to General Bots # Introduction to General Bots
> **⚡ Want to skip ahead?** [Quick Start →](./chapter-01/quick-start.md) gets you running in 5 minutes.
**Build conversational AI bots in minutes, not months.** General Bots lets you create intelligent chatbots by writing simple [BASIC scripts](./chapter-06-gbdialog/basics.md) and dropping in your [documents](./chapter-02/gbkb.md). No complex frameworks, no cloud dependencies, no AI expertise required. **Build conversational AI bots in minutes, not months.** General Bots lets you create intelligent chatbots by writing simple [BASIC scripts](./chapter-06-gbdialog/basics.md) and dropping in your [documents](./chapter-02/gbkb.md). No complex frameworks, no cloud dependencies, no AI expertise required.
| Your Goal | Go To |
|-----------|-------|
| Run a bot NOW | [Quick Start](./chapter-01/quick-start.md) |
| Understand the vision | Keep reading below |
| Write your first script | [Chapter 06: BASIC Dialogs](./chapter-06-gbdialog/README.md) |
| Add documents to bot | [Chapter 02: Packages](./chapter-02/README.md) |
## The No Forms Movement ## The No Forms Movement
<img src="./assets/general-bots-2017.svg" alt="General Bots in 2017" style="max-height: 300px; width: 100%; object-fit: contain;"> <img src="./assets/general-bots-2017.svg" alt="General Bots in 2017" style="max-height: 300px; width: 100%; object-fit: contain;">
@ -47,17 +56,57 @@ General Bots was born from this vision: **replace forms with conversations**.
### After: The Conversation Experience ### After: The Conversation Experience
``` <div class="wa-chat">
User: I need help with my order <div class="wa-message user">
Bot: I'd be happy to help! What's your order number? <div class="wa-bubble">
User: It's 12345 <p>I need help with my order</p>
Bot: Found it - your laptop order from last week. What's the issue? <div class="wa-time">10:30</div>
User: It arrived damaged </div>
Bot: I'm sorry to hear that. I'll create a return label for you. </div>
Should I send it to your email on file? <div class="wa-message bot">
User: Yes please <div class="wa-bubble">
Bot: Done! Check your inbox. Is there anything else? <p>I'd be happy to help! What's your order number?</p>
``` <div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>It's 12345</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>Found it - your laptop order from last week. What's the issue?</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>It arrived damaged</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>I'm sorry to hear that. I'll create a return label for you.</p>
<p>Should I send it to your email on file?</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>Yes please</p>
<div class="wa-time">10:31</div>
</div>
</div>
<div class="wa-message bot">
<div class="wa-bubble">
<p>✅ Done! Check your inbox. Is there anything else?</p>
<div class="wa-time">10:31</div>
</div>
</div>
</div>
**Benefits:** **Benefits:**
- Natural and intuitive - Natural and intuitive