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

Compare commits

merge into: GeneralBots:main
Branches Tags
GeneralBots:main
GeneralBots:master
...
pull from: GeneralBots:master
Branches Tags
GeneralBots:main
GeneralBots:master

No commits in common. "main" and "master" have entirely different histories.
main ... master

558 changed files with 7914 additions and 29267 deletions
Show stats Expand all files Collapse all files

18
.forgejo/workflows/botbook.yaml
View file

@ -2,10 +2,10 @@ name: GBCI
on:
workflow_dispatch:
push:
branches: ["main"]
pull_request:
branches: ["main"]
# push:
# branches: ["main"]
# pull_request:
# branches: ["main"]
jobs:
build:
@ -17,11 +17,6 @@ jobs:
- uses: actions/checkout@v4
- name: Install Rust
run: |
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable --profile minimal
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install mdBook
run: |
if ! command -v mdbook &> /dev/null; then
@ -33,6 +28,5 @@ jobs:
- name: Deploy documentation
run: |
sudo rm -rf /opt/gbo/bin/proxy/docs.pragmatismo.com.br/*
sudo cp -r ./book/* /opt/gbo/bin/proxy/docs.pragmatismo.com.br/
sudo chmod -R 777 /opt/gbo/bin/proxy/docs.pragmatismo.com.br/
sudo cp -r ./book/* /opt/gbo/tenants/pragmatismo/proxy/data/websites/docs.pragmatismo.com.br/
sudo chown -R www-data:www-data /opt/gbo/tenants/pragmatismo/proxy/data/websites/docs.pragmatismo.com.br/

754
PROMPT.md
View file

@ -1,7 +1,45 @@
# botbook Development Guide
# botbook Development Prompt Guide
**Version:** 6.2.0
**Purpose:** Documentation for General Bots (mdBook)
**Version:** 6.1.0
**Purpose:** LLM context for botbook documentation development
---
## Weekly Maintenance - EVERY MONDAY
### Package Review Checklist
**Every Monday, review the following:**
1. **Dependency Updates**
```bash
cargo outdated
cargo audit
```
2. **Package Consolidation Opportunities**
- Check if new crates can replace custom code
- Look for crates that combine multiple dependencies
- Review `Cargo.toml` for redundant dependencies
3. **Documentation Sync**
- Verify docs match current implementation
- Check for deprecated keywords/features
- Update examples with latest syntax
4. **Asset Updates**
- Sync icons with `botui/ui/suite/assets/icons/`
- Verify all screenshots are current
- Check external links are valid
### Packages to Watch
| Area | Potential Packages | Purpose |
|------|-------------------|---------|
| Markdown | `pulldown-cmark` | Better MD processing |
| Search | `tantivy` | Full-text search in docs |
| Diagrams | `mermaid` | Replace ASCII diagrams |
| i18n | `fluent` | Translation management |
---
@ -9,25 +47,31 @@
**Keywords NEVER use underscores. Always use spaces.**
### Correct Syntax
### ✅ Correct Syntax
```basic
SEND MAIL to, subject, body, attachments
GENERATE PDF template, data, output
MERGE PDF files, output
DELETE "url"
DELETE "table", "filter"
ON ERROR RESUME NEXT
CLEAR ERROR
SET BOT MEMORY key, value
GET BOT MEMORY key
KB STATISTICS
KB DOCUMENTS COUNT
```
### WRONG - Never Use Underscores
### ❌ WRONG - Never Use Underscores
```basic
SEND_MAIL ' WRONG!
GENERATE_PDF ' WRONG!
MERGE_PDF ' WRONG!
DELETE_HTTP ' WRONG!
SET_HEADER ' WRONG!
```
### Keyword Mappings
### Keyword Mappings (Documentation to Implementation)
| Write This | NOT This |
|------------|----------|
| `SEND MAIL` | `SEND_MAIL` |
@ -35,13 +79,58 @@ DELETE_HTTP ' WRONG!
| `MERGE PDF` | `MERGE_PDF` |
| `DELETE` | `DELETE_HTTP` |
| `SET HEADER` | `SET_HEADER` |
| `CLEAR HEADERS` | `CLEAR_HEADERS` |
| `GROUP BY` | `GROUP_BY` |
| `FOR EACH` | `FOR_EACH` |
| `EXIT FOR` | `EXIT_FOR` |
| `ON ERROR RESUME NEXT` | (no underscore version) |
### Special Keywords
- `GENERATE FROM TEMPLATE` = Use `FILL` keyword
- `GENERATE WITH PROMPT` = Use `LLM` keyword
- `DELETE` is unified - auto-detects HTTP URLs vs database tables vs files
---
## OFFICIAL ICONS - MANDATORY
## Official Icons - MANDATORY
**NEVER generate icons with LLM. Use official SVG icons from `botui/ui/suite/assets/icons/`**
**NEVER generate icons with LLM. ALWAYS use official SVG icons from `src/assets/icons/`.**
### Available Icons
| Icon | File | Usage |
|------|------|-------|
| Logo | `gb-logo.svg` | Main GB branding |
| Bot | `gb-bot.svg` | Bot/assistant representation |
| Analytics | `gb-analytics.svg` | Charts, metrics, dashboards |
| Calendar | `gb-calendar.svg` | Scheduling, events |
| Chat | `gb-chat.svg` | Conversations, messaging |
| Compliance | `gb-compliance.svg` | Security, auditing |
| Designer | `gb-designer.svg` | Workflow automation |
| Drive | `gb-drive.svg` | File storage, documents |
| Mail | `gb-mail.svg` | Email functionality |
| Meet | `gb-meet.svg` | Video conferencing |
| Paper | `gb-paper.svg` | Document editing |
| Research | `gb-research.svg` | Search, investigation |
| Sources | `gb-sources.svg` | Knowledge bases |
| Tasks | `gb-tasks.svg` | Task management |
| Chart | `gb-chart.svg` | Data visualization |
| Check | `gb-check.svg` | Success, completion |
| Database | `gb-database.svg` | Data storage |
| Folder | `gb-folder.svg` | File organization |
| Gear | `gb-gear.svg` | Settings |
| Globe | `gb-globe.svg` | Web, internet |
| Lightbulb | `gb-lightbulb.svg` | Ideas, tips |
| Lock | `gb-lock.svg` | Security |
| Note | `gb-note.svg` | Notes, comments |
| Package | `gb-package.svg` | Packages, modules |
| Palette | `gb-palette.svg` | Themes, styling |
| Rocket | `gb-rocket.svg` | Launch, deploy |
| Search | `gb-search.svg` | Search functionality |
| Signal | `gb-signal.svg` | Connectivity |
| Target | `gb-target.svg` | Goals, objectives |
| Tree | `gb-tree.svg` | Hierarchy, structure |
| Warning | `gb-warning.svg` | Alerts, cautions |
### Usage in Documentation
@ -49,13 +138,53 @@ DELETE_HTTP ' WRONG!
<!-- Reference icons in docs -->
![Chat](../assets/icons/gb-chat.svg)
<!-- With HTML for sizing -->
<!-- Or with HTML for sizing -->
<img src="../assets/icons/gb-analytics.svg" alt="Analytics" width="24">
```
### Icon Guidelines
- All icons use `stroke="currentColor"` for CSS theming
- ViewBox: `0 0 24 24`
- Stroke width: `1.5`
- Rounded line caps and joins
- Consistent with GB brand identity
**DO NOT:**
- Generate new icons with AI/LLM
- Use emoji or unicode symbols as icons
- Use external icon libraries (FontAwesome, etc.)
- Create inline SVG diagrams when an official icon exists
---
## STRUCTURE
## Project Overview
botbook is the **mdBook-based documentation** for the General Bots platform. It provides comprehensive guides, tutorials, and API references for users and developers.
### Workspace Position
```
botbook/ # THIS PROJECT - Documentation
botserver/ # Main server (source of truth)
botlib/ # Shared library
botui/ # Web/Desktop UI
botapp/ # Desktop app
botmodels/ # Data models visualization
botplugin/ # Browser extension
```
### What botbook Provides
- **User Guides**: Getting started, installation, quick start
- **BASIC Reference**: Keywords, syntax, examples
- **API Documentation**: REST endpoints, WebSocket
- **Configuration**: Settings, environment variables
- **Architecture**: System design, components
---
## Structure
```
botbook/
@ -63,40 +192,194 @@ botbook/
├── src/
│ ├── SUMMARY.md # Table of contents
│ ├── README.md # Introduction
│ ├── 01-introduction/ # Quick Start
│ ├── 01-introduction/ # Run and Talk (Quick Start)
│ ├── 02-templates/ # Package System
│ ├── 03-knowledge-base/ # Knowledge Base
│ ├── 04-gbui/ # UI System
│ ├── 05-gbtheme/ # Theming
│ ├── 06-gbdialog/ # BASIC Dialogs
│ ├── 07-gbapp/ # Applications
│ ├── 08-config/ # Configuration
│ ├── 09-tools/ # Tools
│ ├── 10-rest/ # REST API
│ ├── 11-features/ # Feature Modules
│ ├── 12-auth/ # Authentication
│ ├── 13-community/ # Contributing
│ ├── 14-migration/ # Migration Guide
│ ├── 15-appendix/ # Reference materials
│ ├── 16-appendix-docs-style/
│ ├── 17-testing/ # Testing guide
│ ├── 18-appendix-external-services/
│ ├── 19-maintenance/ # Maintenance
│ └── assets/ # Images, diagrams
├── i18n/ # Translations
│ ├── cn/ # Chinese
│ ├── en/ # English
│ ├── ja/ # Japanese
│ └── pt/ # Portuguese
└── book/ # Generated output
```
---
## DOCUMENTATION RULES
## Documentation Rules
### CRITICAL REQUIREMENTS
```
- All documentation MUST match actual source code
- Extract real keywords from botserver/src/basic/keywords/
- Reference real models from botserver/src/shared/models.rs
- Use actual examples from botserver/templates/
- Version numbers must be 6.2.0
- Version numbers must be 6.1.0
- No placeholder content - only verified features
```
### Writing Style
```
- Beginner-friendly, instructional tone
- Practical examples that work
- Step-by-step instructions
- Clear headings and structure
- Use mdBook admonitions for tips/warnings
```
### Code Examples
```markdown
<!-- For BASIC examples -->
```bas
TALK "Hello, world!"
name = HEAR
TALK "Welcome, " + name
' Error handling
ON ERROR RESUME NEXT
result = SOME_OPERATION()
IF ERROR THEN
TALK "Error: " + ERROR MESSAGE
END IF
ON ERROR GOTO 0
' Email - note: spaces not underscores
SEND MAIL "user@example.com", "Subject", "Body", []
' PDF generation - note: spaces not underscores
GENERATE PDF "template.html", data, "output.pdf"
' Unified DELETE - auto-detects context
DELETE "https://api.example.com/resource/123" ' HTTP DELETE
DELETE "customers", "status = 'inactive'" ' Database DELETE
DELETE "temp/file.txt" ' File DELETE
```
<!-- For configuration -->
```csv
name,value
server_port,8080
llm-url,http://localhost:8081
```
<!-- For Rust (only in gbapp chapter) -->
```rust
use botlib::prelude::*;
```
```
---
## NO ASCII DIAGRAMS - MANDATORY
## Building Documentation
**NEVER use ASCII art diagrams. ALL diagrams must be SVG.**
```bash
# Install mdBook
cargo install mdbook
# Build documentation
cd botbook
mdbook build
# Serve locally with hot reload
mdbook serve --open
# Build specific language
mdbook build --dest-dir book-pt src-pt
```
---
## Chapter Content Guidelines
### Chapter 1: Run and Talk
- Quick start (5 minutes to running bot)
- Bootstrap process explanation
- First conversation walkthrough
- Session management basics
### Chapter 2: Package System
- .gbai folder structure
- .gbot configuration
- .gbdialog scripts
- .gbkb knowledge bases
- .gbtheme customization
### Chapter 6: BASIC Dialogs
- Keyword reference (from source)
- TALK, HEAR, SET, GET
- Control flow (IF, FOR, WHILE)
- Tool creation
- LLM integration
### Chapter 8: Configuration
- config.csv format
- Environment variables
- Database configuration
- Service settings
---
## Source Code References
When documenting features, verify against actual source:
| Topic | Source Location |
|-------|-----------------|
| BASIC Keywords | `botserver/src/basic/keywords/` |
| Database Models | `botserver/src/shared/models.rs` |
| API Routes | `botserver/src/core/urls.rs` |
| Configuration | `botserver/src/core/config/` |
| Bootstrap | `botserver/src/core/bootstrap/` |
| Templates | `botserver/templates/` |
| Error Handling | `botserver/src/basic/keywords/errors/` |
### Key Implementation Files
| Keyword Category | File |
|-----------------|------|
| `SEND MAIL`, `SEND TEMPLATE` | `send_mail.rs` |
| `GENERATE PDF`, `MERGE PDF` | `file_operations.rs` |
| `DELETE`, `INSERT`, `UPDATE` | `data_operations.rs` |
| `POST`, `PUT`, `GRAPHQL`, `SOAP` | `http_operations.rs` |
| `ON ERROR RESUME NEXT` | `errors/on_error.rs` |
| `KB STATISTICS`, `KB DOCUMENTS COUNT` | `kb_statistics.rs` |
| `LLM` | `llm_keyword.rs` |
| `FILL` (template filling) | `data_operations.rs` |
---
## NO ASCII DIAGRAMS — MANDATORY
**NEVER use ASCII art diagrams in documentation. ALL diagrams must be SVG.**
### Prohibited ASCII Patterns
```
+-------+
| Box |
+-------+
❌ NEVER USE:
┌─────────┐ ╔═══════╗ +-------+
│ Box │ ║ Box ║ | Box |
└─────────┘ ╚═══════╝ +-------+
├── folder/ │ → ▶ ──►
│ └── file ▼ ← ◀ ◄──
```
### What to Use Instead
@ -105,175 +388,338 @@ botbook/
|---------------|--------|
| ASCII box diagrams | SVG diagrams in `assets/` |
| ASCII flow charts | SVG with arrows and boxes |
| ASCII directory trees | Markdown tables |
| ASCII directory trees | Markdown tables or SVG |
| ASCII tables with borders | Markdown tables |
| ASCII progress indicators | SVG or text description |
### Directory Trees → Tables
```markdown
❌ WRONG:
mybot.gbai/
├── mybot.gbdialog/
│ └── start.bas
└── mybot.gbot/
└── config.csv
✅ CORRECT:
| Path | Description |
|------|-------------|
| `mybot.gbai/` | Root package |
| `mybot.gbdialog/` | BASIC scripts |
| `mybot.gbdialog/start.bas` | Entry point |
| `mybot.gbot/` | Configuration |
| `mybot.gbot/config.csv` | Bot settings |
```
### Rationale
- ASCII breaks in different fonts/editors
- Not accessible for screen readers
- Cannot adapt to dark/light themes
- Looks unprofessional in modern docs
- SVGs scale perfectly at any size
---
## SVG DIAGRAM GUIDELINES
## SVG Diagram Guidelines — Theme Transparency
All SVGs must support light/dark modes:
All SVG diagrams MUST be theme-agnostic and work with light/dark modes.
### Required Structure
Every SVG must include:
1. **CSS classes for text** (not hardcoded colors)
2. **Dark mode media query** in `<style>` block
3. **Standard gradient definitions** in `<defs>`
### Required CSS Block
```xml
<style>
.title-text { fill: #1E1B4B; }
.main-text { fill: #334155; }
.title-text { fill: #1E1B4B; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
.main-text { fill: #334155; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
.secondary-text { fill: #64748B; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
.white-text { fill: #FFFFFF; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
.mono-text { fill: #475569; font-family: 'SF Mono', 'Fira Code', Consolas, monospace; }
@media (prefers-color-scheme: dark) {
.title-text { fill: #F1F5F9; }
.main-text { fill: #E2E8F0; }
.secondary-text { fill: #94A3B8; }
.mono-text { fill: #CBD5E1; }
}
</style>
```
### Standard Gradients (use these IDs)
| Gradient ID | Colors | Purpose |
|-------------|--------|---------|
| `primaryGrad` | `#6366F1` → `#8B5CF6` | Primary/purple elements |
| `cyanGrad` | `#06B6D4` → `#0EA5E9` | Cyan/info elements |
| `greenGrad` | `#10B981` → `#34D399` | Success/green elements |
| `orangeGrad` | `#F59E0B` → `#FBBF24` | Warning/orange elements |
### Background Rules
- Use `fill="#FAFBFC"` for main background (not pure white)
- Add dot pattern overlay: `fill="url(#dots)"` with `opacity="0.08"`
- Cards use `fill="#FFFFFF"` with `stroke="#E2E8F0"` for definition
- Use `filter="url(#cardShadow)"` for card depth
### DO NOT
- ❌ Hardcode text colors without CSS class
- ❌ Use pure black (`#000000`) for text
- ❌ Forget the `@media (prefers-color-scheme: dark)` block
- ❌ Create new gradient IDs when standard ones exist
- ❌ Use ASCII art diagrams when SVG is appropriate
### DO
- ✅ Use CSS classes for ALL text elements
- ✅ Include dark mode media query in every SVG
- ✅ Use standard gradient IDs consistently
- ✅ Test SVGs in both light and dark browser modes
- ✅ Convert ASCII diagrams to proper SVGs
- ✅ Place SVGs in `src/assets/chapter-XX/` directories
### Dimensions
- Width: 600-1200px (responsive)
- Use `style="max-width: 100%; height: auto;"` when embedding
### Reference
See `src/16-appendix-docs-style/svg.md` for complete guidelines.
---
## CONVERSATION EXAMPLES
## Translation Workflow
Use WhatsApp-style HTML format for bot interactions:
1. English is source of truth (`src/`)
2. Translations in `src-{lang}/`
3. Keep structure identical
4. Update `book.toml` for each language
5. Build separately per language
---
## Quality Checklist
Before committing documentation:
- [ ] All code examples tested and working
- [ ] Version numbers are 6.1.0
- [ ] Links are valid (relative paths)
- [ ] Images have alt text
- [ ] SUMMARY.md is updated
- [ ] mdbook build succeeds without errors
- [ ] Content matches actual source code
- [ ] **NO underscores in keyword names** (use spaces)
- [ ] Model names are generic or current (no gpt-4o, claude-3, etc.)
- [ ] Error handling uses `ON ERROR RESUME NEXT` pattern correctly
---
## Rules
- **Accuracy**: Must match botserver source code
- **Completeness**: No placeholder sections
- **Clarity**: Accessible to BASIC enthusiasts
- **Version**: Always reference 6.1.0
- **Examples**: Only working, tested code
- **Structure**: Follow mdBook conventions
- **Keywords**: NEVER use underscores - always spaces
- **Models**: Use generic references or current model names
- **Errors**: Document `ON ERROR RESUME NEXT` for error handling
---
## Quick Reference: Implemented Keywords
### Error Handling
```basic
ON ERROR RESUME NEXT ' Enable error trapping
ON ERROR GOTO 0 ' Disable error trapping
CLEAR ERROR ' Clear error state
IF ERROR THEN ' Check if error occurred
ERROR MESSAGE ' Get last error message
ERR ' Get error number
THROW "message" ' Raise an error
```
### HTTP Operations
```basic
POST "url", data
PUT "url", data
PATCH "url", data
DELETE "url" ' Unified - works for HTTP, DB, files
SET HEADER "name", "value"
CLEAR HEADERS
GRAPHQL "url", query, variables
SOAP "wsdl", "operation", params
```
### File & PDF Operations
```basic
READ "path"
WRITE "path", content
COPY "source", "dest"
MOVE "source", "dest"
LIST "path"
COMPRESS files, "archive.zip"
EXTRACT "archive.zip", "dest"
UPLOAD file
DOWNLOAD "url"
GENERATE PDF template, data, "output.pdf"
MERGE PDF files, "output.pdf"
```
### Data Operations
```basic
FIND "table", "filter"
SAVE "table", data
INSERT "table", data
UPDATE "table", data, "filter"
DELETE "table", "filter"
MERGE "table", data, "key"
FILL data, template ' Template filling (was GENERATE FROM TEMPLATE)
MAP data, "mapping"
FILTER data, "condition"
AGGREGATE data, "operation"
```
### Knowledge Base & Accounts
```basic
USE KB "collection"
USE ACCOUNT "email@example.com" ' LLM search + file ops
CLEAR KB
KB STATISTICS
KB COLLECTION STATS "name"
KB DOCUMENTS COUNT
KB DOCUMENTS ADDED SINCE days
KB LIST COLLECTIONS
KB STORAGE SIZE
```
### LLM Operations
```basic
result = LLM "prompt" ' Generate with LLM (was GENERATE WITH PROMPT)
USE MODEL "model-name"
```
### Communication
```basic
TALK "message"
HEAR variable
SEND MAIL to, subject, body
SEND MAIL to, subject, body USING "account@example.com"
SEND TEMPLATE recipients, template, variables
```
### File Operations with Accounts
```basic
' account:// path notation (requires USE ACCOUNT first)
COPY "account://user@gmail.com/file.pdf" TO "local.pdf"
COPY "local.xlsx" TO "account://user@outlook.com/data.xlsx"
```
---
## 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>
```
### 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. **Status indicators** — Use text indicators (Success, Error, etc.) not emojis
6. **Bold text** — Use `<strong>` for emphasis
7. **Attachments** — Indicate with text like "[Attachment: filename.pdf]"
### Complete Example
```html
<div class="wa-chat">
<div class="wa-message bot">
<div class="wa-bubble">
<p>Hello! How can I help?</p>
<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</p>
<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><strong>Success:</strong> 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>
```
---
### When to Use Each Format
## SOURCE CODE REFERENCES
| 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 |
| Topic | Source Location |
|-------|-----------------|
| BASIC Keywords | `botserver/src/basic/keywords/` |
| Database Models | `botserver/src/core/shared/models.rs` |
| API Routes | `botserver/src/core/urls.rs` |
| Configuration | `botserver/src/core/config/` |
| Templates | `botserver/templates/` |
---
## BUILDING BOTSERVER
**CRITICAL: ALWAYS USE DEBUG BUILD DURING DEVELOPMENT**
```bash
# CORRECT - Use debug build (FAST)
cargo build
# WRONG - NEVER use --release during development (SLOW)
# cargo build --release # DO NOT USE!
# Run debug server
cargo run
```
**Why Debug Build:**
- Debug builds compile in ~30 seconds
- Release builds take 5-10 minutes with LTO
- Debug builds are sufficient for development and testing
- Only use `--release` for production deployment
---
## BUILDING DOCUMENTATION
```bash
# Install mdBook
cargo install mdbook
# Build documentation
cd botbook && mdbook build
# Serve locally with hot reload
mdbook serve --open
```
---
## TESTING PROCEDURES
### Tool Testing Workflow
**CRITICAL: NO STOP UNTIL NO MORE ERRORS IN TOOLS**
When testing bot tools, follow this sequential process WITHOUT STOPPING:
```
1. Test Tool #1
├─ Fill form one field at a time (if multi-step form)
├─ Verify NO ERRORS in output
├─ Check Result types are NOT visible (no "core::result::Result<..." strings)
├─ Verify database save (if applicable)
├─ IF ERRORS FOUND: FIX THEM IMMEDIATELY, RE-TEST SAME TOOL
├─ ONLY move to next tool when CURRENT tool has ZERO errors
2. Test Tool #2
└─ (repeat process - DO NOT STOP if errors found)
3. Continue until ALL tools tested with ZERO errors
```
**IMPORTANT:**
- Do NOT stop testing to summarize or ask questions
- Do NOT move to next tool if current tool has errors
- Fix errors immediately, rebuild, re-test same tool
- Only proceed when current tool is completely error-free
### Error Patterns to Watch For
**CRITICAL ERRORS (Must Fix Before Proceeding):**
- `core::result::Result<alloc::string::String, alloc::string::String>` in output
- `invalid input syntax for type timestamp`
- `Some("Desculpe, houve um erro...")`
- Empty balloon messages
- Rust debug info visible to users
### Playwright Testing Tricks
```javascript
// Click tool button
await page.getByRole('button', { name: 'Evento/Iluminação' }).click();
// Wait for response
await page.waitForTimeout(3000);
// Take snapshot
await page.snapshot();
// Fill form field by field
await page.getByRole('textbox').fill('field value');
await page.getByRole('textbox').press('Enter');
```
### Test Documentation
After testing each tool, document:
1. Tool name and ID
2. All required parameters
3. Expected behavior
4. Any issues found and fixes applied
5. Final test result (PASS/FAIL)
---
## REMEMBER
- **Accuracy** - Must match botserver source code
- **Completeness** - No placeholder sections
- **Clarity** - Accessible to BASIC enthusiasts
- **Keywords** - NEVER use underscores - always spaces
- **NO ASCII art** - Use SVG diagrams only
- **Version 6.2.0** - Always reference 6.2.0
- **GIT WORKFLOW** - ALWAYS push to ALL repositories (github, pragmatismo)
- **TESTING** - Test tools ONE BY ONE, fix ALL errors before moving to next tool
- **NO STOP** - DO NOT STOP testing until ALL tools have ZERO errors - fix immediately and re-test
The WhatsApp chat styling is defined in `src/whatsapp-chat.css` and automatically included in the book build.

273
README.md
View file

@ -1,17 +1,10 @@
# General Bots Documentation (BotBook)
**Version:** 6.2.0
**Purpose:** Comprehensive documentation for General Bots (mdBook format)
# General Bots
![General Bots Logo](https://github.com/GeneralBots/botserver/blob/main/logo.png?raw=true)
---
**Enterprise-Grade LLM Orchestrator & AI Automation Platform**
## Overview
BotBook is the official documentation repository for General Bots, built using [mdBook](https://rust-lang.github.io/mdBook/). It provides comprehensive guides, API references, tutorials, and architectural documentation for the entire General Bots platform - an enterprise-grade LLM orchestrator and AI automation platform.
For the latest live documentation, visit **[docs.pragmatismo.com.br](https://docs.pragmatismo.com.br)**.
A strongly-typed, self-hosted conversational platform focused on convention over configuration and code-less approaches.
---
@ -21,7 +14,7 @@ For the latest live documentation, visit **[docs.pragmatismo.com.br](https://doc
---
## 📦 General Bots Repositories
## 📦 Repositories
| Repository | Description | Status |
|------------|-------------|--------|
@ -40,7 +33,6 @@ For the latest live documentation, visit **[docs.pragmatismo.com.br](https://doc
- **Rust** (latest stable) - [Install from rustup.rs](https://rustup.rs/)
- **Git** - [Download from git-scm.com](https://git-scm.com/downloads)
- **mdBook** - `cargo install mdbook`
### Run the Server
@ -71,20 +63,6 @@ cd botapp
cargo tauri dev
```
### Build Documentation
```bash
# Clone botbook
git clone https://github.com/GeneralBots/botbook
cd botbook
# Build documentation
mdbook build
# Serve locally with hot reload
mdbook serve --open
```
---
## ✨ Key Features
@ -122,182 +100,6 @@ CLEAR TOOLS ' Remove all tools from session
---
## 📁 Documentation Structure
```
botbook/
├── book.toml # mdBook configuration
├── src/
│ ├── SUMMARY.md # Table of contents
│ ├── README.md # Introduction
│ ├── 01-introduction/ # Quick Start
│ ├── 02-templates/ # Package System
│ ├── 03-knowledge-base/ # Knowledge Base
│ ├── 04-gbui/ # UI Interface
│ ├── 06-gbdialog/ # BASIC Dialogs
│ ├── 08-config/ # Configuration
│ ├── 10-rest/ # REST API
│ ├── 12-auth/ # Authentication
│ └── assets/ # Images, diagrams
├── i18n/ # Translations
└── book/ # Generated output
```
---
## 📚 Documentation Writing Guidelines
### ✅ Keyword Naming Rules - MANDATORY
**Keywords NEVER use underscores. Always use spaces.**
| Write This | NOT This |
|------------|----------|
| `SEND MAIL` | `SEND_MAIL` |
| `GENERATE PDF` | `GENERATE_PDF` |
| `MERGE PDF` | `MERGE_PDF` |
| `DELETE` | `DELETE_HTTP` |
| `SET HEADER` | `SET_HEADER` |
| `FOR EACH` | `FOR_EACH` |
#### Correct Syntax Examples
```basic
SEND MAIL to, subject, body, attachments
GENERATE PDF template, data, output
MERGE PDF files, output
DELETE "url"
ON ERROR RESUME NEXT
SET BOT MEMORY key, value
KB STATISTICS
```
#### ❌ NEVER Use Underscores
```basic
SEND_MAIL ' WRONG!
GENERATE_PDF ' WRONG!
DELETE_HTTP ' WRONG!
```
---
### 🎨 Official Icons - MANDATORY
**NEVER generate icons with LLM. Use official SVG icons from `botui/ui/suite/assets/icons/`**
#### Usage in Documentation
```markdown
<!-- Reference icons in docs -->
![Chat](../assets/icons/gb-chat.svg)
<!-- With HTML for sizing -->
<img src="../assets/icons/gb-analytics.svg" alt="Analytics" width="24">
```
#### Required Icons
```
ui/suite/assets/icons/
├── gb-logo.svg # Main GB logo
├── gb-bot.svg # Bot/assistant
├── gb-analytics.svg # Analytics
├── gb-calendar.svg # Calendar
├── gb-chat.svg # Chat
├── gb-drive.svg # File storage
├── gb-mail.svg # Email
├── gb-meet.svg # Video meetings
├── gb-tasks.svg # Task management
└── ...
```
All icons use `stroke="currentColor"` for CSS theming.
---
### 🚫 NO ASCII Diagramrams - MANDATORY
**NEVER use ASCII art diagrams. ALL diagrams must be SVG.**
#### ❌ Prohibited ASCII Patterns
```
┌─────────┐ ╔═══════╗ +-------+
│ Box │ ║ Box ║ | Box |
└─────────┘ ╚═══════╝ +-------+
```
#### ✅ What to Use Instead
| Instead of... | Use... |
|---------------|--------|
| ASCII box diagrams | SVG diagrams in `assets/` |
| ASCII flow charts | SVG with arrows and boxes |
| ASCII directory trees | Markdown tables |
---
### 🎨 SVG Diagram Guidelines
All SVGs must support light/dark modes:
```xml
<style>
.title-text { fill: #1E1B4B; }
.main-text { fill: #334155; }
@media (prefers-color-scheme: dark) {
.title-text { fill: #F1F5F9; }
.main-text { fill: #E2E8F0; }
}
</style>
```
---
### 💬 Conversation Examples
Use WhatsApp-style HTML format for bot interactions:
```html
<div class="wa-chat">
<div class="wa-message bot">
<div class="wa-bubble">
<p>Hello! How can I help?</p>
<div class="wa-time">10:30</div>
</div>
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>I want to enroll</p>
<div class="wa-time">10:31</div>
</div>
</div>
</div>
```
---
### 📋 Source Code References
| Topic | Source Location |
|-------|-----------------|
| BASIC Keywords | `botserver/src/basic/keywords/` |
| Database Models | `botserver/src/shared/models.rs` |
| API Routes | `botserver/src/core/urls.rs` |
| Configuration | `botserver/src/core/config/` |
| Templates | `botserver/templates/` |
---
### 📖 Documentation Accuracy Rules
```
- All documentation MUST match actual source code
- Extract real keywords from botserver/src/basic/keywords/
- Use actual examples from botserver/templates/
- Version numbers must be 6.2.0
- No placeholder content - only verified features
```
---
## 🏛️ Architecture Details
### botserver (Core)
@ -331,14 +133,31 @@ Common Rust code shared across projects:
---
## 🛡️ Security
## 🔧 Development Setup
- **AGPL-3.0 License** - True open source with contribution requirements
- **Self-hosted** - Your data stays on your infrastructure
- **Enterprise-grade** - 5+ years of stability
- **No vendor lock-in** - Open protocols and standards
```bash
# Clone all repositories
git clone https://github.com/GeneralBots/botserver botserver
git clone https://github.com/GeneralBots/botui
git clone https://github.com/GeneralBots/botapp
git clone https://github.com/GeneralBots/botlib
git clone https://github.com/GeneralBots/botbook botbook
Report security issues to: **security@pragmatismo.com.br**
# Build all (from each directory)
cd botlib && cargo build
cd ../botserver && cargo build
cd ../botui && cargo build
cd ../botapp && cargo build
```
---
## 📖 Documentation
- **[Complete Documentation](https://github.com/GeneralBots/botbook)** - Full mdBook documentation
- **[Quick Start Guide](https://github.com/GeneralBots/botserver/blob/main/docs/QUICK_START.md)** - Get started in minutes
- **[API Reference](https://github.com/GeneralBots/botserver/blob/main/docs/src/chapter-10-api/README.md)** - REST API documentation
- **[Architecture Guide](https://github.com/GeneralBots/botserver/blob/main/docs/src/chapter-07-gbapp/README.md)** - System architecture
---
@ -353,16 +172,14 @@ Report security issues to: **security@pragmatismo.com.br**
---
## 🔗 Links
## 🛡️ Security
- **Website:** [pragmatismo.com.br](https://pragmatismo.com.br)
- **Documentation:** [docs.pragmatismo.com.br](https://docs.pragmatismo.com.br)
- **BotBook:** [Complete Documentation](https://github.com/GeneralBots/botbook)
- **Quick Start:** [Get Started in Minutes](https://github.com/GeneralBots/botserver/blob/main/docs/QUICK_START.md)
- **API Reference:** [REST API Documentation](https://github.com/GeneralBots/botserver/blob/main/docs/src/chapter-10-api/README.md)
- **Architecture:** [System Architecture Guide](https://github.com/GeneralBots/botserver/blob/main/docs/src/chapter-07-gbapp/README.md)
- **Stack Overflow:** Tag questions with `generalbots`
- **Video Tutorial:** [7 AI General Bots LLM Templates](https://www.youtube.com/watch?v=KJgvUPXi3Fw)
- **AGPL-3.0 License** - True open source with contribution requirements
- **Self-hosted** - Your data stays on your infrastructure
- **Enterprise-grade** - 5+ years of stability
- **No vendor lock-in** - Open protocols and standards
Report security issues to: **security@pragmatismo.com.br**
---
@ -378,19 +195,6 @@ We welcome contributions! See our [Contributing Guidelines](https://github.com/G
---
## 🔑 Remember
- **Accuracy** - Must match botserver source code
- **Completeness** - No placeholder sections
- **Clarity** - Accessible to BASIC enthusiasts
- **Keywords** - NEVER use underscores - always spaces
- **NO ASCII art** - Use SVG diagrams only
- **Official icons** - Use icons from botui/ui/suite/assets/icons/
- **Version 6.2.0** - Always reference 6.2.0
- **GIT WORKFLOW** - ALWAYS push to ALL repositories (github, pragmatismo)
---
## 📄 License
General Bots is licensed under **AGPL-3.0**.
@ -401,6 +205,15 @@ Copyright (c) pragmatismo.com.br. All rights reserved.
---
## 🔗 Links
- **Website:** [pragmatismo.com.br](https://pragmatismo.com.br)
- **Documentation:** [docs.pragmatismo.com.br](https://docs.pragmatismo.com.br)
- **Stack Overflow:** Tag questions with `generalbots`
- **Video Tutorial:** [7 AI General Bots LLM Templates](https://www.youtube.com/watch?v=KJgvUPXi3Fw)
---
> **Code Name:** [Guaribas](https://en.wikipedia.org/wiki/Guaribas) (a city in Brazil, state of Piauí)
>
> *"No one should have to do work that can be done by a machine."* - Roberto Mangabeira Unger

7
book.toml
View file

@ -2,7 +2,7 @@
title = "General Bots Documentation"
authors = ["General Bots Team"]
language = "en"
multilingual = false
src = "src"
[build]
@ -12,7 +12,8 @@ build-dir = "book"
default-theme = "light"
preferred-dark-theme = "navy"
smart-punctuation = true
additional-css = ["src/custom.css", "src/whatsapp-chat.css", "src/designer-panel.css"]
additional-css = ["src/custom.css", "src/whatsapp-chat.css"]
additional-js = ["src/theme-sync.js"]
[output.html.favicon]
png = "favicon.png"

4
src/01-getting-started/README.md → src/01-introduction/README.md
View file

@ -35,7 +35,7 @@ By the end of this chapter, you will:
./botserver
```
Open `http://localhost:9000`. Start chatting. That's it.
Open `http://localhost:8080`. Start chatting. That's it.
Everything installs automatically on first run—PostgreSQL, storage, cache, and your first bot.
@ -55,7 +55,7 @@ Everything installs automatically on first run—PostgreSQL, storage, cache, and
<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:9000</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>

0
src/01-getting-started/assets/bootstrap-process.svg.backup → src/01-introduction/assets/bootstrap-process.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

0
src/01-getting-started/assets/quick-start-bootstrap.svg.backup → src/01-introduction/assets/quick-start-bootstrap.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9 KiB

After

Width:  |  Height:  |  Size: 9 KiB

0
src/01-getting-started/assets/session-manager.svg.backup → src/01-introduction/assets/session-manager.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.9 KiB

After

Width:  |  Height:  |  Size: 7.9 KiB

0
src/01-getting-started/assets/session-states.svg.backup → src/01-introduction/assets/session-states.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.9 KiB

After

Width:  |  Height:  |  Size: 6.9 KiB

0
src/01-getting-started/assets/tool-execution-flow.svg.backup → src/01-introduction/assets/tool-execution-flow.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.1 KiB

After

Width:  |  Height:  |  Size: 9.1 KiB

2
src/01-getting-started/first-conversation.md → src/01-introduction/first-conversation.md
View file

@ -4,7 +4,7 @@ After botserver starts, you can immediately start chatting with your bot. No pro
## Just Start Talking
Open your browser to `http://localhost:9000` and start chatting:
Open your browser to `http://localhost:8080` and start chatting:
```
You: Hi!

38
src/01-getting-started/installation.md → src/01-introduction/installation.md
View file

@ -31,10 +31,7 @@ sudo apt install -y \
zlib1g \
ca-certificates \
curl \
wget \
libabseil-dev \
libclang-dev \
pkg-config
wget
# For container support (LXC)
sudo snap install lxd
@ -120,7 +117,7 @@ psql $DATABASE_URL -c "SELECT version();"
curl http://localhost:8081/v1/models
# Open UI
open http://localhost:9000
open http://localhost:8080
```
## Bot Deployment
@ -175,33 +172,8 @@ Requires CUDA installed and 12GB+ VRAM.
| Method | Use Case | Guide |
|--------|----------|-------|
| **Local** | Development, single instance | This page |
| **Docker** | Production, microservices | [Docker Deployment](../02-architecture-packages/docker-deployment.md) |
| **LXC** | Isolated components, Linux | [Container Deployment](../02-architecture-packages/containers.md) |
| **Brother Mode** | Container managing host containers | See below |
### Container-on-Host (Brother Mode)
You can run `botserver` inside a container (Docker/LXC) while letting it manage other containers directly on the host system. This is useful for CI/CD pipelines or managing "host" deployment from a restricted environment.
**Requirements:**
- Mount host's LXD socket to container
- Run container as privileged (if accessing host devices)
**Docker Run Example:**
```bash
docker run -d \
--name botserver \
--network host \
--privileged \
-v /var/snap/lxd/common/lxd/unix.socket:/var/snap/lxd/common/lxd/unix.socket \
-e VAULT_ADDR="https://127.0.0.1:8200" \
-e VAULT_TOKEN="<your-token>" \
botserver:latest
```
> **Note**: For non-snap LXD, use `-v /var/lib/lxd/unix.socket:/var/lib/lxd/unix.socket` instead.
The installer detects if it is running in a container but needs to manage the host (brother mode) and will configure the host's LXD/LXC environment safely.
| **Docker** | Production, microservices | [Docker Deployment](../chapter-07-gbapp/docker-deployment.md) |
| **LXC** | Isolated components, Linux | [Container Deployment](../chapter-07-gbapp/containers.md) |
> ⚠️ **IMPORTANT**: Container create commands (`botserver install ... --container`) must be run from the **host system**, not inside a container.
@ -229,4 +201,4 @@ lxc list | grep mycompany
- [Quick Start Guide](./quick-start.md) - Create your first bot
- [First Conversation](./first-conversation.md) - Test your bot
- [Configuration Reference](../10-configuration-deployment/README.md) - All settings
- [Configuration Reference](../chapter-08-config/README.md) - All settings

2
src/01-getting-started/local-domains.md → src/01-introduction/local-domains.md
View file

@ -10,7 +10,7 @@ botserver certificates include `127.0.0.1` as a Subject Alternative Name (SAN),
| Component | Description | IP:Port |
|-----------|-------------|---------|
| api | Main botserver API | `127.0.0.1:8443` (HTTPS) / `127.0.0.1:9000` (HTTP) |
| api | Main botserver API | `127.0.0.1:8443` (HTTPS) / `127.0.0.1:8080` (HTTP) |
| tables | PostgreSQL database | `127.0.0.1:5432` |
| drive | Object storage (S3-compatible) | `127.0.0.1:9000` |
| cache | Redis cache | `127.0.0.1:6379` |

23
src/01-getting-started/overview.md → src/01-introduction/overview.md
View file

@ -105,7 +105,7 @@ Installation begins by downloading and running the botserver binary. The bootstr
Bot deployment uses object storage buckets. Each bot receives its own bucket for file storage. Bots are deployed to the drive rather than the work folder, which is reserved for internal operations as documented in the gbapp chapter.
After startup, access the UI interface at `http://localhost:9000` to interact with your bots and monitor their operation.
After startup, access the UI interface at `http://localhost:8080` to interact with your bots and monitor their operation.
## Use Cases
@ -173,27 +173,6 @@ Example bots in the `templates/` directory demonstrate common patterns. Test sui
General Bots is open source under the AGPL (GNU Affero General Public License). The GitHub repository hosts all development activity. Issue tracking manages bug reports and feature requests. Pull requests from the community are welcome and encouraged.
## Codebase Statistics
The General Bots workspace contains the following lines of code by language:
| Language | Lines of Code |
|------------|---------------|
| HTML | 318,676 |
| Rust | 232,015 |
| Markdown | 135,130 |
| SVG | 47,196 |
| JSON | 45,743 |
| CSS | 40,476 |
| SQL | 26,242 |
| JavaScript | 16,257 |
| TOML | 5,640 |
| YAML | 4,762 |
| Shell | 3,602 |
| TypeScript | 13 |
| **Total** | **875,752** |
## Summary
botserver provides a complete platform for building conversational AI applications. The combination of simple BASIC scripting, automatic setup, and enterprise features bridges the gap between simple chatbots and complex AI systems. The focus on packages, minimal configuration, and multi-channel support makes botserver suitable for both rapid prototyping and production deployments serving millions of users.

18
src/01-getting-started/quick-start.md → src/01-introduction/quick-start.md
View file

@ -28,13 +28,13 @@ Installing Cache...
Creating bots from templates...
default.gbai deployed
announcements.gbai deployed
botserver ready at http://localhost:9000
botserver ready at http://localhost:8080
```
### 3. Open Browser
```
http://localhost:9000
http://localhost:8080
```
Start chatting with your bot!
@ -45,7 +45,7 @@ Start chatting with your bot!
### Bootstrap Flow
<img src="../assets/01-getting-started/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-01/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
The **automatic bootstrap** process:
@ -78,7 +78,7 @@ drive-secret,my-secret-key
### How Tools Work
<img src="../assets/01-getting-started/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-01/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
Tools are just `.bas` files. Create `enrollment.bas`:
@ -277,11 +277,11 @@ rm .env
## Documentation
- **[Full Installation Guide](docs/src/01-getting-started/installation.md)** - Detailed bootstrap explanation
- **[Tool Definition](docs/src/08-rest-api-tools/tool-definition.md)** - Creating tools
- **[BASIC Keywords](docs/src/07-user-interface/keywords.md)** - Language reference
- **[Package System](docs/src/02-architecture-packages/README.md)** - Creating bots
- **[Architecture](docs/src/04-basic-scripting/architecture.md)** - How it works
- **[Full Installation Guide](docs/src/chapter-01/installation.md)** - Detailed bootstrap explanation
- **[Tool Definition](docs/src/chapter-08/tool-definition.md)** - Creating tools
- **[BASIC Keywords](docs/src/chapter-05/keywords.md)** - Language reference
- **[Package System](docs/src/chapter-02/README.md)** - Creating bots
- **[Architecture](docs/src/chapter-06/architecture.md)** - How it works
---

10
src/01-getting-started/sessions.md → src/01-introduction/sessions.md
View file

@ -2,7 +2,7 @@
Every conversation has memory. Sessions are the beating heart of botserver because they remember who you are, what you have said, and where you left off. Even if you close your browser and come back tomorrow, your conversation continues right where it paused.
<img src="../assets/01-getting-started/session-manager.svg" alt="Session Manager" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-01/session-manager.svg" alt="Session Manager" style="max-height: 400px; width: 100%; object-fit: contain;">
## What Is a Session?
@ -14,7 +14,7 @@ A session is a persistent conversation container that tracks everything about an
### UI Interface
When a user opens `http://localhost:9000`, the browser receives a session token in the form of a UUID. This token is stored in localStorage for persistence across page loads. The session itself is created in PostgreSQL for durability and cached for fast access during active conversations.
When a user opens `http://localhost:8080`, the browser receives a session token in the form of a UUID. This token is stored in localStorage for persistence across page loads. The session itself is created in PostgreSQL for durability and cached for fast access during active conversations.
### API Access
@ -22,12 +22,12 @@ Programmatic access to sessions uses the REST API. A POST request to `/api/sessi
```bash
# Get new session
curl -X POST http://localhost:9000/api/session
curl -X POST http://localhost:8080/api/session
# Returns: {"session_id": "uuid-here", "token": "secret-token"}
# Use session
curl -H "Authorization: Bearer secret-token" \
http://localhost:9000/api/chat
http://localhost:8080/api/chat
```
### Anonymous vs Authenticated
@ -37,7 +37,7 @@ Sessions come in two flavors depending on user identity. Anonymous sessions are
## Session Lifecycle
<img src="../assets/01-getting-started/session-states.svg" alt="Session States" style="max-height: 300px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-01/session-states.svg" alt="Session States" style="max-height: 300px; width: 100%; object-fit: contain;">
Sessions move through several states during their existence. Active sessions have no timeout while the user is actively chatting. Idle sessions timeout after 30 minutes by default, though this is configurable. Expired sessions are removed after 7 days for anonymous users, while authenticated sessions never expire automatically.

931
src/02-architecture-packages/building.md
View file

@ -1,931 +0,0 @@
# Building from Source
This guide covers building botserver from source, including dependencies, feature flags, and platform-specific considerations.
## Quick Start
**For server deployment (no desktop GUI):**
```bash
cargo build --release --no-default-features
```
**For desktop application development (requires GTK libraries):**
```bash
sudo apt install -y libglib2.0-dev libgtk-3-dev libgdk-pixbuf-2.0-dev libcairo2-dev libpango1.0-dev libatk1.0-dev libxkbcommon-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev
cargo build --release
```
## Prerequisites
### System Requirements
- **Operating System**: Linux, macOS, or Windows
- **Rust**: 1.90 or later (2021 edition)
- **Memory**: 4GB RAM minimum (8GB recommended)
- **Disk Space**: 8GB for development environment
### Install Git
Git is required to clone the repository and manage submodules.
#### Linux
```bash
sudo apt install git
```
#### macOS
```bash
brew install git
```
#### Windows
Download and install from: https://git-scm.com/download/win
Or use winget:
```powershell
winget install Git.Git
```
### Install Rust
If you don't have Rust installed:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```
Verify installation:
```bash
rustc --version
cargo --version
```
### System Dependencies
#### Linux (Ubuntu/Debian)
**Base dependencies** (required for all builds):
```bash
sudo apt update
sudo apt install -y \
clang \
lld \
build-essential \
pkg-config \
libssl-dev \
libpq-dev \
cmake \
git
```
**Desktop GUI dependencies** (required for Tauri/desktop builds):
```bash
sudo apt install -y \
libglib2.0-dev \
libgtk-3-dev \
libwebkit2gtk-4.1-dev \
libjavascriptcoregtk-4.1-dev \
libayatana-appindicator3-dev \
librsvg2-dev \
libsoup-3.0-dev
```
**Note:** The webkit2gtk library must be version 4.1, not 4.0. Using the wrong version will cause build failures with error: `error: failed to run custom build command for webkit2gtk-sys v2.0.2`
**Note:** Desktop GUI dependencies are only needed if building with `--features desktop`. For minimal builds without desktop GUI, these libraries are not required.
Configure Rust to use clang as the linker:
```bash
mkdir -p ~/.cargo
cat >> ~/.cargo/config.toml << EOF
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]
EOF
```
#### Linux (Fedora/RHEL)
**Base dependencies** (required for all builds):
```bash
sudo dnf install -y \
clang \
lld \
gcc \
gcc-c++ \
make \
pkg-config \
openssl-devel \
postgresql-devel \
cmake \
git
```
**Desktop GUI dependencies** (required for Tauri/desktop builds):
```bash
sudo dnf install -y \
glib2-devel \
gobject-introspection-devel \
gtk3-devel \
webkit2gtk3-devel \
javascriptcore-gtk-devel \
libappindicator-gtk3-devel \
librsvg2-devel \
libsoup3-devel
```
**Note:** Desktop GUI dependencies are only needed if building with `--features desktop`. For minimal builds without desktop GUI, these libraries are not required.
Configure Rust to use clang as the linker:
```bash
mkdir -p ~/.cargo
cat >> ~/.cargo/config.toml << EOF
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]
EOF
```
#### macOS
```bash
brew install postgresql openssl cmake git
xcode-select --install
```
#### Windows
Install Visual Studio Build Tools with C++ support from:
https://visualstudio.microsoft.com/downloads/
Select "Desktop development with C++" workload during installation.
Then install PostgreSQL manually from:
https://www.postgresql.org/download/windows/
## Clone Repository
```bash
git clone --recursive https://github.com/GeneralBots/gb.git
cd gb
```
If you cloned without `--recursive`, initialize submodules:
```bash
git submodule update --init --recursive
```
## Build Cache with sccache
sccache caches compilation artifacts for faster rebuilds.
Install and configure:
```bash
cargo install sccache
mkdir -p ~/.cargo
echo '[build]
compiler = "sccache"' >> ~/.cargo/config.toml
export RUSTC_WRAPPER=sccache
```
Verify cache hits:
```bash
sccache --show-stats
```
Clear cache if needed:
```bash
sccache --zero-stats
```
## Build Configurations
### Minimal Build (Recommended for Server)
Build without desktop GUI dependencies:
```bash
cargo build --release --no-default-features
```
This excludes:
- Desktop GUI (Tauri) - No GTK libraries required
- Vector database (Qdrant)
- Email integration (IMAP)
**Use this for:** Server deployments, Docker containers, CI/CD, or when GTK libraries are not available.
### Standard Build (Requires Desktop GUI Dependencies)
Build with default features (includes desktop support):
```bash
cargo build --release
```
**Requires:** GTK development libraries (see "Desktop GUI dependencies" in prerequisites).
**Use this for:** Desktop application development or when you need native GUI features.
### Feature-Specific Builds
#### With Vector Database
Enable Qdrant vector database support:
```bash
cargo build --release --features vectordb
```
#### With Email Support
Enable IMAP email integration:
```bash
cargo build --release --features email
```
#### Desktop Application
Build as desktop app with Tauri (default):
```bash
cargo build --release --features desktop
```
#### All Features
Build with all optional features:
```bash
cargo build --release --all-features
```
## Feature Flags
botserver supports the following features defined in `Cargo.toml`:
```toml
[features]
default = ["desktop"]
vectordb = ["qdrant-client"]
email = ["imap"]
desktop = ["dep:tauri", "dep:tauri-plugin-dialog", "dep:tauri-plugin-opener"]
```
### Feature Details
| Feature | Dependencies | Purpose |
|---------|--------------|---------|
| `desktop` | tauri, tauri-plugin-dialog, tauri-plugin-opener | Native desktop application with system integration |
| `vectordb` | qdrant-client | Semantic search with Qdrant vector database |
| `email` | imap | IMAP email integration for reading emails |
## Build Profiles
### Debug Build
For development with debug symbols and no optimizations:
```bash
cargo build
```
Binary location: `target/debug/botserver`
### Release Build
Optimized for production with LTO and size optimization:
```bash
cargo build --release
```
Binary location: `target/release/botserver`
The release profile in `Cargo.toml` uses aggressive optimization:
```toml
[profile.release]
lto = true # Link-time optimization
opt-level = "z" # Optimize for size
strip = true # Strip symbols
panic = "abort" # Abort on panic (smaller binary)
codegen-units = 1 # Better optimization (slower build)
```
## Platform-Specific Builds
### Linux
Standard build works on most distributions:
```bash
cargo build --release
```
For static linking (portable binary):
```bash
RUSTFLAGS='-C target-feature=+crt-static' cargo build --release --target x86_64-unknown-linux-gnu
```
### macOS
Build for current architecture:
```bash
cargo build --release
```
Build universal binary (Intel + Apple Silicon):
```bash
rustup target add x86_64-apple-darwin aarch64-apple-darwin
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin
lipo -create \
target/x86_64-apple-darwin/release/botserver \
target/aarch64-apple-darwin/release/botserver \
-output botserver-universal
```
### Windows
Build with MSVC toolchain:
```bash
cargo build --release
```
Binary location: `target\release\botserver.exe`
## Cross-Compilation
### Install Cross-Compilation Tools
```bash
cargo install cross
```
### Build for Linux from macOS/Windows
```bash
cross build --release --target x86_64-unknown-linux-gnu
```
### Build for Windows from Linux/macOS
```bash
cross build --release --target x86_64-pc-windows-gnu
```
## Troubleshooting
### Linker Errors (Linux)
**Error: `linker 'clang' not found`**
This occurs when clang/lld is not installed:
```bash
sudo apt install clang lld
```
Then configure Rust to use clang:
```bash
mkdir -p ~/.cargo
cat >> ~/.cargo/config.toml << EOF
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]
EOF
```
### OpenSSL Errors
If you encounter OpenSSL linking errors:
**Linux:**
```bash
sudo apt install libssl-dev
```
**macOS:**
```bash
export OPENSSL_DIR=$(brew --prefix openssl)
cargo build --release
```
**Windows:**
```powershell
# Use vcpkg
vcpkg install openssl:x64-windows
$env:OPENSSL_DIR="C:\vcpkg\installed\x64-windows"
cargo build --release
```
### libsoup-3.0 Dependency Warning
**Warning:** `pkg-config exited with status code 1` when searching for `libsoup-3.0`
This occurs when the libsoup-3.0 development library is missing but is required by a transitive dependency for desktop features.
**Solution (Linux):**
```bash
sudo apt install libsoup-3.0-dev
```
**Solution (Fedora/RHEL):**
```bash
sudo dnf install libsoup3-devel
```
**Solution (macOS):**
```bash
brew install libsoup
export PKG_CONFIG_PATH=$(brew --prefix libsoup)/lib/pkgconfig:$PKG_CONFIG_PATH
```
**Note:** This library is only needed for desktop/Tauri builds with GTK dependencies. If building with `--no-default-features` for server-only deployments, this library is not required and the warning can be safely ignored.
### PostgreSQL Library Errors
If libpq is not found:
**Linux:**
```bash
sudo apt install libpq-dev
```
**macOS:**
```bash
brew install postgresql
export PQ_LIB_DIR=$(brew --prefix postgresql)/lib
```
**Windows:**
```powershell
# Ensure PostgreSQL is in PATH
$env:PQ_LIB_DIR="C:\Program Files\PostgreSQL\15\lib"
```
### Out of Memory During Build
Use sccache to cache compilations:
```bash
cargo install sccache
export RUSTC_WRAPPER=sccache
cargo build --release
```
Or reduce parallel jobs:
```bash
cargo build --release -j 2
```
Or limit memory per job:
```bash
CARGO_BUILD_JOBS=2 cargo build --release
```
### Linker Errors
Ensure you have a C/C++ compiler:
**Linux:**
```bash
sudo apt install build-essential
```
**macOS:**
```bash
xcode-select --install
```
**Windows:**
Install Visual Studio Build Tools with C++ support.
## Common Build Errors
### Error: `linker 'clang' not found`
**Cause:** The C/C++ toolchain is missing or not configured.
**Solution (Linux):**
1. Install clang and lld:
```bash
sudo apt update
sudo apt install -y clang lld build-essential
```
2. Configure Rust to use clang:
```bash
mkdir -p ~/.cargo
cat > ~/.cargo/config.toml << 'EOF'
[build]
rustflags = ["-C", "linker=clang", "-C", "link-arg=-fuse-ld=lld"]
[target.x86_64-unknown-linux-gnu]
linker = "clang"
EOF
```
3. Clean and rebuild:
```bash
cargo clean
cargo build --release
```
**Solution (macOS):**
```bash
xcode-select --install
```
**Solution (Windows):**
Install Visual Studio Build Tools with "Desktop development with C++" workload.
### Error: `could not find native library pq`
**Cause:** PostgreSQL development libraries are missing.
**Solution:**
**Linux:**
```bash
sudo apt install libpq-dev
```
**macOS:**
```bash
brew install postgresql
export PQ_LIB_DIR=$(brew --prefix postgresql)/lib
```
**Windows:** Install PostgreSQL from postgresql.org
### Error: `openssl-sys` build failures
**Cause:** OpenSSL headers are missing.
**Solution:**
**Linux:**
```bash
sudo apt install libssl-dev pkg-config
```
**macOS:**
```bash
brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)
export OPENSSL_LIB_DIR=$(brew --prefix openssl)/lib
export OPENSSL_INCLUDE_DIR=$(brew --prefix openssl)/include
```
### Error: Out of memory during build
**Cause:** Too many parallel compilation jobs.
**Solution:**
Reduce parallel jobs:
```bash
CARGO_BUILD_JOBS=2 cargo build --release
```
Or limit memory:
```bash
ulimit -v 4000000 # Limit to 4GB
cargo build --release
```
### Error: Submodule references not found
**Cause:** Submodules not initialized.
**Solution:**
```bash
git submodule update --init --recursive
```
Or re-clone with submodules:
```bash
git clone --recursive https://github.com/GeneralBots/gb.git
```
### Error: `#[derive(RustEmbed)] folder '$CARGO_MANIFEST_DIR/ui' does not exist`
**Cause:** The `rust-embed` crate cannot expand the `$CARGO_MANIFEST_DIR` variable without the `interpolate-folder-path` feature enabled.
**Solution:**
Ensure the workspace `Cargo.toml` has the feature enabled:
```toml
rust-embed = { version = "8.5", features = ["interpolate-folder-path"] }
```
This feature allows rust-embed to expand cargo environment variables like `$CARGO_MANIFEST_DIR` in the folder path attribute.
### Warning: `ignoring invalid dependency 'botserver' which is missing a lib target`
**Cause:** The `bottest` crate incorrectly specifies `botserver` as a dependency, but `botserver` is a binary-only crate with no library target.
**Solution:**
Remove the invalid dependency from `bottest/Cargo.toml`:
```toml
[dependencies]
# Note: botserver is a binary-only crate, tested by spawning the process
botlib = { path = "../botlib", features = ["database"] }
```
Integration tests should spawn the botserver binary as a separate process rather than linking against it as a library.
## Verify Build
After building, verify the binary works:
```bash
./target/release/botserver --version
```
Expected output: `botserver 6.2.0` or similar.
## Development Builds
### Watch Mode
Auto-rebuild on file changes:
```bash
cargo install cargo-watch
cargo watch -x 'build --release'
```
### Check Without Building
Fast syntax and type checking:
```bash
cargo check
```
With specific features:
```bash
cargo check --features vectordb,email
```
## Testing
### Run All Tests
```bash
cargo test
```
### Run Tests for Specific Module
```bash
cargo test --package botserver --lib bootstrap::tests
```
### Run Integration Tests
```bash
cargo test --test '*'
```
## Code Quality
### Format Code
```bash
cargo fmt
```
### Lint Code
```bash
cargo clippy -- -D warnings
```
### Check Dependencies
```bash
cargo tree
```
Find duplicate dependencies:
```bash
cargo tree --duplicates
```
### Security Audit
Run security audit to check for known vulnerabilities in dependencies:
```bash
cargo install cargo-audit
cargo audit
```
This should be run regularly during development to ensure dependencies are secure.
### Quick Build Check
Check if everything compiles without building:
```bash
cargo check --all-features
```
This is much faster than a full build and catches most errors.
## Build Artifacts
After a successful release build, you'll have:
- `target/release/botserver` - Main executable
- `target/release/build/` - Build script outputs
- `target/release/deps/` - Compiled dependencies
## Size Optimization
The release profile already optimizes for size. To further reduce:
### Strip Binary Manually
```bash
strip target/release/botserver
```
### Use UPX Compression
```bash
upx --best --lzma target/release/botserver
```
Note: UPX may cause issues with some systems. Test thoroughly.
## Clean Build
Remove all build artifacts:
```bash
cargo clean
```
## CI/CD Builds
For automated builds in CI/CD pipelines:
### GitHub Actions
```yaml
name: Build
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
submodules: recursive
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install Dependencies
run: |
sudo apt update
sudo apt install -y clang lld build-essential pkg-config libssl-dev libpq-dev cmake
- name: Cache sccache
uses: actions/cache@v3
with:
path: ~/.cache/sccache
key: ${{ runner.os }}-sccache-${{ hashFiles('**/Cargo.lock') }}
- name: Build
run: cargo build --release --all-features
```
### LXC Build
Build inside LXC container:
```bash
# Create build container
lxc-create -n botserver-build -t download -- -d ubuntu -r jammy -a amd64
# Configure container with build resources
cat >> /var/lib/lxc/botserver-build/config << EOF
lxc.cgroup2.memory.max = 4G
lxc.cgroup2.cpu.max = 400000 100000
EOF
# Start container
lxc-start -n botserver-build
# Install build dependencies
lxc-attach -n botserver-build -- bash -c "
apt-get update
apt-get install -y clang lld build-essential pkg-config libssl-dev libpq-dev cmake curl git
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source \$HOME/.cargo/env
"
# Build botserver
lxc-attach -n botserver-build -- bash -c "
git clone --recursive https://github.com/GeneralBots/gb.git /build
cd /build
source \$HOME/.cargo/env
cargo build --release --no-default-features
"
# Copy binary from container
lxc-attach -n botserver-build -- cat /build/target/release/botserver > /usr/local/bin/botserver
chmod +x /usr/local/bin/botserver
```
## Installation
After building, install system-wide:
```bash
sudo install -m 755 target/release/botserver /usr/local/bin/
```
Or create a symlink:
```bash
ln -s $(pwd)/target/release/botserver ~/.local/bin/botserver
```
Verify installation:
```bash
botserver --version
```
Expected output: `botserver 6.2.0` or similar.
## Quick Reference
| Command | Purpose |
|---------|---------|
| `cargo build --release` | Optimized production build |
| `cargo build --release -j 2` | Build with limited parallelism |
| `cargo check` | Fast syntax/type checking |
| `cargo test` | Run all tests |
| `cargo clippy` | Lint code |
| `cargo clean` | Remove build artifacts |
| `CARGO_BUILD_JOBS=2 cargo build` | Limit build jobs |
| `RUSTC_WRAPPER=sccache cargo build` | Use compilation cache |
## Next Steps
After building:
1. Run the bootstrap process to install dependencies
2. Configure `.env` file with database credentials
3. Start botserver and access web interface
4. Create your first bot from templates
See [Chapter 01: Run and Talk](../01-getting-started/README.md) for next steps.

1
src/02-architecture-packages/kubernetes-deployment.md
View file

@ -1 +0,0 @@
# Kubernetes Deployment

1
src/02-architecture-packages/monitoring-setup.md
View file

@ -1 +0,0 @@
# Monitoring Setup

351
src/02-architecture-packages/testing-safety.md
View file

@ -1,351 +0,0 @@
# Testing and Safety Tooling
This guide covers advanced testing and safety tools for General Bots development, including formal verification, undefined behavior detection, and memory safety analysis.
## Overview
General Bots prioritizes safety and correctness. While Rust's type system catches many errors at compile time, additional tooling can detect subtle bugs and verify critical code paths.
## Standard Testing
### Unit Tests
```bash
cargo test
```
Run tests for a specific package:
```bash
cargo test -p botserver
cargo test -p botlib
```
### Integration Tests
```bash
cargo test --test integration
```
## Miri - Undefined Behavior Detection
[Miri](https://github.com/rust-lang/miri) is an interpreter for Rust's mid-level intermediate representation (MIR) that detects undefined behavior.
### When to Use Miri
- Testing unsafe code blocks
- Detecting memory leaks in complex data structures
- Finding data races in concurrent code
- Validating pointer arithmetic
### Running Miri
```bash
# Install Miri
rustup +nightly component add miri
# Run tests under Miri
cargo +nightly miri test
# Run specific test
cargo +nightly miri test test_name
# Run with isolation disabled (for FFI)
cargo +nightly miri test -- -Zmiri-disable-isolation
```
### Miri Limitations
- **Slow execution** - 10-100x slower than native
- **No FFI** - Cannot call C libraries
- **No I/O** - Cannot perform actual I/O operations
- **Nightly only** - Requires nightly Rust
### Recommended Usage for General Bots
Miri is valuable for testing:
- `botlib` data structures and parsing logic
- BASIC interpreter core in `botserver`
- Custom serialization/deserialization code
Not suitable for:
- HTTP handlers (requires I/O)
- Database operations (requires FFI)
- Full integration tests
## Kani - Formal Verification
[Kani](https://github.com/model-checking/kani) is a model checker that mathematically proves code properties.
### When to Use Kani
- Verifying critical algorithms
- Proving absence of panics
- Checking invariants in state machines
- Validating security-critical code
### Running Kani
```bash
# Install Kani
cargo install --locked kani-verifier
kani setup
# Verify a function
cargo kani --function critical_function
# Verify with specific harness
cargo kani --harness verify_limits
```
### Writing Kani Proofs
```rust
#[cfg(kani)]
mod verification {
use super::*;
#[kani::proof]
fn verify_loop_limit_check() {
let iterations: u32 = kani::any();
let max: u32 = kani::any();
// Assume valid inputs
kani::assume(max > 0);
let result = check_loop_limit(iterations, max);
// Prove: if iterations < max, result is Ok
if iterations < max {
assert!(result.is_ok());
}
}
#[kani::proof]
fn verify_rate_limiter_never_panics() {
let count: u64 = kani::any();
let limit: u64 = kani::any();
kani::assume(limit > 0);
// This should never panic regardless of inputs
let _ = count.checked_div(limit);
}
}
```
### Kani Limitations
- **Bounded verification** - Cannot verify unbounded loops
- **Slow** - Model checking is computationally expensive
- **Limited async support** - Async code requires special handling
### Recommended Usage for General Bots
Kani is valuable for:
- Verifying `botlib::limits` enforcement
- Proving rate limiter correctness
- Validating authentication logic invariants
- Checking BASIC parser edge cases
## AddressSanitizer (ASan)
AddressSanitizer detects memory errors at runtime.
### Running with ASan
```bash
# Build and test with AddressSanitizer
RUSTFLAGS="-Z sanitizer=address" cargo +nightly test
# For a specific package
RUSTFLAGS="-Z sanitizer=address" cargo +nightly test -p botserver
```
### What ASan Detects
- Use-after-free
- Buffer overflows
- Stack buffer overflow
- Global buffer overflow
- Use after return
- Memory leaks
### ASan Configuration
```bash
# Set ASan options
export ASAN_OPTIONS="detect_leaks=1:abort_on_error=1:symbolize=1"
# Run tests
RUSTFLAGS="-Z sanitizer=address" cargo +nightly test
```
## ThreadSanitizer (TSan)
Detects data races in multi-threaded code.
```bash
RUSTFLAGS="-Z sanitizer=thread" cargo +nightly test
```
### TSan Considerations
- Requires `--target x86_64-unknown-linux-gnu`
- Incompatible with ASan (run separately)
- Higher memory overhead
## MemorySanitizer (MSan)
Detects uninitialized memory reads.
```bash
RUSTFLAGS="-Z sanitizer=memory" cargo +nightly test
```
### MSan Requirements
- Must compile all dependencies with MSan
- Most practical for pure Rust code
- Requires nightly toolchain
## Ferrocene - Safety-Critical Rust
[Ferrocene](https://ferrocene.dev/) is a qualified Rust compiler for safety-critical systems.
### When to Consider Ferrocene
Ferrocene is relevant if General Bots is deployed in:
- Medical devices
- Automotive systems
- Aerospace applications
- Industrial control systems
- Any context requiring ISO 26262, IEC 61508, or DO-178C compliance
### Ferrocene vs Standard Rust
| Aspect | Standard Rust | Ferrocene |
|--------|---------------|-----------|
| **Qualification** | None | ISO 26262, IEC 61508 |
| **Documentation** | Community | Formal qualification docs |
| **Support** | Community | Commercial support |
| **Cost** | Free | Commercial license |
| **Traceability** | Limited | Full requirement traceability |
### Should General Bots Use Ferrocene?
**For typical SaaS deployment: No**
Ferrocene is overkill for:
- Web applications
- Business automation
- General chatbot deployments
**Consider Ferrocene if:**
- Deploying GB in safety-critical environments
- Customer requires formal certification
- Regulatory compliance mandates qualified tooling
### Alternative: Standard Rust + Testing
For most deployments, comprehensive testing provides sufficient confidence:
```bash
# Full test suite
cargo test --all
# With coverage
cargo tarpaulin --out Html
# Fuzzing critical parsers
cargo fuzz run parse_basic_script
```
## Recommended Testing Strategy
### Development (Every Commit)
```bash
cargo test
cargo clippy -- -D warnings
```
### Pre-Release
```bash
# Full test suite
cargo test --all
# Miri for unsafe code
cargo +nightly miri test -p botlib
# AddressSanitizer
RUSTFLAGS="-Z sanitizer=address" cargo +nightly test
# ThreadSanitizer (for concurrent code)
RUSTFLAGS="-Z sanitizer=thread" cargo +nightly test
```
### Critical Code Changes
```bash
# Kani for formal verification
cargo kani --function critical_function
# Extended fuzzing
cargo fuzz run target_name -- -max_total_time=3600
```
## CI/CD Integration
Example GitHub Actions workflow:
```yaml
name: Safety Tests
on:
push:
branches: [main]
pull_request:
jobs:
miri:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@nightly
with:
components: miri
- run: cargo miri test -p botlib
sanitizers:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@nightly
- run: RUSTFLAGS="-Z sanitizer=address" cargo test
kani:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: model-checking/kani-github-action@v1
- run: cargo kani --tests
```
## Summary
| Tool | Purpose | When to Use |
|------|---------|-------------|
| `cargo test` | Unit/integration tests | Always |
| `miri` | Undefined behavior | Unsafe code changes |
| `kani` | Formal verification | Critical algorithms |
| `ASan` | Memory errors | Pre-release, CI |
| `TSan` | Data races | Concurrent code changes |
| `Ferrocene` | Safety certification | Regulated industries only |
## See Also
- [System Limits](../09-security/system-limits.md) - Rate limiting and resource constraints
- [Security Features](../09-security/security-features.md) - Security architecture
- [Building from Source](./building.md) - Compilation guide

78
src/02-templates/README.md Normal file
View file

@ -0,0 +1,78 @@
# Chapter 02: About Packages
How bots are organized in General Bots.
## What You'll Learn
- Package structure (`.gbai` folders)
- Dialog scripts in BASIC
- Knowledge bases
- Configuration basics
- How packages load
## Package Structure
A bot is just a folder ending in `.gbai`:
```
my-bot.gbai/
├── my-bot.gbdialog/ # BASIC scripts
├── my-bot.gbkb/ # Documents
├── my-bot.gbot/ # Configuration
├── my-bot.gbtheme/ # Optional styling
└── my-bot.gbdrive/ # Optional storage
```
Drop the folder in `templates/`, it loads automatically.
## Key Concepts
### Dialogs (.gbdialog)
- BASIC scripts that control conversation
- `start.bas` is optional (but needed to activate tools/KB with USE TOOL/USE KB)
- Simple commands like TALK and HEAR
### Knowledge Base (.gbkb)
- Put PDFs and documents in folders
- Automatically becomes searchable
- Bot can answer questions from documents
### Configuration (.gbot)
- Single `config.csv` file
- Simple name,value pairs
- Missing values use defaults
### Themes (.gbtheme)
- Optional CSS styling
- Most bots don't need this
### Storage (.gbdrive)
- Links to S3-compatible storage
- For large files and uploads
## How It Works
1. **Discovery**: Finds `.gbai` folders
2. **Loading**: Reads all components
3. **Indexing**: Processes documents
4. **Activation**: Bot is ready
No build process. No compilation. Just folders and files.
The web UI uses **HTMX with server-side rendering** - minimal JavaScript, no build process, just HTML templates powered by Rust.
## Topics Covered
- [.gbai Architecture](./gbai.md) - Package details
- [.gbdialog Dialogs](./gbdialog.md) - BASIC scripting
- [.gbkb Knowledge Base](./gbkb.md) - Document management
- [.gbot Configuration](./gbot.md) - Settings
- [.gbtheme UI Theming](./gbtheme.md) - Styling
- [.gbdrive File Storage](./gbdrive.md) - Storage integration
- [Bot Templates](./templates.md) - Example bots
---
<div align="center">
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
</div>

0
src/02-architecture-packages/assets/package-structure.svg.backup → src/02-templates/assets/package-structure.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
src/02-architecture-packages/assets/template-deployment-flow.svg.backup → src/02-templates/assets/template-deployment-flow.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

6
src/02-architecture-packages/gbai.md → src/02-templates/gbai.md
View file

@ -17,7 +17,7 @@ That's it. No manifests, no build files, no dependencies. Copy the folder to dep
### Visual Architecture
### Architecture
<img src="../assets/02-architecture-packages/package-structure.svg" alt="Package Structure" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-02/package-structure.svg" alt="Package Structure" style="max-height: 400px; width: 100%; object-fit: contain;">
## How Bootstrap Finds Bots
@ -158,7 +158,7 @@ greeting,Welcome to support!
```bash
cp -r my-bot.gbai/ templates/
./botserver restart
# Visit http://localhost:9000/my-bot
# Visit http://localhost:8080/my-bot
```
### Production Server
@ -211,7 +211,7 @@ Each bot:
When botserver starts:
<img src="../assets/02-architecture-packages/template-deployment-flow.svg" alt="Template Deployment Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-02/template-deployment-flow.svg" alt="Template Deployment Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
Takes about 5-10 seconds per bot.

55
src/02-architecture-packages/gbdialog.md → src/02-templates/gbdialog.md
View file

@ -1,27 +1,6 @@
# .gbdialog Dialogs
The [`.gbdialog`](../02-architecture-packages/gbdialog.md) package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.
## ⚠️ System Limits & Safety
All `.gbdialog` scripts run in a **sandboxed environment** with enforced limits to prevent abuse:
| Limit | Value | Description |
|-------|-------|-------------|
| **Loop Iterations** | 100,000 | Maximum iterations per loop (WHILE/FOR) |
| **Script Timeout** | 300 seconds | Maximum execution time |
| **String Length** | 10 MB | Maximum string size |
| **Array Length** | 1,000,000 | Maximum array elements |
| **File Size** | 100 MB | Maximum file size for GET/SAVE |
| **API Calls** | 1,000/minute | Rate limit per user |
**Important:**
- Loops automatically terminate if they exceed the iteration limit
- Scripts that run too long are forcefully stopped
- Excessive API calls return HTTP 429 (Too Many Requests)
- File operations are restricted to the bot's `.gbdrive` scope
See [System Limits](../09-security/system-limits.md) for complete documentation.
The [`.gbdialog`](../chapter-02/gbdialog.md) package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.
## What is .gbdialog?
@ -79,7 +58,7 @@ TALK "Registration complete!"
```
### 3. Knowledge Base Usage
See [Knowledge Base documentation](../03-knowledge-ai/knowledge-base.md) for details.
See [Knowledge Base documentation](../chapter-03/knowledge-base.md) for details.
```basic
' Activate knowledge base collections
USE KB "products"
@ -95,7 +74,7 @@ TALK "What product information can I help you with?"
## Script Structure
### Entry Point: start.bas (Optional)
The `start.bas` file in the [`.gbdialog`](../02-architecture-packages/gbdialog.md) folder is **optional**, but required if you want to activate tools or knowledge bases:
The `start.bas` file in the [`.gbdialog`](../chapter-02/gbdialog.md) folder is **optional**, but required if you want to activate tools or knowledge bases:
```basic
' Optional start script - needed only to activate tools/KB
@ -116,7 +95,7 @@ TALK "Welcome! How can I assist you today?"
- For basic Q&A without document search
### Tool Definitions
Create separate `.bas` files for each tool. See [KB and Tools](../03-knowledge-ai/kb-and-tools.md) for more information:
Create separate `.bas` files for each tool. See [KB and Tools](../chapter-03/kb-and-tools.md) for more information:
```basic
' enrollment.bas - The LLM knows when to use this
@ -218,7 +197,7 @@ TALK "What would you like to know about our products?"
## Advanced Features
### Memory Management
See [Storage documentation](../08-rest-api-tools.md) for persistent data options.
See [Storage documentation](../chapter-09/storage.md) for persistent data options.
```basic
SET BOT MEMORY "company_policy", policy_text
' Available across all sessions
@ -227,7 +206,7 @@ retrieved = GET BOT MEMORY "company_policy"
```
### External APIs
See [External APIs chapter](../08-rest-api-tools/external-apis.md) for integration patterns.
See [External APIs chapter](../chapter-08/external-apis.md) for integration patterns.
```basic
result = GET "https://api.example.com/data"
' For background processing only
@ -236,7 +215,7 @@ SET BOT MEMORY "api_summary", summary
```
### Suggestions
See [UI Interface](../07-user-interface/ui-interface.md) for UI integration.
See [UI Interface](../chapter-04/ui-interface.md) for UI integration.
```basic
ADD SUGGESTION "Schedule Meeting" AS "schedule"
ADD SUGGESTION "View Products" AS "products"
@ -250,9 +229,6 @@ The system handles errors gracefully:
- Runtime errors logged but don't crash
- LLM provides fallback responses
- Timeouts prevent infinite operations
- **Loop limit exceeded**: Script terminates with "Maximum iterations exceeded" error
- **Rate limit exceeded**: Returns HTTP 429 with `retry_after_secs` value
- **File too large**: Operation fails with "Limit exceeded for file_size" error
## Script Execution
@ -262,9 +238,6 @@ Scripts run in a sandboxed environment with:
- Knowledge base search
- Tool execution rights
- External API access (configured)
- **Enforced resource limits** (see System Limits above)
- **No direct filesystem access** - only `.gbdrive` via keywords
- **Rate limiting** - excessive requests return 429
## Migration from Traditional Bots
@ -291,13 +264,13 @@ The key is to **trust the system AI** and write less code for more intelligent b
## Important Distinction
- **[LLM Command](../03-knowledge-ai/ai-llm.md)**: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
- **[Interactive Conversations](../03-knowledge-ai/conversation.md)**: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow
- **[LLM Command](../chapter-09/ai-llm.md)**: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
- **[Interactive Conversations](../chapter-09/conversation.md)**: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow
## See Also
- [Chapter 1: Quick Start](../01-getting-started/quick-start.md) - Getting started with your first bot
- [Chapter 2: Bot Architecture](../02-architecture-packages/README.md) - Understanding all components
- [Chapter 3: Knowledge Base](../03-knowledge-ai/knowledge-base.md) - Working with KB collections
- [Chapter 5: Keywords Reference](../07-user-interface/README.md) - Complete BASIC command reference
- [Chapter 9: Conversation Flow](../03-knowledge-ai/conversation.md) - Advanced dialog patterns
- [Chapter 1: Quick Start](../chapter-01/quick-start.md) - Getting started with your first bot
- [Chapter 2: Bot Architecture](../chapter-02/README.md) - Understanding all components
- [Chapter 3: Knowledge Base](../chapter-03/knowledge-base.md) - Working with KB collections
- [Chapter 5: Keywords Reference](../chapter-05/README.md) - Complete BASIC command reference
- [Chapter 9: Conversation Flow](../chapter-09/conversation.md) - Advanced dialog patterns

0
src/02-architecture-packages/gbdrive.md → src/02-templates/gbdrive.md
View file

6
src/02-architecture-packages/gbkb.md → src/02-templates/gbkb.md
View file

@ -62,6 +62,6 @@ CLEAR KB "policies"
## Learn More
- [Chapter 03: Knowledge Base System](../03-knowledge-ai/README.md) - Technical deep-dive on indexing, vectors, and search
- [USE KB Keyword](../04-basic-scripting/keyword-use-kb.md) - Complete keyword reference
- [CLEAR KB Keyword](../04-basic-scripting/keyword-clear-kb.md) - Managing active collections
- [Chapter 03: Knowledge Base System](../chapter-03/README.md) - Technical deep-dive on indexing, vectors, and search
- [USE KB Keyword](../chapter-06-gbdialog/keyword-use-kb.md) - Complete keyword reference
- [CLEAR KB Keyword](../chapter-06-gbdialog/keyword-clear-kb.md) - Managing active collections

0
src/02-architecture-packages/gbot.md → src/02-templates/gbot.md
View file

0
src/02-architecture-packages/gbtheme.md → src/02-templates/gbtheme.md
View file

0
src/02-architecture-packages/summary.md → src/02-templates/summary.md
View file

2
src/02-architecture-packages/template-analytics.md → src/02-templates/template-analytics.md
View file

@ -428,4 +428,4 @@ POST "https://bi-tool.example.com/webhook", data
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-api-client.md → src/02-templates/template-api-client.md
View file

@ -463,4 +463,4 @@ api_key = GET ENV "MY_API_KEY"
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

8
src/02-architecture-packages/template-attendance-crm.md → src/02-templates/template-attendance-crm.md
View file

@ -107,7 +107,7 @@ Attendants can be identified by **any channel**: WhatsApp phone, email, Microsof
```csv
id,name,channel,preferences,department,aliases,phone,email,teams,google
att-001,João Silva,all,sales,commercial,joao;js;silva,+5511999990001,joao.silva@company.com,joao.silva@company.onmicrosoft.com,joao.silva@company.com
att-002,Maria Santos,whatsapp,support,customer-service,maria;ms,+5511999990002,santos@company.com,santos@company.onmicrosoft.com,santos@gmail.com
att-002,Maria Santos,whatsapp,support,customer-service,maria;ms,+5511999990002,maria.santos@company.com,maria.santos@company.onmicrosoft.com,maria.santos@gmail.com
att-003,Pedro Costa,web,technical,engineering,pedro;pc;tech,+5511999990003,pedro.costa@company.com,pedro.costa@company.onmicrosoft.com,pedro.costa@company.com
att-004,Ana Oliveira,all,collections,finance,ana;ao;cobranca,+5511999990004,ana.oliveira@company.com,ana.oliveira@company.onmicrosoft.com,ana.oliveira@company.com
att-005,Carlos Souza,whatsapp,sales,commercial,carlos;cs,+5511999990005,carlos.souza@company.com,carlos.souza@company.onmicrosoft.com,carlos.souza@gmail.com
@ -408,7 +408,7 @@ Set up alerts for:
## See Also
- [Transfer to Human](../03-knowledge-ai/transfer-to-human.md) - Handoff details
- [LLM-Assisted Attendant](../03-knowledge-ai/attendant-llm-assist.md) - AI copilot features
- [Transfer to Human](../chapter-11-features/transfer-to-human.md) - Handoff details
- [LLM-Assisted Attendant](../chapter-11-features/attendant-llm-assist.md) - AI copilot features
- [Sales CRM Template](./template-crm.md) - Full CRM without attendance
- [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Queue configuration
- [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Queue configuration

2
src/02-architecture-packages/template-bi.md → src/02-templates/template-bi.md
View file

@ -269,4 +269,4 @@ SEND FILE img, "Low Stock Alert"
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-crawler.md → src/02-templates/template-crawler.md
View file

@ -327,4 +327,4 @@ END IF
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbkb Reference](../03-knowledge-ai/README.md) - Knowledge base guide
- [gbkb Reference](../chapter-03/README.md) - Knowledge base guide

8
src/02-architecture-packages/template-crm-contacts.md → src/02-templates/template-crm-contacts.md
View file

@ -62,7 +62,7 @@ Add these settings to your `config.csv`:
</div>
<div class="wa-message user">
<div class="wa-bubble">
<p>santos@company.com</p>
<p>maria.santos@company.com</p>
<div class="wa-time">10:33</div>
</div>
</div>
@ -97,7 +97,7 @@ Add these settings to your `config.csv`:
<p>📋 <strong>Contact Details</strong></p>
<p>━━━━━━━━━━━━━━━━━</p>
<p>👤 <strong>Name:</strong> Maria Santos</p>
<p>📧 <strong>Email:</strong> santos@company.com</p>
<p>📧 <strong>Email:</strong> maria.santos@company.com</p>
<p>📱 <strong>Phone:</strong> +55 11 98765-4321</p>
<p>🏢 <strong>Company:</strong> Tech Solutions Ltd</p>
<p>🏷️ <strong>Tags:</strong> lead</p>
@ -139,7 +139,7 @@ Add these settings to your `config.csv`:
<div class="wa-bubble">
<p>🔍 Found 3 contacts at "Tech Solutions":</p>
<p></p>
<p>1. <strong>Maria Santos</strong> - santos@company.com</p>
<p>1. <strong>Maria Santos</strong> - maria.santos@company.com</p>
<p> 📱 +55 11 98765-4321 | 🏷️ lead</p>
<p></p>
<p>2. <strong>João Silva</strong> - joao.silva@techsolutions.com</p>
@ -300,4 +300,4 @@ Use the `POST` and `GET` keywords to sync contacts with Salesforce, HubSpot, or
.wa-bubble p{margin:0 0 4px 0;line-height:1.4;color:#303030}
.wa-bubble p:last-child{margin-bottom:0}
.wa-time{font-size:11px;color:#8696a0;text-align:right;margin-top:4px}
</style>
</style>

2
src/02-architecture-packages/template-crm.md → src/02-templates/template-crm.md
View file

@ -478,4 +478,4 @@ END IF
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

7
src/02-architecture-packages/template-embedded.md → src/02-templates/template-embedded.md
View file

@ -97,10 +97,7 @@ SUB handleCommand(command)
TALK "Current temperature is " + currentTemp + " degrees. Target is " + targetTemp + ". Heating is " + heating
CASE "schedule"
scheduleTime = intent.time
scheduleTemp = intent.temperature
SET SCHEDULER "thermostat_schedule", scheduleTime, "setTemperature", scheduleTemp
TALK "Scheduled temperature change to " + scheduleTemp + " degrees at " + scheduleTime
TALK "Scheduling not yet implemented"
END SELECT
END SUB
```
@ -674,7 +671,7 @@ idleTimeout = 60 ' Return to welcome screen after inactivity
lastActivity = NOW
' Initialize display
' (Runs in browser kiosk mode at http://localhost:9000/embedded/)
' (Runs in browser kiosk mode at http://localhost:8088/embedded/)
TALK welcomeMessage

2
src/02-architecture-packages/template-law.md → src/02-templates/template-law.md
View file

@ -349,4 +349,4 @@ This template provides AI-assisted document analysis tools. It does not constitu
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbkb Reference](../03-knowledge-ai/README.md) - Knowledge base guide
- [gbkb Reference](../chapter-03/README.md) - Knowledge base guide

2
src/02-architecture-packages/template-llm-server.md → src/02-templates/template-llm-server.md
View file

@ -420,4 +420,4 @@ CMD ["npm", "start"]
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-llm-tools.md → src/02-templates/template-llm-tools.md
View file

@ -447,4 +447,4 @@ Test various phrasings to ensure tool invocation:
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-marketing.md → src/02-templates/template-marketing.md
View file

@ -443,4 +443,4 @@ TALK "Post scheduled for " + schedule_time + " on " + platform
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-office.md → src/02-templates/template-office.md
View file

@ -391,4 +391,4 @@ END IF
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/template-reminder.md → src/02-templates/template-reminder.md
View file

@ -414,4 +414,4 @@ The LLM understands various date formats:
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

6
src/02-architecture-packages/template-samples.md → src/02-templates/template-samples.md
View file

@ -695,6 +695,6 @@ If these templates don't fit your needs:
## See Also
- [Templates Reference](./templates.md) - Full template list
- [How To: Create Your First Bot](../07-user-interface/how-to/create-first-bot.md)
- [Sources App](../07-user-interface/apps/sources.md) - Managing templates
- [Write Your First Dialog](../07-user-interface/how-to/write-first-dialog.md)
- [How To: Create Your First Bot](../chapter-04-gbui/how-to/create-first-bot.md)
- [Sources App](../chapter-04-gbui/apps/sources.md) - Managing templates
- [Write Your First Dialog](../chapter-04-gbui/how-to/write-first-dialog.md)

6
src/02-architecture-packages/template-template.md → src/02-templates/template-template.md
View file

@ -330,8 +330,8 @@ Bot: To add a tool, create a .bas file in your .gbdialog folder:
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [Bot Configuration](../10-configuration-deployment/README.md) - Configuration options
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
- [Bot Configuration](../chapter-08-config/README.md) - Configuration options
---
@ -349,4 +349,4 @@ Bot: To add a tool, create a .bas file in your .gbdialog folder:
- [Templates Reference](./templates.md) - Full template list
- [Template Samples](./template-samples.md) - Example conversations
- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide

2
src/02-architecture-packages/templates.md → src/02-templates/templates.md
View file

@ -122,7 +122,7 @@ Select based on your needs:
```bash
# Templates are auto-deployed during bootstrap
# Access at: http://localhost:9000/template-name
# Access at: http://localhost:8080/template-name
```
### 3. Customize Configuration

668
src/03-knowledge-ai/channel-setup.md
View file

@ -1,668 +0,0 @@
# Channel Setup Guide
This guide provides step-by-step instructions for connecting General Bots to various messaging platforms and social media channels.
## Overview
General Bots supports multiple communication channels:
| Category | Channels |
|----------|----------|
| Social Media | Instagram, Facebook, Twitter/X, LinkedIn, Bluesky, Threads, TikTok, YouTube, Pinterest, Reddit, Snapchat |
| Messaging | WhatsApp, Telegram, Discord, Microsoft Teams, WeChat, Twilio SMS |
| Email | Gmail, Outlook, Custom SMTP |
## Configuration Methods
Channels can be configured through:
1. **Settings UI** - Navigate to Settings → Accounts
2. **config.csv** - Add credentials to your bot's configuration
3. **Environment Variables** - Set system-wide defaults
4. **API** - Programmatic configuration
## Social Media Channels
### Instagram
**Requirements:**
- Instagram Business or Creator account
- Facebook Page connected to Instagram
- Facebook Developer App
**Setup Steps:**
1. Create a Facebook Developer App at developers.facebook.com
2. Add Instagram Graph API product
3. Connect your Instagram Business account
4. Generate long-lived access token
**Configuration:**
```csv
key,value
instagram-access-token,your-long-lived-token
instagram-account-id,your-instagram-account-id
instagram-page-id,your-facebook-page-id
```
**Permissions Required:**
- `instagram_basic`
- `instagram_content_publish`
- `instagram_manage_comments`
- `instagram_manage_insights`
**Rate Limits:**
- 25 posts per 24 hours
- 200 API calls per hour
---
### Facebook
**Requirements:**
- Facebook Page
- Facebook Developer App
**Setup Steps:**
1. Create a Facebook Developer App
2. Add Facebook Login and Pages API products
3. Generate Page Access Token
4. Request page_publish permissions
**Configuration:**
```csv
key,value
facebook-access-token,your-page-access-token
facebook-page-id,your-page-id
facebook-app-id,your-app-id
facebook-app-secret,your-app-secret
```
**Permissions Required:**
- `pages_manage_posts`
- `pages_read_engagement`
- `pages_show_list`
---
### Twitter / X
**Requirements:**
- Twitter Developer Account
- Elevated or Basic API access
**Setup Steps:**
1. Apply for Twitter Developer Account at developer.twitter.com
2. Create a Project and App
3. Generate API keys and access tokens
4. Enable OAuth 1.0a with read and write permissions
**Configuration:**
```csv
key,value
twitter-api-key,your-api-key
twitter-api-secret,your-api-secret
twitter-access-token,your-access-token
twitter-access-secret,your-access-token-secret
twitter-bearer-token,your-bearer-token
```
**Rate Limits:**
- Free tier: 1,500 tweets/month
- Basic tier: 3,000 tweets/month
- Pro tier: 300,000 tweets/month
---
### LinkedIn
**Requirements:**
- LinkedIn Page
- LinkedIn Marketing Developer Platform access
**Setup Steps:**
1. Create app at linkedin.com/developers
2. Request Marketing Developer Platform access
3. Add products: Share on LinkedIn, Marketing Developer Platform
4. Generate OAuth 2.0 access token
**Configuration:**
```csv
key,value
linkedin-client-id,your-client-id
linkedin-client-secret,your-client-secret
linkedin-access-token,your-access-token
linkedin-organization-id,your-organization-urn
```
**Permissions Required:**
- `w_organization_social`
- `r_organization_social`
- `rw_organization_admin`
---
### Bluesky
**Requirements:**
- Bluesky account
- App password (not your main password)
**Setup Steps:**
1. Log into Bluesky
2. Go to Settings → App Passwords
3. Create new app password
4. Note your handle (e.g., yourname.bsky.social)
**Configuration:**
```csv
key,value
bluesky-handle,yourname.bsky.social
bluesky-app-password,xxxx-xxxx-xxxx-xxxx
```
**Rate Limits:**
- 1,666 posts per day
- 5,000 API calls per hour
---
### Threads
**Requirements:**
- Threads account (linked to Instagram)
- Meta Developer App with Threads API access
**Setup Steps:**
1. Use your existing Meta Developer App
2. Add Threads API product
3. Generate Threads access token
4. Link your Threads account
**Configuration:**
```csv
key,value
threads-access-token,your-threads-token
threads-user-id,your-threads-user-id
```
**Rate Limits:**
- 250 posts per 24 hours
---
### TikTok
**Requirements:**
- TikTok Business Account
- TikTok Developer App
**Setup Steps:**
1. Register at developers.tiktok.com
2. Create an app
3. Apply for Content Posting API access
4. Complete OAuth flow to get access token
**Configuration:**
```csv
key,value
tiktok-client-key,your-client-key
tiktok-client-secret,your-client-secret
tiktok-access-token,your-access-token
tiktok-refresh-token,your-refresh-token
```
**Permissions Required:**
- `video.upload`
- `video.publish`
**Notes:**
- Videos must be uploaded before publishing
- Supports direct upload or URL pull
---
### YouTube
**Requirements:**
- YouTube Channel
- Google Cloud Project
**Setup Steps:**
1. Create project at console.cloud.google.com
2. Enable YouTube Data API v3
3. Create OAuth 2.0 credentials
4. Complete OAuth consent screen setup
5. Generate refresh token
**Configuration:**
```csv
key,value
youtube-client-id,your-client-id
youtube-client-secret,your-client-secret
youtube-refresh-token,your-refresh-token
youtube-channel-id,your-channel-id
```
**Permissions Required:**
- `youtube.upload`
- `youtube.force-ssl`
**Quota:**
- 10,000 units per day (default)
- Video upload: 1,600 units
---
### Pinterest
**Requirements:**
- Pinterest Business Account
- Pinterest Developer App
**Setup Steps:**
1. Apply at developers.pinterest.com
2. Create an app
3. Request access to Pins API
4. Generate access token
**Configuration:**
```csv
key,value
pinterest-app-id,your-app-id
pinterest-app-secret,your-app-secret
pinterest-access-token,your-access-token
```
**Rate Limits:**
- 1,000 API calls per minute
- 200 Pins per hour
---
### Reddit
**Requirements:**
- Reddit Account
- Reddit Developer App
**Setup Steps:**
1. Go to reddit.com/prefs/apps
2. Create script or web application
3. Note client ID (under app name) and secret
**Configuration:**
```csv
key,value
reddit-client-id,your-client-id
reddit-client-secret,your-client-secret
reddit-username,your-username
reddit-password,your-password
reddit-user-agent,GeneralBots/1.0
```
**Rate Limits:**
- 60 requests per minute
- 10 posts per subreddit per day
---
### Snapchat
**Requirements:**
- Snapchat Business Account
- Snap Marketing API access
**Setup Steps:**
1. Create account at business.snapchat.com
2. Apply for Marketing API access
3. Create OAuth app
4. Generate access token
**Configuration:**
```csv
key,value
snapchat-client-id,your-client-id
snapchat-client-secret,your-client-secret
snapchat-access-token,your-access-token
snapchat-refresh-token,your-refresh-token
snapchat-ad-account-id,your-ad-account-id
```
---
## Messaging Channels
### WhatsApp Business
**Requirements:**
- WhatsApp Business Account
- Meta Business verification
**Setup Steps:**
1. Set up Meta Business Suite
2. Add WhatsApp to your Meta Developer App
3. Configure webhook URL
4. Get phone number ID and access token
**Configuration:**
```csv
key,value
whatsapp-phone-number-id,your-phone-number-id
whatsapp-access-token,your-access-token
whatsapp-business-account-id,your-business-account-id
whatsapp-webhook-verify-token,your-verify-token
```
**Webhook URL:** `https://your-domain.com/api/channels/whatsapp/webhook`
---
### Telegram
**Requirements:**
- Telegram Bot (created via BotFather)
**Setup Steps:**
1. Message @BotFather on Telegram
2. Send `/newbot` and follow prompts
3. Copy the bot token
4. Set webhook URL
**Configuration:**
```csv
key,value
telegram-bot-token,your-bot-token
telegram-webhook-secret,your-webhook-secret
```
**Set Webhook:**
```bash
curl -X POST "https://api.telegram.org/bot<token>/setWebhook" \
-d "url=https://your-domain.com/api/channels/telegram/webhook"
```
---
### Discord
**Requirements:**
- Discord Server (with admin permissions)
- Discord Developer Application
**Setup Steps:**
1. Create app at discord.com/developers/applications
2. Create a Bot
3. Copy bot token
4. Generate invite URL with required permissions
5. Add bot to your server
**Configuration:**
```csv
key,value
discord-bot-token,your-bot-token
discord-application-id,your-application-id
discord-guild-id,your-server-id
discord-channel-id,default-channel-id
```
**Required Bot Permissions:**
- Send Messages
- Embed Links
- Attach Files
- Read Message History
---
### Microsoft Teams
**Requirements:**
- Microsoft 365 account
- Azure Active Directory app registration
**Setup Steps:**
1. Register app in Azure Portal
2. Add Teams permissions
3. Create Teams app manifest
4. Upload to Teams Admin Center
**Configuration:**
```csv
key,value
teams-app-id,your-app-id
teams-app-password,your-app-password
teams-tenant-id,your-tenant-id
```
---
### WeChat
**Requirements:**
- WeChat Official Account (Service or Subscription)
- ICP license (for China operations)
**Setup Steps:**
1. Register at mp.weixin.qq.com
2. Complete verification
3. Configure server settings
4. Get AppID and AppSecret
**Configuration:**
```csv
key,value
wechat-app-id,your-app-id
wechat-app-secret,your-app-secret
wechat-token,your-verification-token
wechat-encoding-aes-key,your-encoding-key
```
---
### Twilio SMS
**Requirements:**
- Twilio Account
- Phone number with SMS capability
**Setup Steps:**
1. Create account at twilio.com
2. Get Account SID and Auth Token
3. Purchase or port a phone number
4. Configure webhook URL
**Configuration:**
```csv
key,value
twilio-account-sid,your-account-sid
twilio-auth-token,your-auth-token
twilio-phone-number,+1234567890
twilio-messaging-service-sid,optional-messaging-service
```
**Webhook URL:** `https://your-domain.com/api/channels/twilio/webhook`
---
## Email Channels
### Gmail / Google Workspace
**Setup Steps:**
1. Enable Gmail API in Google Cloud Console
2. Create OAuth 2.0 credentials
3. Complete consent screen
4. Generate refresh token
**Configuration:**
```csv
key,value
gmail-client-id,your-client-id
gmail-client-secret,your-client-secret
gmail-refresh-token,your-refresh-token
gmail-user-email,your-email@gmail.com
```
---
### Outlook / Office 365
**Setup Steps:**
1. Register app in Azure Portal
2. Add Mail.Send permission
3. Grant admin consent
4. Generate access token
**Configuration:**
```csv
key,value
outlook-client-id,your-client-id
outlook-client-secret,your-client-secret
outlook-tenant-id,your-tenant-id
outlook-user-email,your-email@company.com
```
---
### Custom SMTP
**Configuration:**
```csv
key,value
smtp-host,smtp.example.com
smtp-port,587
smtp-username,your-username
smtp-password,your-password
smtp-from-address,noreply@example.com
smtp-from-name,Your Company
smtp-security,tls
```
---
## Testing Your Configuration
### Verify Connection
```http
GET /api/channels/{channel}/status
Authorization: Bearer <token>
```
Response:
```json
{
"channel": "instagram",
"connected": true,
"account": "@youraccount",
"permissions": ["read", "write"],
"rate_limit_remaining": 180,
"last_sync": "2025-01-21T10:00:00Z"
}
```
### Send Test Message
```http
POST /api/channels/{channel}/test
Authorization: Bearer <token>
Content-Type: application/json
{
"message": "Hello from General Bots!"
}
```
---
## Troubleshooting
### Common Issues
**Invalid Token**
- Tokens expire; regenerate and update
- Check token permissions match requirements
**Rate Limited**
- Reduce posting frequency
- Implement exponential backoff
- Consider upgrading API tier
**Webhook Not Receiving**
- Verify URL is publicly accessible
- Check SSL certificate is valid
- Confirm webhook is registered with platform
**Permission Denied**
- Review required permissions list
- Reauthorize with correct scopes
- Check app review status
### Debug Logging
Enable channel debug logging:
```bash
CHANNEL_DEBUG=true
CHANNEL_LOG_LEVEL=debug
```
---
## Security Best Practices
1. **Store secrets securely** - Use environment variables or secret management
2. **Rotate tokens regularly** - Set reminders for token refresh
3. **Use webhook signatures** - Validate incoming webhook requests
4. **Limit permissions** - Request only needed scopes
5. **Monitor usage** - Track API calls and rate limits
6. **Audit access** - Review connected accounts periodically
---
## Related Topics
- [POST TO Keyword](../06-gbdialog/keyword-post-to.md) - Posting from BASIC
- [Social Media Keywords](../06-gbdialog/keywords-social-media.md) - Full social media reference
- [Multi-Channel Architecture](./channels.md) - System design
- [Accounts Settings](../10-configuration-deployment/accounts.md) - UI configuration

343
src/03-knowledge-ai/feature-map.md
View file

@ -1,343 +0,0 @@
# Cargo Feature Map
This document provides a comprehensive reference for all Cargo.toml feature flags in General Bots, their dependencies, and how to use them for optimized builds.
## Overview
General Bots uses Rust's feature flag system to enable modular compilation. This allows you to:
- **Reduce binary size** by excluding unused features
- **Minimize dependencies** for faster compilation
- **Customize deployments** for specific use cases
- **Control resource usage** in constrained environments
## Feature Categories
```
┌─────────────────────────────────────────────────────────────┐
│ BUNDLE FEATURES │
│ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ ┌─────────┐ │
│ │communications│ │productivity │ │ documents │ │ full │ │
│ └──────┬──────┘ └──────┬──────┘ └─────┬─────┘ └────┬────┘ │
└─────────┼───────────────┼──────────────┼────────────┼──────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ APPLICATION FEATURES │
│ chat, mail, meet, calendar, tasks, drive, docs, paper... │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CORE TECHNOLOGIES │
│ cache, automation, llm, vectordb, monitoring... │
└─────────────────────────────────────────────────────────────┘
```
## Default Features
The default feature set provides a minimal but functional installation:
```toml
default = ["chat", "drive", "tasks", "automation", "cache", "directory"]
```
| Feature | Purpose |
|---------|---------|
| `chat` | AI chat interface |
| `drive` | File storage and management |
| `tasks` | Task scheduling and management |
| `automation` | BASIC script engine (Rhai) |
| `cache` | Redis session caching |
| `directory` | User directory services |
## Communication Features
Features for messaging, email, and real-time communication.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `chat` | - | Core chat functionality |
| `people` | - | Contact management |
| `mail` | lettre, mailparse, imap, native-tls | Full email client (IMAP/SMTP) |
| `meet` | livekit | Video conferencing |
| `social` | - | Social network integrations |
| `whatsapp` | - | WhatsApp Business API |
| `telegram` | - | Telegram Bot API |
| `instagram` | - | Instagram messaging |
| `msteams` | - | Microsoft Teams integration |
### Bundle: `communications`
Enables all communication features:
```toml
communications = ["chat", "people", "mail", "meet", "social",
"whatsapp", "telegram", "instagram", "msteams", "cache"]
```
## Productivity Features
Features for task management, scheduling, and project planning.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `calendar` | - | Event scheduling |
| `tasks` | cron, automation | Task management with scheduling |
| `project` | quick-xml | Project (MS Project style) |
| `goals` | - | Goal tracking and OKRs |
| `workspace` | - | Workspace management |
| `tickets` | - | Support ticket system |
| `billing` | - | Invoicing and payments |
### Bundle: `productivity`
```toml
productivity = ["calendar", "tasks", "project", "goals", "workspaces", "cache"]
```
## Document Features
Features for document processing and file management.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `drive` | aws-config, aws-sdk-s3, aws-smithy-async, pdf-extract | Cloud storage (S3-compatible) |
| `docs` | docx-rs, ooxmlsdk | Word document processing |
| `paper` | docs, pdf-extract | AI-assisted writing |
| `sheet` | calamine, spreadsheet-ods | Spreadsheet processing |
| `slides` | ooxmlsdk | Presentation processing |
### Bundle: `documents`
```toml
documents = ["paper", "docs", "sheet", "slides", "drive"]
```
## Media Features
Features for video, audio, and visual content.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `video` | - | Video processing |
| `player` | - | Media playback |
| `canvas` | - | Visual editor/whiteboard |
### Bundle: `media`
```toml
media = ["video", "player", "canvas"]
```
## Learning & Research Features
Features for AI-powered research and learning.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `learn` | - | Learning management |
| `research` | llm, vectordb | AI research assistant |
| `sources` | - | Knowledge source management |
### Bundle: `learning`
```toml
learning = ["learn", "research", "sources"]
```
## Analytics Features
Features for monitoring and business intelligence.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `analytics` | - | Usage analytics |
| `dashboards` | - | Custom BI dashboards |
| `monitoring` | sysinfo | System monitoring |
### Bundle: `analytics_suite`
```toml
analytics_suite = ["analytics", "dashboards", "monitoring"]
```
## Development Features
Features for bot development and automation.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `designer` | - | Visual bot builder |
| `editor` | - | Code editor |
| `automation` | rhai, cron | BASIC script engine |
### Bundle: `development`
```toml
development = ["designer", "editor", "automation"]
```
## Admin Features
Features for system administration.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `attendant` | - | Human handoff queue |
| `security` | - | Security settings |
| `settings` | - | Configuration UI |
### Bundle: `admin`
```toml
admin = ["attendant", "security", "settings"]
```
## Core Technologies
Low-level features that other features depend on.
| Feature | Dependencies | Description |
|---------|--------------|-------------|
| `llm` | - | LLM integration framework |
| `vectordb` | qdrant-client | Vector database for RAG |
| `nvidia` | - | NVIDIA GPU acceleration |
| `cache` | redis | Session caching |
| `compliance` | csv | Compliance/audit tools |
| `timeseries` | - | Time-series database |
| `weba` | - | Web accessibility features |
| `directory` | - | User directory services |
| `progress-bars` | indicatif | CLI progress indicators |
| `grpc` | tonic | gRPC server |
| `jemalloc` | tikv-jemallocator, tikv-jemalloc-ctl | Memory allocator |
| `console` | crossterm, ratatui, monitoring | Terminal UI mode |
## Build Profiles
### Minimal Build
Smallest possible binary with core functionality:
```bash
cargo build --release --no-default-features --features "chat,cache"
```
**Size**: ~15MB
**Use case**: Embedded devices, edge computing
### Lightweight Build
Core office features without heavy dependencies:
```bash
cargo build --release --no-default-features \
--features "chat,drive,tasks,cache,directory"
```
**Size**: ~25MB
**Use case**: Small deployments, resource-constrained servers
### Standard Build (Default)
Balanced feature set for most deployments:
```bash
cargo build --release
```
**Size**: ~40MB
**Use case**: General purpose, development
### Full Build
All features enabled:
```bash
cargo build --release --all-features
```
**Size**: ~80MB+
**Use case**: Enterprise deployments, feature testing
## Dependency Matrix
```
Feature | External Crates | Size Impact
-----------------+--------------------------------------+-------------
mail | lettre, mailparse, imap, native-tls | ~2MB
meet | livekit | ~5MB
vectordb | qdrant-client | ~3MB
drive | aws-sdk-s3, aws-config | ~4MB
docs | docx-rs, ooxmlsdk | ~2MB
sheet | calamine, spreadsheet-ods | ~1MB
automation | rhai, cron | ~2MB
cache | redis | ~1MB
console | crossterm, ratatui | ~1MB
monitoring | sysinfo | ~500KB
```
## Runtime Configuration
Features can be further controlled at runtime via the `.product` file:
```ini
# .product file
name=My Custom Bot
apps=chat,drive,tasks
theme=dark
```
The effective app list is the **intersection** of:
1. Features compiled in Cargo.toml
2. Apps enabled in `.product` file
This means you can compile with many features but only expose a subset to users.
## API Endpoint
The `/api/product` endpoint returns the current feature matrix:
```json
{
"name": "General Bots",
"apps": ["chat", "drive", "tasks"],
"compiled_features": ["chat", "drive", "tasks", "automation", "cache", "directory"],
"theme": "sentient"
}
```
## Checking Compiled Features
In Rust code, use conditional compilation:
```rust
#[cfg(feature = "mail")]
fn handle_email() {
// Only compiled when mail feature is enabled
}
```
At runtime, check the `COMPILED_FEATURES` constant:
```rust
use crate::core::features::COMPILED_FEATURES;
if COMPILED_FEATURES.contains(&"mail") {
// Feature is available
}
```
## Best Practices
1. **Start minimal**: Begin with the default features and add as needed
2. **Use bundles**: Prefer bundle features over individual ones for consistency
3. **Test builds**: Verify functionality after changing features
4. **Document requirements**: List required features in deployment docs
5. **Monitor size**: Track binary size as features are added
## See Also
- [Building from Source](../07-gbapp/building.md)
- [Cargo Tools Reference](../07-gbapp/cargo-tools.md)
- [White Label Configuration](../12-ecosystem-reference/README.md)

351
src/03-knowledge-ai/project-app.md
View file

@ -1,351 +0,0 @@
# Project App User Guide
The Project app is a comprehensive project management tool built into General Bots, providing Gantt charts, task dependencies, resource management, and critical path analysis.
## Overview
The Project app enables you to:
- Create and manage projects with tasks and milestones
- Visualize timelines with interactive Gantt charts
- Define task dependencies and relationships
- Allocate and track resource assignments
- Calculate critical paths for schedule optimization
- Track progress and completion status
## Getting Started
### Creating a Project
1. Navigate to **Apps** → **Project**
2. Click **New Project**
3. Enter project details:
- **Name**: Project title
- **Start Date**: When work begins
- **End Date**: Target completion (optional)
- **Description**: Project overview
### Project Structure
Projects contain:
```
Project
├── Summary Tasks (Phases)
│ ├── Tasks
│ │ ├── Subtasks
│ │ └── Milestones
│ └── More Tasks
└── Milestones
```
## Working with Tasks
### Creating Tasks
Click **Add Task** or press `Enter` on the last task row:
| Field | Description |
|-------|-------------|
| Name | Task title |
| Duration | Time to complete (e.g., "5 days") |
| Start | Task start date |
| Finish | Task end date (calculated or manual) |
| Predecessors | Tasks that must complete first |
| Resources | Assigned team members |
| Progress | Completion percentage (0-100%) |
### Task Types
| Type | Icon | Description |
|------|------|-------------|
| Task | ▬ | Standard work item |
| Milestone | ◆ | Zero-duration checkpoint |
| Summary | ▬▬ | Container for subtasks |
### Duration Formats
| Format | Example | Result |
|--------|---------|--------|
| Days | `5d` or `5 days` | 5 working days |
| Weeks | `2w` or `2 weeks` | 10 working days |
| Hours | `16h` or `16 hours` | 2 working days |
| Minutes | `240m` | 4 hours |
## Gantt Chart
### Navigation
- **Scroll**: Mouse wheel or drag timeline
- **Zoom**: Ctrl + scroll or zoom buttons
- **Today**: Click "Today" to center on current date
### Time Scales
| View | Shows | Best For |
|------|-------|----------|
| Day | Hours | Short tasks |
| Week | Days | Sprint planning |
| Month | Weeks | Project overview |
| Quarter | Months | Portfolio view |
| Year | Quarters | Long-term planning |
### Bar Colors
| Color | Meaning |
|-------|---------|
| Blue | Normal task |
| Green | Completed task |
| Red | Critical path task |
| Orange | Behind schedule |
| Purple | Milestone |
| Gray | Summary task |
## Task Dependencies
### Dependency Types
| Type | Code | Description |
|------|------|-------------|
| Finish-to-Start | FS | B starts when A finishes |
| Start-to-Start | SS | B starts when A starts |
| Finish-to-Finish | FF | B finishes when A finishes |
| Start-to-Finish | SF | B finishes when A starts |
### Creating Dependencies
**Method 1: Predecessors Column**
Enter task numbers in the Predecessors column:
```
2 → Task 2 must finish first (FS)
2FS → Same as above (explicit)
2SS → Start when task 2 starts
2FF+2d → Finish when task 2 finishes, plus 2 days
3,5 → Both tasks 3 and 5 must finish
```
**Method 2: Drag in Gantt**
1. Hover over a task bar
2. Drag from the end connector
3. Drop on another task
### Lag and Lead Time
| Syntax | Meaning |
|--------|---------|
| `2FS+3d` | Start 3 days after task 2 finishes |
| `2FS-2d` | Start 2 days before task 2 finishes |
| `2SS+1w` | Start 1 week after task 2 starts |
## Resource Management
### Adding Resources
1. Click **Resources** tab
2. Click **Add Resource**
3. Enter resource details:
- Name
- Type (Work, Material, Cost)
- Rate (hourly/daily cost)
- Availability (percentage)
### Resource Types
| Type | Use Case | Unit |
|------|----------|------|
| Work | People | Hours |
| Material | Consumables | Quantity |
| Cost | Fixed costs | Currency |
### Assigning Resources
In the Resources column, enter:
```
John → 100% allocation
John[50%] → 50% allocation
John,Sarah → Two resources
John[50%],Sarah → Mixed allocations
```
### Resource Views
- **Resource Sheet**: List all resources with details
- **Resource Usage**: Time-phased work assignments
- **Resource Graph**: Visual workload chart
## Critical Path
### Understanding Critical Path
The critical path is the longest sequence of dependent tasks that determines the minimum project duration. Tasks on the critical path have zero float—any delay extends the project.
### Viewing Critical Path
1. Click **Format** → **Critical Path**
2. Critical tasks appear in red
3. Hover for float information
### Critical Path Analysis
| Metric | Description |
|--------|-------------|
| Total Float | Time a task can slip without delaying project |
| Free Float | Time a task can slip without delaying successors |
| Critical | Float = 0, on critical path |
## Timeline View
The Timeline view provides a high-level summary:
1. Click **View** → **Timeline**
2. Drag tasks to add to timeline
3. Resize to set date range
### Timeline Features
- Executive summary view
- Milestone emphasis
- Export to PowerPoint
- Shareable as image
## Progress Tracking
### Updating Progress
**Method 1: Percentage**
Enter completion percentage (0-100%) in Progress column.
**Method 2: Actual Dates**
- Actual Start: When work actually began
- Actual Finish: When work actually completed
**Method 3: Remaining Work**
Enter remaining hours/days to completion.
### Status Indicators
| Indicator | Meaning |
|-----------|---------|
| ✓ | Complete (100%) |
| ● | In Progress |
| ○ | Not Started |
| ⚠ | Behind Schedule |
| 🔴 | Critical & Late |
### Baseline Comparison
1. Set baseline: **Project** → **Set Baseline**
2. View variance: **View** → **Tracking Gantt**
3. Gray bars show original plan
## Reports
### Built-in Reports
| Report | Shows |
|--------|-------|
| Project Summary | Overall status, milestones |
| Task Status | All tasks with progress |
| Resource Overview | Assignments and workload |
| Cost Report | Budget vs actual costs |
| Critical Tasks | Critical path analysis |
### Generating Reports
1. Click **Reports**
2. Select report type
3. Choose date range
4. Click **Generate**
### Export Options
- PDF
- Excel
- CSV
- Image (PNG)
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Enter` | Add new task |
| `Tab` | Indent task (make subtask) |
| `Shift+Tab` | Outdent task |
| `Ctrl+Z` | Undo |
| `Ctrl+Y` | Redo |
| `Delete` | Delete selected |
| `Ctrl+C` | Copy task |
| `Ctrl+V` | Paste task |
| `F5` | Go to date |
| `Ctrl+G` | Go to task |
## BASIC Integration
### Creating Projects from BASIC
```bas
project = CREATE PROJECT "Website Redesign"
project.start_date = "2025-02-01"
project.description = "Complete website overhaul"
task1 = CREATE TASK project, "Design Phase"
task1.duration = "10 days"
task2 = CREATE TASK project, "Development"
task2.duration = "20 days"
task2.predecessors = task1.id
milestone = CREATE MILESTONE project, "Launch"
milestone.predecessors = task2.id
```
### Querying Projects
```bas
projects = GET FROM projects WHERE status = "active"
FOR EACH project IN projects
tasks = GET FROM tasks WHERE project_id = project.id
TALK "Project: " + project.name + " has " + LEN(tasks) + " tasks"
NEXT
```
## Tips and Best Practices
### Planning
1. **Start with milestones** - Define key deliverables first
2. **Work backwards** - From deadline to start
3. **Break down tasks** - No task longer than 2 weeks
4. **Identify dependencies** - What blocks what?
5. **Add buffer** - Include contingency time
### Execution
1. **Update regularly** - Daily or weekly progress
2. **Monitor critical path** - Watch for delays
3. **Rebalance resources** - Address overallocation
4. **Communicate changes** - Keep stakeholders informed
### Common Mistakes
| Mistake | Solution |
|---------|----------|
| Missing dependencies | Review task relationships |
| Over-allocated resources | Level workload |
| No milestones | Add checkpoints |
| Too much detail | Summarize minor tasks |
| No baseline | Set before execution |
## Related Topics
- [Task Management](./tasks.md) - Task app integration
- [Calendar Integration](./calendar.md) - Scheduling
- [Forms Integration](./forms.md) - Task intake forms
- [BASIC Reference](../06-gbdialog/keywords.md) - Automation keywords

467
src/03-knowledge-ai/whiteboard.md
View file

@ -1,467 +0,0 @@
# Meeting Whiteboard User Guide
The Meeting Whiteboard provides a collaborative canvas for real-time visual collaboration during meetings, enabling teams to sketch ideas, diagram workflows, and brainstorm together.
## Overview
The Whiteboard app enables you to:
- Draw freehand sketches and annotations
- Create shapes, diagrams, and flowcharts
- Add sticky notes and text labels
- Collaborate in real-time with meeting participants
- Export whiteboards as images or PDFs
- Save and revisit whiteboard sessions
## Getting Started
### Accessing the Whiteboard
**During a Meeting:**
1. Join a meeting in the Meet app
2. Click the **Whiteboard** button in the toolbar
3. A shared canvas opens for all participants
**Standalone Mode:**
1. Navigate to **Apps** → **Whiteboard**
2. Click **New Whiteboard**
3. Share the link to invite collaborators
### Canvas Basics
| Element | Description |
|---------|-------------|
| Canvas | Infinite drawing area |
| Toolbar | Tools on the left side |
| Properties | Settings on the right side |
| Zoom | Bottom-right controls |
| Participants | Avatars showing who's viewing |
## Drawing Tools
### Pen Tool
Freehand drawing with customizable settings:
| Setting | Options |
|---------|---------|
| Color | Any color |
| Size | 1-20 pixels |
| Opacity | 0-100% |
| Smoothing | Low, Medium, High |
**Keyboard Shortcut:** `P`
### Highlighter
Semi-transparent marker for emphasis:
- Automatic transparency (50%)
- Wide stroke for highlighting
- Colors: Yellow, Green, Pink, Blue
**Keyboard Shortcut:** `H`
### Eraser
Remove content from the canvas:
| Mode | Function |
|------|----------|
| Stroke | Erases entire strokes |
| Area | Erases within brush area |
**Keyboard Shortcut:** `E`
### Laser Pointer
Temporary pointer visible to all participants:
- Fades after 2 seconds
- Shows your cursor position
- Color matches your participant color
**Keyboard Shortcut:** `L`
## Shape Tools
### Basic Shapes
| Shape | Shortcut | Description |
|-------|----------|-------------|
| Rectangle | `R` | Boxes and containers |
| Ellipse | `O` | Circles and ovals |
| Triangle | `T` | Triangles |
| Line | `\` | Straight lines |
| Arrow | `A` | Directional arrows |
### Drawing Shapes
1. Select shape tool
2. Click and drag on canvas
3. Hold `Shift` for perfect proportions
4. Release to complete
### Shape Properties
| Property | Options |
|----------|---------|
| Fill | Solid, None, Pattern |
| Stroke | Color, Width, Style |
| Corners | Sharp, Rounded |
| Shadow | None, Light, Medium, Dark |
## Text and Notes
### Text Tool
Add text labels anywhere on the canvas:
1. Press `T` or select Text tool
2. Click on canvas
3. Type your text
4. Click outside to finish
**Text Settings:**
| Setting | Options |
|---------|---------|
| Font Size | 12-72pt |
| Font Weight | Normal, Bold |
| Alignment | Left, Center, Right |
| Color | Any color |
### Sticky Notes
Virtual post-it notes for ideas:
1. Press `N` or select Sticky Note
2. Click to place
3. Type content
4. Drag to reposition
**Sticky Note Colors:**
- Yellow (default)
- Pink
- Green
- Blue
- Purple
- Orange
## Connectors
### Creating Connectors
Link shapes to show relationships:
1. Select Connector tool (`C`)
2. Click on first shape
3. Click on second shape
4. Connector automatically routes
### Connector Types
| Type | Use Case |
|------|----------|
| Straight | Direct connection |
| Elbow | Right-angle routing |
| Curved | Smooth curves |
### Connector Endpoints
| Endpoint | Meaning |
|----------|---------|
| Arrow | Direction/flow |
| Circle | Connection point |
| Diamond | Decision |
| None | Simple connection |
## Collaboration Features
### Real-Time Sync
All changes sync instantly to participants:
- See others' cursors in real-time
- Watch drawing as it happens
- Automatic conflict resolution
### Participant Cursors
Each participant has a unique cursor:
- Name label follows cursor
- Color identifies participant
- Fades when inactive
### Follow Mode
Focus on a presenter:
1. Click a participant's avatar
2. Select **Follow**
3. Your view follows their canvas position
### Presence Indicators
| Indicator | Meaning |
|-----------|---------|
| Green dot | Active, drawing |
| Yellow dot | Viewing |
| Gray dot | Idle |
## Canvas Navigation
### Panning
Move around the canvas:
- **Mouse:** Middle-click drag or Space + drag
- **Trackpad:** Two-finger drag
- **Touch:** Two-finger drag
### Zooming
| Action | Method |
|--------|--------|
| Zoom In | `Ctrl/Cmd + +` or scroll up |
| Zoom Out | `Ctrl/Cmd + -` or scroll down |
| Fit to Screen | `Ctrl/Cmd + 0` |
| Zoom to Selection | `Ctrl/Cmd + 2` |
### Minimap
Overview of entire canvas:
1. Click minimap icon (bottom-right)
2. Blue rectangle shows current view
3. Click to jump to location
## Selection and Editing
### Selecting Objects
| Action | Method |
|--------|--------|
| Single select | Click object |
| Multi-select | Shift + click |
| Box select | Drag selection rectangle |
| Select all | `Ctrl/Cmd + A` |
### Transforming Objects
| Action | Method |
|--------|--------|
| Move | Drag selected object |
| Resize | Drag corner handles |
| Rotate | Drag rotation handle |
| Constrain | Hold Shift while transforming |
### Alignment
Align selected objects:
| Alignment | Shortcut |
|-----------|----------|
| Left | `Alt + L` |
| Center | `Alt + C` |
| Right | `Alt + R` |
| Top | `Alt + T` |
| Middle | `Alt + M` |
| Bottom | `Alt + B` |
### Distribution
Evenly space selected objects:
- **Distribute Horizontally:** `Alt + H`
- **Distribute Vertically:** `Alt + V`
## Layers and Organization
### Layer Order
| Action | Shortcut |
|--------|----------|
| Bring to Front | `Ctrl/Cmd + ]` |
| Send to Back | `Ctrl/Cmd + [` |
| Bring Forward | `Ctrl/Cmd + Shift + ]` |
| Send Backward | `Ctrl/Cmd + Shift + [` |
### Grouping
Combine objects:
1. Select multiple objects
2. Press `Ctrl/Cmd + G` to group
3. Press `Ctrl/Cmd + Shift + G` to ungroup
### Locking
Prevent accidental edits:
1. Select object
2. Right-click → **Lock**
3. Right-click → **Unlock** to edit again
## Templates
### Using Templates
Start with pre-built layouts:
1. Click **Templates** in toolbar
2. Browse categories:
- Brainstorming
- Flowcharts
- Mind Maps
- Retrospectives
- Kanban
- User Journey
3. Click to apply
### Saving Templates
Create reusable templates:
1. Design your whiteboard
2. Click **File** → **Save as Template**
3. Name and categorize
4. Template appears in your library
## Export and Sharing
### Export Formats
| Format | Use Case |
|--------|----------|
| PNG | High-quality image |
| JPEG | Smaller file size |
| SVG | Vector graphics |
| PDF | Document sharing |
### Export Options
| Option | Description |
|--------|-------------|
| Selection | Export only selected area |
| Entire Canvas | Export everything |
| Current View | Export visible area |
| With Background | Include canvas background |
### Sharing
| Method | Description |
|--------|-------------|
| Link | Share view-only or edit link |
| Embed | Embed in websites |
| Email | Send link via email |
## Undo and History
### Undo/Redo
| Action | Shortcut |
|--------|----------|
| Undo | `Ctrl/Cmd + Z` |
| Redo | `Ctrl/Cmd + Y` or `Ctrl/Cmd + Shift + Z` |
### Version History
1. Click **History** icon
2. Browse previous versions
3. Click to preview
4. **Restore** to revert
## Keyboard Shortcuts
### Tools
| Shortcut | Tool |
|----------|------|
| `V` | Select |
| `P` | Pen |
| `H` | Highlighter |
| `E` | Eraser |
| `T` | Text |
| `N` | Sticky Note |
| `R` | Rectangle |
| `O` | Ellipse |
| `A` | Arrow |
| `C` | Connector |
| `L` | Laser Pointer |
### Actions
| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + Z` | Undo |
| `Ctrl/Cmd + Y` | Redo |
| `Ctrl/Cmd + C` | Copy |
| `Ctrl/Cmd + V` | Paste |
| `Ctrl/Cmd + D` | Duplicate |
| `Delete` | Delete selected |
| `Ctrl/Cmd + A` | Select all |
| `Ctrl/Cmd + G` | Group |
| `Escape` | Deselect / Cancel |
### Navigation
| Shortcut | Action |
|----------|--------|
| `Space + drag` | Pan canvas |
| `Ctrl/Cmd + +` | Zoom in |
| `Ctrl/Cmd + -` | Zoom out |
| `Ctrl/Cmd + 0` | Fit to screen |
| `Ctrl/Cmd + 1` | Zoom to 100% |
## Tips and Best Practices
### For Facilitators
1. **Prepare templates** - Set up structure before meeting
2. **Use frames** - Organize different activities
3. **Enable follow mode** - Guide participants' attention
4. **Use laser pointer** - Highlight without editing
5. **Save checkpoints** - Version history for reference
### For Participants
1. **Claim your color** - Identify your contributions
2. **Use sticky notes** - Quick idea capture
3. **Don't overlap** - Give space to others' work
4. **Use reactions** - Vote with emoji stamps
### Performance Tips
| Issue | Solution |
|-------|----------|
| Slow canvas | Reduce object count |
| Lag in sync | Check network connection |
| Export fails | Reduce canvas size |
## Integration with Meetings
### Starting from Meet
1. In Meet, click **More** → **Open Whiteboard**
2. Whiteboard opens for all participants
3. Whiteboard persists after meeting ends
### Whiteboard Recording
When meeting is recorded:
- Whiteboard activity is captured
- Playback shows drawing timeline
- Export includes whiteboard snapshots
## Related Topics
- [Meet App](./meet.md) - Video meetings
- [Tasks Integration](./tasks.md) - Create tasks from whiteboard
- [Drive Storage](./drive.md) - Whiteboard file storage
- [Export Options](./export.md) - Sharing and formats

80
src/03-knowledge-base/README.md Normal file
View file

@ -0,0 +1,80 @@
# Chapter 03: Knowledge Base System
Vector search and semantic retrieval for intelligent document querying.
## Overview
The Knowledge Base (gbkb) transforms documents into searchable semantic representations, enabling natural language queries against your organization's content.
## Architecture
<img src="../assets/chapter-03/kb-architecture-pipeline.svg" alt="KB Architecture Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
The pipeline processes documents through extraction, chunking, embedding, and storage to enable semantic search.
## Supported Formats
| Format | Features |
|--------|----------|
| PDF | Text, OCR, tables |
| DOCX | Formatted text, styles |
| HTML | DOM parsing |
| Markdown | GFM, tables, code |
| CSV/JSON | Structured data |
| TXT | Plain text |
## Quick Start
```basic
' Activate knowledge base
USE KB "company-docs"
' Bot now answers from your documents
TALK "How can I help you?"
```
## Key Concepts
### Document Processing
1. **Extract** - Pull text from files
2. **Chunk** - Split into ~500 token segments
3. **Embed** - Generate vectors (BGE model)
4. **Store** - Save to Qdrant
### Semantic Search
- Query converted to vector embedding
- Cosine similarity finds relevant chunks
- Top results injected into LLM context
- No explicit search code needed
### Storage Requirements
Vector databases need ~3.5x original document size:
- Embeddings: ~2x
- Indexes: ~1x
- Metadata: ~0.5x
## Configuration
```csv
name,value
embedding-url,http://localhost:8082
embedding-model,bge-small-en-v1.5
rag-hybrid-enabled,true
rag-top-k,10
```
## Chapter Contents
- [KB and Tools System](./kb-and-tools.md) - Integration patterns
- [Vector Collections](./vector-collections.md) - Collection management
- [Document Indexing](./indexing.md) - Processing pipeline
- [Semantic Search](./semantic-search.md) - Search mechanics
- [Episodic Memory](./episodic-memory.md) - Conversation history and context management
- [Semantic Caching](./caching.md) - Performance optimization
## See Also
- [.gbkb Package](../chapter-02/gbkb.md) - Folder structure
- [USE KB Keyword](../chapter-06-gbdialog/keyword-use-kb.md) - Keyword reference
- [Hybrid Search](../chapter-11-features/hybrid-search.md) - RAG 2.0

0
src/03-knowledge-ai/assets/caching-architecture.svg.backup → src/03-knowledge-base/assets/caching-architecture.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

0
src/03-knowledge-ai/assets/context-window.svg.backup → src/03-knowledge-base/assets/context-window.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

0
src/03-knowledge-ai/assets/kb-architecture-pipeline.svg.backup → src/03-knowledge-base/assets/kb-architecture-pipeline.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

0
src/03-knowledge-ai/assets/search-pipeline.svg.backup → src/03-knowledge-base/assets/search-pipeline.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.7 KiB

After

Width:  |  Height:  |  Size: 8.7 KiB

0
src/03-knowledge-ai/assets/storage-breakdown.svg.backup → src/03-knowledge-base/assets/storage-breakdown.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
src/03-knowledge-ai/assets/storage-multiplication.svg.backup → src/03-knowledge-base/assets/storage-multiplication.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.9 KiB

After

Width:  |  Height:  |  Size: 7.9 KiB

0
src/03-knowledge-ai/assets/technical-specs.svg.backup → src/03-knowledge-base/assets/technical-specs.svg.backup
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.7 KiB

After

Width:  |  Height:  |  Size: 6.7 KiB

2
src/03-knowledge-ai/caching.md → src/03-knowledge-base/caching.md
View file

@ -2,7 +2,7 @@
botserver includes automatic caching to improve response times and reduce redundant processing, including semantic caching for LLM responses using an in-memory cache component.
<img src="../assets/03-knowledge-ai/caching-architecture.svg" alt="Caching Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-03/caching-architecture.svg" alt="Caching Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
## Features

4
src/03-knowledge-ai/episodic-memory.md → src/03-knowledge-base/episodic-memory.md
View file

@ -183,5 +183,5 @@ Both features reduce costs and improve performance independently.
## See Also
- [Semantic Caching](./caching.md) - Response caching system
- [Configuration Parameters](../10-configuration-deployment/parameters.md) - Full parameter reference
- [LLM Configuration](../10-configuration-deployment/llm-config.md) - Model settings
- [Configuration Parameters](../chapter-08-config/parameters.md) - Full parameter reference
- [LLM Configuration](../chapter-08-config/llm-config.md) - Model settings

0
src/03-knowledge-ai/indexing.md → src/03-knowledge-base/indexing.md
View file

0
src/03-knowledge-ai/kb-and-tools.md → src/03-knowledge-base/kb-and-tools.md
View file

6
src/03-knowledge-ai/semantic-search.md → src/03-knowledge-base/semantic-search.md
View file

@ -2,7 +2,7 @@
Semantic search finds relevant content by meaning, not just keywords. When a user asks "How many days off do I get?", the system matches documents about "vacation policy" or "PTO allowance" even though the words differ.
<img src="../assets/03-knowledge-ai/search-pipeline.svg" alt="Search Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-03/search-pipeline.svg" alt="Search Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
## How It Works
@ -93,7 +93,7 @@ episodic-memory-threshold,4 # When to compress older context
## See Also
- [Hybrid Search](../03-knowledge-ai/hybrid-search.md) - Combining semantic + keyword search
- [Hybrid Search](../chapter-11-features/hybrid-search.md) - Combining semantic + keyword search
- [Document Indexing](./indexing.md) - How documents are processed
- [Vector Collections](./vector-collections.md) - Technical vector DB details
- [USE KB](../04-basic-scripting/keyword-use-kb.md) - Keyword reference
- [USE KB](../chapter-06-gbdialog/keyword-use-kb.md) - Keyword reference

6
src/03-knowledge-ai/summary.md → src/03-knowledge-base/summary.md
View file

@ -52,6 +52,6 @@ This chapter explains how botserver manages knowledge base collections, indexing
## See Also
- [.gbkb Package](../02-architecture-packages/gbkb.md) - Folder structure for knowledge bases
- [LLM Configuration](../10-configuration-deployment/llm-config.md) - Model and provider settings
- [Hybrid Search](../03-knowledge-ai/hybrid-search.md) - Advanced RAG techniques
- [.gbkb Package](../chapter-02/gbkb.md) - Folder structure for knowledge bases
- [LLM Configuration](../chapter-08-config/llm-config.md) - Model and provider settings
- [Hybrid Search](../chapter-11-features/hybrid-search.md) - Advanced RAG techniques

2
src/03-knowledge-ai/vector-collections.md → src/03-knowledge-base/vector-collections.md
View file

@ -2,7 +2,7 @@
This chapter explains how botserver organizes knowledge into vector collections, the searchable units that power semantic retrieval. Understanding how collections work helps you structure documents effectively and optimize the knowledge your bots can access.
<img src="../assets/03-knowledge-ai/storage-breakdown.svg" alt="Storage Breakdown" style="max-height: 400px; width: 100%; object-fit: contain;">
<img src="../assets/chapter-03/storage-breakdown.svg" alt="Storage Breakdown" style="max-height: 400px; width: 100%; object-fit: contain;">
## From Folders to Collections

116
src/04-basic-scripting/execution-modes.md
View file

@ -1,116 +0,0 @@
# BASIC Execution Modes: RUNTIME vs WORKFLOW
General Bots BASIC scripts run in one of two execution modes. The mode is selected by a pragma at the top of the `.bas` file.
## Quick Comparison
| Feature | RUNTIME mode (default) | WORKFLOW mode ⚗️ |
|---------|----------------------|-----------------|
| **Pragma** | _(none)_ | `#workflow` |
| **Engine** | Rhai AST | Step engine + PostgreSQL |
| **HEAR behavior** | Blocks a thread | Suspends to DB, zero threads |
| **Server restart** | Loses position | Resumes exact step |
| **Side-effect re-run** | ❌ possible on crash | ✅ never |
| **Multi-day flows** | ❌ (1h timeout) | ✅ unlimited |
| **FOR EACH loops** | ✅ | ❌ |
| **FUNCTION / SUB** | ✅ | ❌ |
| **USE WEBSITE** | ✅ | ❌ |
| **Startup time** | ~1ms | ~2ms |
| **RAM per session** | 1 thread (~64KB) | 0 threads |
| **Observability** | Logs only | DB rows (queryable) |
| **Best for** | Tools, short dialogs | Multi-step dialogs, tickets, approvals |
---
## RUNTIME Mode (default)
Every `.bas` file without `#workflow` runs in RUNTIME mode. The script compiles to a Rhai AST and executes in a `spawn_blocking` thread. `HEAR` blocks the thread until the user replies (up to `hear-timeout-secs`, default 3600).
```basic
' ticket.bas — RUNTIME mode (no pragma)
TALK "Describe the issue"
HEAR description ' blocks thread, waits
SET ticket = CREATE(description)
TALK "Ticket #{ticket} created"
```
**When to use:** Tool scripts called by LLM, short dialogs (< 10 minutes), scripts using `FOR EACH`, `FUNCTION`, or `USE WEBSITE`.
---
## WORKFLOW Mode ⚗️
> **Status: Planned feature** — see `botserver/WORKFLOW_PLAN.md`
Add `#workflow` as the first line. The compiler produces a `Vec<Step>` instead of a Rhai AST. Each step is persisted to `workflow_executions` in PostgreSQL before execution. On `HEAR`, the engine saves state and returns — no thread held. On the next user message, execution resumes from the exact step.
```basic
#workflow
' ticket.bas — WORKFLOW mode
TALK "Describe the issue"
HEAR description ' saves state, returns, zero threads
SET ticket = CREATE(description)
TALK "Ticket #{ticket} created"
```
**When to use:** Multi-step dialogs, ticket creation, approval flows, anything that may span minutes or days.
### Keyword compatibility in WORKFLOW mode
| Category | Keywords | WORKFLOW support |
|----------|----------|-----------------|
| **Dialog** | `TALK`, `HEAR`, `WAIT` | ✅ |
| **Data** | `SET`, `GET`, `FIND`, `SAVE`, `INSERT`, `UPDATE`, `DELETE` | ✅ |
| **Communication** | `SEND MAIL`, `SEND TEMPLATE`, `SMS` | ✅ |
| **AI** | `USE KB`, `USE TOOL`, `REMEMBER`, `THINK KB` | ✅ |
| **HTTP** | `GET` (http), `POST`, `PUT`, `PATCH`, `DELETE` (http) | ✅ |
| **Scheduling** | `SCHEDULE`, `BOOK`, `CREATE TASK` | ✅ |
| **Expressions** | `FORMAT`, math, datetime, string functions | ✅ (via Rhai eval) |
| **Control flow** | `IF/ELSE/END IF` | ✅ |
| **Loops** | `FOR EACH / NEXT` | ❌ use RUNTIME |
| **Procedures** | `FUNCTION`, `SUB`, `CALL` | ❌ use RUNTIME |
| **Browser** | `USE WEBSITE` | ❌ use RUNTIME |
| **Events** | `ON EMAIL`, `ON CHANGE`, `WEBHOOK` | ❌ use RUNTIME |
### How WORKFLOW compiles
The compiler does **not** use Rhai for workflow mode. It is a line-by-line parser:
```
TALK "Hello ${name}" → Step::Talk { template: "Hello ${name}" }
HEAR description → Step::Hear { var: "description", type: "any" }
SET x = score + 1 → Step::Set { var: "x", expr: "score + 1" }
IF score > 10 THEN → Step::If { cond: "score > 10", then_steps, else_steps }
SEND MAIL to, s, body → Step::SendMail { to, subject, body }
```
Expressions (`score + 1`, `score > 10`) are stored as strings and evaluated at runtime using Rhai as a pure expression calculator — no custom syntax, no side effects.
### Observability
In WORKFLOW mode, every step is a DB row. You can query execution state directly:
```sql
SELECT script_path, current_step, state_json, status, updated_at
FROM workflow_executions
WHERE session_id = '<session-uuid>'
ORDER BY updated_at DESC;
```
---
## Choosing a Mode
```
Does the script use FOR EACH, FUNCTION, or USE WEBSITE?
YES → RUNTIME (no pragma)
Does the script have HEAR and may run for > 1 hour?
YES → WORKFLOW (#workflow)
Is it a tool script called by LLM (short, no HEAR)?
YES → RUNTIME (no pragma)
Is it a multi-step dialog (ticket, approval, enrollment)?
YES → WORKFLOW (#workflow) ⚗️ when available
```

477
src/04-basic-scripting/keyword-face-api.md
View file

@ -1,477 +0,0 @@
# Face API Keywords
General Bots provides face detection and analysis capabilities through BASIC keywords that integrate with Azure Face API and other providers.
<img src="../assets/gb-decorative-header.svg" alt="General Bots" style="max-height: 100px; width: 100%; object-fit: contain;">
## Overview
Face API keywords enable:
- Face detection in images and video frames
- Face verification (comparing two faces)
- Facial attribute analysis (age, emotion, glasses, etc.)
- Multi-provider support (Azure, AWS Rekognition, OpenCV)
## DETECT FACES
Detect faces in an image and return their locations and attributes.
### Syntax
```bas
faces = DETECT FACES image
faces = DETECT FACES image, options
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| image | String/File | Image path, URL, or base64 data |
| options | Object | Optional detection settings |
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| return_attributes | Boolean | false | Include facial attributes |
| return_landmarks | Boolean | false | Include facial landmarks |
| detection_model | String | "detection_01" | Detection model to use |
| recognition_model | String | "recognition_04" | Recognition model for face IDs |
### Return Value
Returns an array of detected faces:
```json
[
{
"face_id": "uuid",
"rectangle": {
"top": 100,
"left": 150,
"width": 200,
"height": 250
},
"confidence": 0.98,
"attributes": {
"age": 32,
"gender": "male",
"emotion": "happy",
"glasses": "none"
}
}
]
```
### Examples
#### Basic Detection
```bas
image = "/photos/team.jpg"
faces = DETECT FACES image
TALK "Found " + LEN(faces) + " face(s) in the image"
FOR EACH face IN faces
TALK "Face at position: " + face.rectangle.left + ", " + face.rectangle.top
NEXT
```
#### With Attributes
```bas
options = #{return_attributes: true}
faces = DETECT FACES "/photos/portrait.jpg", options
IF LEN(faces) > 0 THEN
face = faces[0]
TALK "Detected a " + face.attributes.age + " year old person"
TALK "Expression: " + face.attributes.emotion
END IF
```
#### Upload and Detect
```bas
ON FILE UPLOAD
IF file.type STARTS WITH "image/" THEN
faces = DETECT FACES file.path
IF LEN(faces) = 0 THEN
TALK "No faces detected in this image"
ELSE IF LEN(faces) = 1 THEN
TALK "Found 1 face"
ELSE
TALK "Found " + LEN(faces) + " faces"
END IF
END IF
END ON
```
## VERIFY FACE
Compare two faces to determine if they belong to the same person.
### Syntax
```bas
result = VERIFY FACE face_id1, face_id2
result = VERIFY FACE image1, image2
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| face_id1 | String | First face ID from detection |
| face_id2 | String | Second face ID from detection |
| image1 | String/File | First image (auto-detects face) |
| image2 | String/File | Second image (auto-detects face) |
### Return Value
```json
{
"is_identical": true,
"confidence": 0.92,
"threshold": 0.5
}
```
### Examples
#### Verify Using Face IDs
```bas
faces1 = DETECT FACES "/photos/id-card.jpg"
faces2 = DETECT FACES "/photos/selfie.jpg"
IF LEN(faces1) > 0 AND LEN(faces2) > 0 THEN
result = VERIFY FACE faces1[0].face_id, faces2[0].face_id
IF result.is_identical THEN
TALK "Match confirmed with " + ROUND(result.confidence * 100, 0) + "% confidence"
ELSE
TALK "Faces do not match"
END IF
END IF
```
#### Verify Using Images Directly
```bas
id_photo = "/documents/passport.jpg"
live_photo = "/uploads/verification-selfie.jpg"
result = VERIFY FACE id_photo, live_photo
IF result.is_identical AND result.confidence > 0.8 THEN
SET USER "verified", true
TALK "Identity verified successfully!"
ELSE
TALK "Verification failed. Please try again with a clearer photo."
END IF
```
#### KYC Verification Flow
```bas
TALK "Please upload a photo of your ID"
HEAR AS id_image
TALK "Now take a selfie for verification"
HEAR AS selfie_image
id_faces = DETECT FACES id_image
selfie_faces = DETECT FACES selfie_image
IF LEN(id_faces) = 0 THEN
TALK "Could not detect a face in your ID photo"
ELSE IF LEN(selfie_faces) = 0 THEN
TALK "Could not detect your face in the selfie"
ELSE
result = VERIFY FACE id_faces[0].face_id, selfie_faces[0].face_id
IF result.is_identical THEN
IF result.confidence >= 0.9 THEN
SET USER "kyc_status", "verified"
TALK "✅ Identity verified with high confidence"
ELSE IF result.confidence >= 0.7 THEN
SET USER "kyc_status", "pending_review"
TALK "⚠️ Verification needs manual review"
ELSE
SET USER "kyc_status", "failed"
TALK "❌ Verification confidence too low"
END IF
ELSE
SET USER "kyc_status", "failed"
TALK "❌ Faces do not match"
END IF
END IF
```
## ANALYZE FACE
Perform detailed analysis of facial attributes.
### Syntax
```bas
analysis = ANALYZE FACE image
analysis = ANALYZE FACE image, attributes
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| image | String/File | Image path, URL, or base64 data |
| attributes | Array | Specific attributes to analyze |
### Available Attributes
| Attribute | Description |
|-----------|-------------|
| age | Estimated age |
| gender | Detected gender |
| emotion | Primary emotion (happy, sad, angry, etc.) |
| glasses | Type of glasses (none, reading, sunglasses) |
| facial_hair | Beard, mustache, sideburns |
| hair | Hair color, bald, invisible |
| makeup | Eye makeup, lip makeup |
| accessories | Headwear, mask |
| occlusion | Face occlusion (forehead, eye, mouth) |
| blur | Image blur level |
| exposure | Image exposure level |
| noise | Image noise level |
| head_pose | Pitch, roll, yaw angles |
| smile | Smile intensity (0-1) |
### Return Value
```json
{
"face_id": "uuid",
"attributes": {
"age": 28,
"gender": "female",
"emotion": {
"primary": "happy",
"scores": {
"happy": 0.95,
"neutral": 0.03,
"surprise": 0.02
}
},
"glasses": "none",
"smile": 0.87,
"facial_hair": {
"beard": 0.0,
"mustache": 0.0,
"sideburns": 0.0
},
"head_pose": {
"pitch": -5.2,
"roll": 2.1,
"yaw": -8.3
},
"quality": {
"blur": "low",
"exposure": "good",
"noise": "low"
}
}
}
```
### Examples
#### Basic Analysis
```bas
analysis = ANALYZE FACE "/photos/headshot.jpg"
IF analysis != NULL THEN
TALK "Estimated age: " + analysis.attributes.age
TALK "Primary emotion: " + analysis.attributes.emotion.primary
TALK "Smile score: " + ROUND(analysis.attributes.smile * 100, 0) + "%"
END IF
```
#### Specific Attributes
```bas
attributes = ["age", "emotion", "glasses"]
analysis = ANALYZE FACE image, attributes
TALK "Age: " + analysis.attributes.age
TALK "Emotion: " + analysis.attributes.emotion.primary
TALK "Glasses: " + analysis.attributes.glasses
```
#### Photo Quality Check
```bas
analysis = ANALYZE FACE uploaded_photo
quality = analysis.attributes.quality
IF quality.blur = "high" THEN
TALK "Your photo is too blurry. Please upload a clearer image."
ELSE IF quality.exposure = "over" OR quality.exposure = "under" THEN
TALK "Lighting is not optimal. Please use better lighting."
ELSE IF analysis.attributes.occlusion.forehead OR analysis.attributes.occlusion.eye THEN
TALK "Part of your face is obscured. Please ensure your full face is visible."
ELSE
TALK "Photo quality is acceptable!"
END IF
```
#### Emotion-Based Response
```bas
ON MESSAGE
IF message.has_image THEN
analysis = ANALYZE FACE message.image
IF analysis != NULL THEN
emotion = analysis.attributes.emotion.primary
SWITCH emotion
CASE "happy"
TALK "You look happy! 😊 How can I help you today?"
CASE "sad"
TALK "I'm sorry you seem down. Is there anything I can help with?"
CASE "angry"
TALK "I sense some frustration. Let me see how I can assist you."
CASE "surprise"
TALK "Surprised? Let me know what's on your mind!"
DEFAULT
TALK "How can I help you today?"
END SWITCH
END IF
END IF
END ON
```
#### Customer Satisfaction Analysis
```bas
SET SCHEDULE "every day at 6pm"
photos = LIST "/store/customer-photos/today/"
emotions = #{happy: 0, neutral: 0, sad: 0, angry: 0}
total = 0
FOR EACH photo IN photos
analysis = ANALYZE FACE photo.path
IF analysis != NULL THEN
primary_emotion = analysis.attributes.emotion.primary
emotions[primary_emotion] = emotions[primary_emotion] + 1
total = total + 1
END IF
NEXT
IF total > 0 THEN
satisfaction_rate = ROUND((emotions.happy / total) * 100, 1)
report = "Daily Customer Mood Report\n"
report = report + "========================\n"
report = report + "Total analyzed: " + total + "\n"
report = report + "Happy: " + emotions.happy + "\n"
report = report + "Neutral: " + emotions.neutral + "\n"
report = report + "Satisfaction rate: " + satisfaction_rate + "%"
SEND MAIL TO "manager@store.com" SUBJECT "Daily Mood Report" BODY report
END IF
```
## Configuration
Add Face API credentials to your bot's `config.csv`:
### Azure Face API
```csv
key,value
face-api-provider,azure
azure-face-endpoint,https://your-resource.cognitiveservices.azure.com
azure-face-key,your-api-key
```
### AWS Rekognition
```csv
key,value
face-api-provider,aws
aws-access-key-id,your-access-key
aws-secret-access-key,your-secret-key
aws-region,us-east-1
```
### Local OpenCV (Offline)
```csv
key,value
face-api-provider,opencv
opencv-model-path,/models/face_detection
```
## Error Handling
```bas
ON ERROR RESUME NEXT
faces = DETECT FACES image
IF ERROR THEN
error_msg = ERROR MESSAGE
IF error_msg CONTAINS "rate limit" THEN
WAIT 60
faces = DETECT FACES image
ELSE IF error_msg CONTAINS "invalid image" THEN
TALK "Please provide a valid image file"
ELSE
TALK "Face detection is temporarily unavailable"
END IF
END IF
CLEAR ERROR
```
## Privacy Considerations
Face detection and analysis involves biometric data. Ensure you:
- Obtain explicit consent before processing facial images
- Store face IDs temporarily (they expire after 24 hours)
- Do not store facial templates long-term without consent
- Comply with GDPR, CCPA, and other privacy regulations
- Provide clear privacy notices to users
- Allow users to request deletion of their facial data
## Best Practices
**Use appropriate thresholds.** For security applications, use higher confidence thresholds (0.8+). For general matching, 0.6+ may suffice.
**Handle multiple faces.** Always check the number of detected faces and handle edge cases.
**Check image quality.** Poor lighting, blur, or occlusion affects accuracy. Validate quality before verification.
**Implement rate limiting.** Face API services have rate limits. Cache results and avoid redundant calls.
**Provide fallbacks.** If face detection fails, offer alternative verification methods.
**Respect privacy.** Only collect and process facial data with user consent and for legitimate purposes.
## See Also
- [ON FILE UPLOAD](./keyword-on.md) - Handle uploaded images
- [SET USER](./keyword-set-user.md) - Store verification status
- [ON ERROR](./keyword-on-error.md) - Error handling
- [SEND MAIL](./keyword-send-mail.md) - Send reports

387
src/04-basic-scripting/keyword-post-to.md
View file

@ -1,387 +0,0 @@
# POST TO
Publish content to social media platforms and messaging channels. Supports text, images, videos, and multi-platform posting.
<img src="../assets/gb-decorative-header.svg" alt="General Bots" style="max-height: 100px; width: 100%; object-fit: contain;">
## Syntax
```bas
POST TO platform content
POST TO platform content, caption
POST TO platform image, caption
POST TO "platform1,platform2" image, caption
POST TO platform AT "datetime" content
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| platform | String | Target platform name or comma-separated list |
| content | String/File | Text content, image path, or video path |
| caption | String | Optional caption or message text |
| datetime | String | Optional scheduled time (ISO 8601 format) |
## Supported Platforms
| Platform | Identifier | Content Types |
|----------|------------|---------------|
| Instagram | `instagram` | Images, Videos, Carousels |
| Facebook | `facebook` | Text, Images, Videos, Links |
| LinkedIn | `linkedin` | Text, Images, Articles |
| Twitter/X | `twitter` | Text, Images, Videos |
| Bluesky | `bluesky` | Text, Images |
| Threads | `threads` | Text, Images |
| Discord | `discord` | Text, Images, Embeds |
| TikTok | `tiktok` | Videos |
| YouTube | `youtube` | Videos, Community Posts |
| Pinterest | `pinterest` | Images (Pins) |
| Reddit | `reddit` | Text, Links, Images |
| WeChat | `wechat` | Text, Images, Articles |
| Snapchat | `snapchat` | Images, Videos |
## Basic Usage
### Text Post
```bas
POST TO BLUESKY "Just launched our new AI assistant! 🚀"
POST TO TWITTER "Check out our latest update"
POST TO LINKEDIN "Excited to announce our partnership with..."
```
### Image Post
```bas
image = "/marketing/product-launch.jpg"
caption = "Introducing our newest feature! #AI #Innovation"
POST TO INSTAGRAM image, caption
```
### Video Post
```bas
video = "/videos/tutorial.mp4"
description = "Quick tutorial on getting started"
POST TO TIKTOK video, description
POST TO YOUTUBE video, "How to automate your workflow"
```
## Multi-Platform Posting
Post to multiple platforms simultaneously:
```bas
image = "/content/announcement.png"
caption = "Big news! We're expanding to new markets 🌍"
POST TO "instagram,facebook,linkedin,twitter" image, caption
```
### Platform-Specific Content
```bas
image = "/promo/sale.jpg"
POST TO INSTAGRAM image, "Summer sale! 50% off everything ☀️ #Sale #Summer"
POST TO LINKEDIN image, "We're offering exclusive discounts to our business partners."
POST TO TWITTER image, "FLASH SALE: 50% off for the next 24 hours! 🔥"
```
## Scheduled Posting
Schedule posts for future publication:
```bas
POST TO INSTAGRAM AT "2025-02-14 09:00" image, "Happy Valentine's Day! ❤️"
POST TO FACEBOOK AT "2025-03-01 10:00:00" image, "March is here!"
```
### Campaign Scheduling
```bas
posts = [
#{date: "2025-02-01 09:00", caption: "Week 1: Introduction"},
#{date: "2025-02-08 09:00", caption: "Week 2: Deep Dive"},
#{date: "2025-02-15 09:00", caption: "Week 3: Advanced Tips"},
#{date: "2025-02-22 09:00", caption: "Week 4: Conclusion"}
]
FOR EACH post IN posts
POST TO "instagram,linkedin" AT post.date "/campaign/week" + i + ".png", post.caption
NEXT
```
## Platform-Specific Features
### Instagram
```bas
POST TO INSTAGRAM image, caption
POST TO INSTAGRAM video, caption
POST TO INSTAGRAM [image1, image2, image3], "Carousel post!"
```
### Facebook
```bas
POST TO FACEBOOK text
POST TO FACEBOOK image, caption
POST TO FACEBOOK link, description
```
### LinkedIn
```bas
POST TO LINKEDIN text
POST TO LINKEDIN image, caption
POST TO LINKEDIN article_url, commentary
```
### Twitter/X
```bas
POST TO TWITTER text
POST TO TWITTER image, text
POST TO TWITTER [image1, image2, image3, image4], text
```
### Bluesky
```bas
POST TO BLUESKY text
POST TO BLUESKY image, text
POST TO BLUESKY [image1, image2, image3, image4], text
```
### Threads
```bas
POST TO THREADS text
POST TO THREADS image, caption
```
### Discord
```bas
POST TO DISCORD text
POST TO DISCORD image, message
embed = #{
title: "New Release",
description: "Version 2.0 is here!",
color: 5814783,
fields: [
#{name: "Features", value: "New dashboard, API improvements"},
#{name: "Download", value: "https://example.com/download"}
]
}
POST TO DISCORD embed
```
### TikTok
```bas
video = "/videos/dance.mp4"
POST TO TIKTOK video, "Check out this tutorial! #Tutorial #HowTo"
```
### YouTube
```bas
video = "/videos/full-tutorial.mp4"
POST TO YOUTUBE video, "Complete Guide to Automation"
POST TO YOUTUBE "community", "What topics should we cover next? 🤔"
```
### Pinterest
```bas
POST TO PINTEREST image, "DIY Home Decor Ideas | Save for later!"
POST TO PINTEREST image, caption, board_name
```
### Reddit
```bas
POST TO REDDIT "r/programming", "title", "text content"
POST TO REDDIT "r/pics", "Check this out!", image
```
### WeChat
```bas
POST TO WECHAT text
POST TO WECHAT article_title, article_content, cover_image
```
### Snapchat
```bas
POST TO SNAPCHAT image
POST TO SNAPCHAT video
```
## Return Value
Returns a post identifier that can be used for metrics or deletion:
```bas
post_id = POST TO INSTAGRAM image, caption
SET BOT MEMORY "latest_instagram_post", post_id
metrics = GET INSTAGRAM METRICS post_id
TALK "Post received " + metrics.likes + " likes"
```
## Examples
### Daily Content Automation
```bas
SET SCHEDULE "every day at 10am"
day_of_week = WEEKDAY(NOW())
content = [
#{image: "/content/monday.png", caption: "Monday motivation! 💪"},
#{image: "/content/tuesday.png", caption: "Tech Tuesday tip 🔧"},
#{image: "/content/wednesday.png", caption: "Midweek check-in ✅"},
#{image: "/content/thursday.png", caption: "Throwback Thursday 📸"},
#{image: "/content/friday.png", caption: "Friday feels! 🎉"}
]
IF day_of_week >= 1 AND day_of_week <= 5 THEN
today = content[day_of_week - 1]
POST TO "instagram,facebook,linkedin" today.image, today.caption
END IF
```
### Product Launch Campaign
```bas
launch_image = "/products/new-product.jpg"
launch_date = "2025-03-15 09:00"
POST TO INSTAGRAM AT launch_date launch_image, "🚀 IT'S HERE! Our most requested feature is now live. Link in bio! #Launch #NewProduct"
POST TO TWITTER AT launch_date launch_image, "🚀 The wait is over! Check out our newest feature: [link] #ProductLaunch"
POST TO LINKEDIN AT launch_date launch_image, "We're excited to announce the launch of our newest innovation. After months of development, we're proud to share..."
POST TO FACEBOOK AT launch_date launch_image, "🎉 Big announcement! We just launched something amazing. Head to our website to learn more!"
TALK "Launch campaign scheduled for " + launch_date
```
### Customer Testimonial Posts
```bas
ON FORM SUBMIT "testimonial"
IF fields.share_permission = "yes" THEN
quote = fields.testimonial
name = fields.name
company = fields.company
caption = "\"" + quote + "\" - " + name + ", " + company + " ⭐️ #CustomerLove #Testimonial"
template_image = FILL "testimonial-template.png", #{quote: quote, name: name, company: company}
POST TO "linkedin,twitter" template_image, caption
TALK "Thank you for sharing your experience!"
END IF
END ON
```
### Engagement-Based Reposting
```bas
SET SCHEDULE "every sunday at 8pm"
posts = GET INSTAGRAM POSTS
best_post = NULL
best_engagement = 0
FOR EACH post IN posts
IF DATEDIFF("day", post.created_at, NOW()) <= 90 THEN
metrics = GET INSTAGRAM METRICS post.id
engagement = metrics.likes + metrics.comments * 2
IF engagement > best_engagement THEN
best_engagement = engagement
best_post = post
END IF
END IF
NEXT
IF best_post != NULL THEN
POST TO "facebook,linkedin" best_post.image, "In case you missed it: " + best_post.caption
END IF
```
## Configuration
Add platform credentials to your bot's `config.csv`:
```csv
key,value
bluesky-handle,your.handle.bsky.social
bluesky-app-password,your-app-password
threads-access-token,your-threads-token
discord-bot-token,your-discord-token
discord-channel-id,your-channel-id
tiktok-access-token,your-tiktok-token
youtube-api-key,your-youtube-key
pinterest-access-token,your-pinterest-token
reddit-client-id,your-reddit-client-id
reddit-client-secret,your-reddit-secret
wechat-app-id,your-wechat-app-id
wechat-app-secret,your-wechat-secret
snapchat-access-token,your-snapchat-token
```
## Error Handling
```bas
ON ERROR RESUME NEXT
post_id = POST TO INSTAGRAM image, caption
IF ERROR THEN
error_msg = ERROR MESSAGE
SEND MAIL TO "admin@company.com" SUBJECT "Post Failed" BODY error_msg
TALK "Sorry, I couldn't post right now. The team has been notified."
ELSE
TALK "Posted successfully!"
SET BOT MEMORY "last_post", post_id
END IF
CLEAR ERROR
```
## Best Practices
**Tailor content per platform.** What works on LinkedIn may not work on TikTok. Adjust tone, length, and format accordingly.
**Respect rate limits.** Platforms enforce posting limits. Space out posts and avoid bulk operations.
**Use scheduling wisely.** Analyze when your audience is most active and schedule posts accordingly.
**Store post IDs.** Save identifiers for later metrics retrieval or content management.
**Handle errors gracefully.** Network issues and API changes happen. Implement proper error handling.
**Test before campaigns.** Always test posts to a single platform before launching multi-platform campaigns.
## See Also
- [Social Media Keywords](./keywords-social-media.md) - Platform metrics and management
- [SET SCHEDULE](./keyword-set-schedule.md) - Automate posting schedules
- [FILL](./keyword-fill.md) - Generate images from templates
- [SET BOT MEMORY](./keyword-set-bot-memory.md) - Store post tracking data
- [ON ERROR](./keyword-on-error.md) - Error handling

310
src/04-basic-scripting/keyword-save.md
View file

@ -1,310 +0,0 @@
# SAVE
Saves data to a database table using upsert (insert or update) semantics.
## Syntax
### Form 1: Save with object (classic)
```basic
SAVE "table", id, data
```
### Form 2: Save with variables (direct)
```basic
SAVE "table", id, field1, field2, field3, ...
```
The variable names are used as column names automatically.
## Parameters
### Form 1 (with object)
| Parameter | Type | Description |
|-----------|------|-------------|
| table | String | The name of the database table |
| id | String/Number | The unique identifier for the record |
| data | Object | A map/object containing field names and values |
### Form 2 (with variables)
| Parameter | Type | Description |
|-----------|------|-------------|
| table | String | The name of the database table |
| id | String/Number | The unique identifier for the record |
| field1, field2, ... | Any | Variable references (names become column names) |
## Description
`SAVE` performs an upsert operation:
- If a record with the given `id` exists, it updates the record
- If no record exists, it inserts a new one
The `id` parameter maps to the `id` column in the table.
### Form 1 vs Form 2
**Form 1** (with object) is useful when you need custom column names or complex data structures:
```basic
data = #{
"customer_name": "João Silva",
"email": "joao@example.com"
}
SAVE "customers", "CUST-001", data
```
**Form 2** (with variables) is simpler - variable names become column names:
```basic
customerName = "João Silva"
email = "joao@example.com"
phone = "+5511999887766"
SAVE "customers", "CUST-001", customerName, email, phone
' Creates columns: customerName, email, phone
```
This eliminates the need for WITH blocks when variable names match your desired column names.
### Perfect for TOOL Functions
**This is especially useful for TOOL functions** where variables are automatically filled by user input and can be saved directly without needing WITH blocks:
```basic
' TOOL function parameters - automatically filled by LLM
PARAM nome AS STRING LIKE "João Silva" DESCRIPTION "Nome completo"
PARAM email AS EMAIL LIKE "joao@example.com" DESCRIPTION "Email"
PARAM telefone AS STRING LIKE "(21) 98888-8888" DESCRIPTION "Telefone"
' Generate unique ID
customerId = "CUST-" + FORMAT(NOW(), "yyyyMMddHHmmss")
' Save directly - variable names become column names automatically!
' No need for WITH block - just pass the variables directly
SAVE "customers", customerId, nome, email, telefone
RETURN customerId
```
In TOOL functions, the parameters (variables like `nome`, `email`, `telefone`) are automatically extracted from user input by the LLM. The direct SAVE syntax allows you to persist these variables immediately without manual object construction.
## Examples
### Basic Save with Object (Form 1)
```basic
' Create data object using Rhai map syntax
data = #{
"customer_name": "João Silva",
"email": "joao@example.com",
"phone": "+5511999887766",
"status": "active"
}
SAVE "customers", "CUST-001", data
```
### Save with Variables - No WITH Block Needed (Form 2)
```basic
' Variable names become column names automatically
casamentoId = "CAS-20250117-1234"
protocolo = "CAS123456"
nomeNoivo = "Carlos Eduardo"
nomeNoiva = "Juliana Cristina"
telefoneNoivo = "(21) 98888-8888"
telefoneNoiva = "(21) 97777-7777"
emailNoivo = "carlos@example.com"
emailNoiva = "juliana@example.com"
tipoCasamento = "RELIGIOSO_COM_EFEITO_CIVIL"
dataPreferencial = "2026-12-15"
horarioPreferencial = "16:00"
' Save directly without WITH block
SAVE "casamentos", casamentoId, protocolo, nomeNoivo, nomeNoiva, telefoneNoivo, telefoneNoiva, emailNoivo, emailNoiva, tipoCasamento, dataPreferencial, horarioPreferencial
```
### Save Order Data (Direct Syntax - No Object)
```basic
order_id = "ORD-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
customer_id = "CUST-001"
customer_name = "João Silva"
total = 150.50
status = "pending"
' Save directly - variable names become columns
SAVE "orders", order_id, customer_id, customer_name, total, status
TALK "Order " + order_id + " saved successfully!"
```
### Save Event Registration
```basic
' Event registration form data
eventId = "EVT-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
nome = "Maria Santos"
email = "maria@example.com"
telefone = "(11) 91234-5678"
dataEvento = "2025-03-15"
quantidadePessoas = 3
observacoes = "Precisa de cadeira de rodas"
' Direct save - no WITH block needed
SAVE "eventos", eventId, nome, email, telefone, dataEvento, quantidadePessoas, observacoes
TALK "Inscrição confirmada! ID: " + eventId
```
### Update Existing Record
```basic
' If order exists, this updates it; otherwise creates it
order_id = "ORD-20250117-0001"
status = "shipped"
shipped_at = NOW()
tracking_number = "TRACK123456"
' Use object for updates to specific columns
update_data = #{
"status": status,
"shipped_at": shipped_at,
"tracking_number": tracking_number
}
SAVE "orders", order_id, update_data
```
### With WhatsApp Notification
```basic
WEBHOOK "new-customer"
customer_id = "CUST-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
phone = body.phone
name = body.name
source = "webhook"
' Direct save with variables
SAVE "customers", customer_id, phone, name, source
' Notify via WhatsApp
TALK TO "whatsapp:" + phone, "Welcome " + name + "! Your account has been created."
result_status = "ok"
result_customer_id = customer_id
```
### Building Data Dynamically
```basic
' Start with empty map and add fields
data = #{}
data.name = customer_name
data.email = customer_email
data.phone = customer_phone
data.registered_at = NOW()
IF has_referral THEN
data.referral_code = referral_code
data.discount = 10
END IF
SAVE "customers", customer_id, data
```
### Saving Multiple Related Records
```basic
WEBHOOK "create-order"
' Save order
order_id = body.order_id
customer_id = body.customer_id
total = body.total
status = "pending"
SAVE "orders", order_id, customer_id, total, status
' Save each line item
FOR EACH item IN body.items
line_id = order_id + "-" + item.sku
line_data = #{
"order_id": order_id,
"sku": item.sku,
"quantity": item.quantity,
"price": item.price
}
SAVE "order_items", line_id, line_data
NEXT item
' Notify customer
TALK TO "whatsapp:" + body.customer_phone, "Order #" + order_id + " confirmed!"
result_status = "ok"
```
### Comparison: WITH Block vs Direct Syntax
**Old way (WITH block):**
```basic
WITH casamento
id = casamentoId
protocolo = protocolo
noivo = nomeNoivo
noiva = nomeNoiva
END WITH
SAVE "casamentos", casamento
```
**New way (direct):**
```basic
' Variable names become column names automatically
SAVE "casamentos", casamentoId, protocolo, nomeNoivo, nomeNoiva
```
The direct syntax is cleaner and avoids the intermediate object creation. Use it when your variable names match your desired column names.
## Return Value
Returns an object with:
- `command`: "save"
- `table`: The table name
- `id`: The record ID
- `rows_affected`: Number of rows affected (1 for insert/update)
## Notes
- Table must exist in the database
- The `id` column is used as the primary key for conflict detection
- All string values are automatically sanitized to prevent SQL injection
- Column names are validated to prevent injection
## Comparison with INSERT and UPDATE
| Keyword | Behavior |
|---------|----------|
| `SAVE` | Upsert - inserts if new, updates if exists |
| `INSERT` | Always creates new record (may fail if ID exists) |
| `UPDATE` | Only updates existing records (no-op if not found) |
```basic
' SAVE is preferred for most cases
SAVE "customers", id, data ' Insert or update
' Use INSERT when you need a new record guaranteed
INSERT "logs", log_entry ' Always creates new
' Use UPDATE for targeted updates
UPDATE "orders", "status=pending", update_data ' Update matching rows
```
## See Also
- [INSERT](./keyword-insert.md) - Insert new records
- [UPDATE](./keyword-update.md) - Update existing records
- [DELETE](./keyword-delete.md) - Delete records
- [FIND](./keyword-find.md) - Query records

304
src/04-basic-scripting/keyword-send-mail.md
View file

@ -1,304 +0,0 @@
# SEND MAIL
Send email messages.
## Syntax
### Single Line
```basic
SEND MAIL to, subject, body
SEND MAIL to, subject, body USING "account@example.com"
```
### Multi-Line Block with Variable Substitution
```basic
BEGIN MAIL recipient
Subject: Email subject here
Dear ${customerName},
Your order ${orderId} is ready.
Thank you!
END MAIL
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `to` | String | Recipient email address(es), comma-separated for multiple |
| `subject` | String | Email subject line |
| `body` | String | Email body (plain text or HTML) |
| `account` | String | (Optional) Connected account to send through |
| `${variable}` | Expression | Variable substitution within MAIL blocks |
## Description
The `SEND MAIL` keyword sends emails using either:
1. **Default SMTP** - Configuration from `config.csv`
2. **Connected Account** - Send through Gmail, Outlook, etc. configured in Sources app
## BEGIN MAIL / END MAIL Blocks
The `BEGIN MAIL / END MAIL` block syntax allows you to write elegant multi-line emails with automatic variable substitution using `${variable}` syntax.
### Syntax
```basic
BEGIN MAIL recipient
Subject: Email subject ${variable}
Dear ${customerName},
Your order ${orderId} has been shipped.
Tracking: ${trackingNumber}
Best regards,
The Team
END MAIL
```
### How It Works
1. **First line after `BEGIN MAIL`**: Should contain the email recipient
2. **Line starting with `Subject:`**: Email subject line (supports `${variable}`)
3. **Blank line after subject**: Separates subject from body
4. **Body lines**: Email content with automatic `${variable}` substitution
5. **Each line** is converted to string concatenation with proper newline handling
**Input:**
```basic
nome = "João"
pedido = "12345"
BEGIN MAIL "cliente@example.com"
Subject: Confirmação do Pedido ${pedido}
Olá ${nome},
Seu pedido foi confirmado!
Atenciosamente,
Equipe de Vendas
END MAIL
```
**Converted to:**
```basic
SEND MAIL "cliente@example.com", "Confirmação do Pedido 12345", "Olá " + nome + ",\n\nSeu pedido foi confirmado!\n\nAtenciosamente,\nEquipe de Vendas"
```
### Variable Substitution Rules
- `${variableName}` - Replaced with the variable value
- `${FUNCTION(args)}` - Function calls are evaluated and substituted
- Plain text without `${}` is treated as a string literal
- Special characters like `$` (not followed by `{`) are preserved
- Newlines are preserved as `\n` in the final email body
### Examples
#### Simple Email
```basic
email = "customer@example.com"
nome = "Maria"
BEGIN MAIL email
Subject: Bem-vindo ao nosso serviço!
Olá ${nome},
Obrigado por se cadastrar!
Atenciosamente,
Equipe
END MAIL
```
#### With Function Calls
```basic
BEGIN MAIL "cliente@empresa.com"
Subject: Pedido ${pedidoId} - Confirmação
Prezado ${nomeCliente},
Confirmamos seu pedido #${pedidoId} no valor de ${FORMAT(total, "currency")}.
Entrega prevista para: ${FORMAT(dataEntrega, "dd/MM/yyyy")}
Atenciosamente,
Departamento de Vendas
END MAIL
```
#### HTML Email
```basic
BEGIN MAIL "cliente@exemplo.com"
Subject: Seu pedido foi enviado!
<h1>Confirmação de Pedido</h1>
<p>Olá ${nome},</p>
<p>Seu pedido <strong>${pedidoId}</strong> foi enviado com sucesso!</p>
<p>Valor: <em>${FORMAT(valor, "currency")}</em></p>
<p>Atenciosamente,<br>Loja Virtual</p>
END MAIL
```
### Real-World Example: Wedding Confirmation
```basic
PARAM nomeNoivo AS STRING LIKE "Carlos" DESCRIPTION "Nome do noivo"
PARAM nomeNoiva AS STRING LIKE "Ana" DESCRIPTION "Nome da noiva"
PARAM emailNoivo AS EMAIL LIKE "noivo@example.com" DESCRIPTION "Email do noivo"
PARAM emailNoiva AS EMAIL LIKE "noiva@example.com" DESCRIPTION "Email da noiva"
PARAM protocolo AS STRING LIKE "CAS123456" DESCRIPTION "Protocolo"
casamentoId = "CAS-" + FORMAT(NOW(), "yyyyMMddHHmmss")
tipoTexto = "Religioso Simples"
BEGIN MAIL emailNoivo
Subject: Confirmação de Casamento - Protocolo ${protocolo}
Queridos ${nomeNoivo} e ${nomeNoiva},
Parabéns pelo compromisso de amor que estão assumindo! Recebemos a solicitação de casamento no Santuário Cristo Redentor.
DADOS DA SOLICITAÇÃO:
Protocolo: ${protocolo}
ID: ${casamentoId}
Noivo: ${nomeNoivo}
Noiva: ${nomeNoiva}
Tipo: ${tipoTexto}
Nossa equipe verificará a disponibilidade e enviará todas as instruções necessárias em breve.
Que Deus abençoe a união de vocês!
Atenciosamente,
Secretaria do Santuário Cristo Redentor
Tel: (21) 4101-0770 | WhatsApp: (21) 99566-5883
END MAIL
```
### Multiple Recipients
Send the same email to multiple people:
```basic
BEGIN MAIL "team1@company.com"
Subject: Meeting Reminder
Team meeting tomorrow at 3 PM.
END MAIL
BEGIN MAIL "team2@company.com"
Subject: Meeting Reminder
Team meeting tomorrow at 3 PM.
END MAIL
```
Or use comma-separated recipients:
```basic
recipients = "john@company.com, jane@company.com, bob@company.com"
SEND MAIL recipients, "Meeting Update", "Meeting rescheduled to 4 PM"
```
### Advantages
1. **Cleaner Syntax** - No more repetitive string concatenation for email body
2. **Easier to Read** - Multi-line emails are natural to write and maintain
3. **Template-Like** - Write emails like templates with `${variable}` placeholders
4. **Automatic Newlines** - Blank lines in the block become `\n` in the email
5. **Perfect for TOOL Functions** - Variables are automatically filled by user input
## Examples
## Configuration
Default SMTP in `config.csv`:
```csv
name,value
email-from,noreply@example.com
email-server,smtp.example.com
email-port,587
email-user,smtp-user@example.com
email-pass,smtp-password
```
## Examples
```basic
SEND MAIL "user@example.com", "Welcome!", "Thank you for signing up."
```
```basic
recipients = "john@example.com, jane@example.com"
SEND MAIL recipients, "Team Update", "Meeting tomorrow at 3 PM"
```
```basic
body = "<h1>Welcome!</h1><p>Thank you for joining us.</p>"
SEND MAIL "user@example.com", "Getting Started", body
```
## USING Clause
Send through a connected account configured in Suite → Sources → Accounts:
```basic
SEND MAIL "customer@example.com", "Subject", body USING "support@company.com"
```
The email appears from that account's address with proper authentication.
```basic
SEND MAIL "customer@example.com", "Ticket Update", "Your ticket has been resolved." USING "support@company.com"
```
## Delivery Status
```basic
status = SEND MAIL "user@example.com", "Test", "Message"
IF status = "sent" THEN
TALK "Email delivered successfully"
END IF
```
## Best Practices
1. Use connected accounts for better deliverability
2. Validate email addresses before sending
3. Implement delays for bulk emails
4. Handle failures gracefully
## Troubleshooting
| Issue | Cause | Solution |
|-------|-------|----------|
| Auth failed | Invalid credentials | Check config.csv or re-authenticate account |
| Not sending | Firewall blocking | Verify port 587/465 is open |
| Going to spam | No domain auth | Configure SPF/DKIM |
| Account not found | Not configured | Add account in Suite → Sources |
## See Also
- [USE ACCOUNT](./keyword-use-account.md)
- [WAIT](./keyword-wait.md)
## Implementation
Located in `src/basic/keywords/send_mail.rs`

157
src/04-basic-scripting/keyword-think-kb.md
View file

@ -1,157 +0,0 @@
# THINK KB
Perform explicit knowledge base reasoning with structured results.
## Syntax
```basic
results = THINK KB "query_text"
results = THINK KB query_variable
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `query_text` | String | The question or search query to execute |
| `query_variable` | Variable | Variable containing the search query |
## Description
Unlike automatic KB search (USE KB), THINK KB provides explicit control over knowledge base queries with structured results for analysis and decision-making.
## Return Structure
```basic
{
"results": [
{
"content": "Relevant text content",
"source": "document.pdf",
"kb_name": "knowledge_base_name",
"relevance": 0.85,
"tokens": 150
}
],
"summary": "Brief summary of findings",
"confidence": 0.78,
"total_results": 5,
"sources": ["doc1.pdf", "doc2.md"],
"query": "original search query",
"kb_count": 2
}
```
## Examples
### Basic Usage
```basic
USE KB "policies"
results = THINK KB "What is the remote work policy?"
TALK results.summary
PRINT "Confidence: " + results.confidence
FOR i = 0 TO results.results.length - 1
result = results.results[i]
PRINT "Source: " + result.source
PRINT "Content: " + result.content
NEXT i
```
### Decision Making with Confidence
```basic
USE KB "technical_docs"
results = THINK KB "How to fix database errors?"
IF results.confidence > 0.8 THEN
TALK "I found reliable information: " + results.summary
top_result = results.results[0]
TALK "From: " + top_result.source
TALK top_result.content
ELSE IF results.confidence > 0.5 THEN
TALK "Found some information, but not completely certain"
ELSE
TALK "Couldn't find reliable information. Consult additional resources."
END IF
```
### Multi-Stage Reasoning
```basic
USE KB "research_papers"
' Stage 1: General search
general = THINK KB "machine learning applications"
' Stage 2: Specific search based on findings
IF general.confidence > 0.6 THEN
specific_query = "deep learning " + general.results[0].content.substring(0, 50)
specific = THINK KB specific_query
TALK "Overview: " + general.summary
TALK "Details: " + specific.summary
END IF
```
### Source Filtering
```basic
results = THINK KB "contract clauses"
pdf_results = []
FOR i = 0 TO results.results.length - 1
result = results.results[i]
IF result.source CONTAINS ".pdf" THEN
pdf_results.push(result)
END IF
NEXT i
TALK "Found " + pdf_results.length + " PDF results"
```
## Key Differences from USE KB
| Feature | USE KB (Automatic) | THINK KB (Explicit) |
|---------|-------------------|-------------------|
| **Trigger** | Automatic on user questions | Explicit keyword execution |
| **Control** | Behind-the-scenes | Full programmatic control |
| **Results** | Injected into LLM context | Structured data for processing |
| **Confidence** | Not exposed | Explicit confidence scoring |
| **Filtering** | Not available | Full result filtering |
## Best Practices
1. **Activate KBs First**: Use `USE KB` to activate knowledge bases
2. **Check Confidence**: Use thresholds for decision making
3. **Handle Empty Results**: Check `total_results` before accessing array
4. **Filter by Relevance**: Consider filtering results below 0.5 relevance
5. **Cache Results**: Store in variables for multiple uses
## Error Handling
```basic
TRY
results = THINK KB user_query
IF results.total_results = 0 THEN
TALK "No information found for: " + user_query
END IF
CATCH error
TALK "Search failed: " + error.message
END TRY
```
## Performance
- **Search Time**: 100-500ms depending on KB size
- **Memory**: Results cached for session
- **Token Limits**: Respects 2000 token default limit
- **Concurrent**: Searches all active KBs in parallel
## See Also
- [USE KB](./keyword-use-kb.md) - Activate knowledge bases
- [CLEAR KB](./keyword-clear-kb.md) - Deactivate knowledge bases
- [KB Statistics](./keyword-kb-statistics.md) - Knowledge base metrics

101
src/04-basic-scripting/keyword-use-website.md
View file

@ -1,101 +0,0 @@
# USE WEBSITE Keyword
**Syntax**
```basic
USE WEBSITE "https://example.com"
USE WEBSITE "https://example.com" REFRESH "1d"
```
**Parameters**
- `"url"` – A valid HTTP or HTTPS URL pointing to a website that should be made available in the conversation context.
- `"refresh"` – (Optional) How often to recrawl the website. Supports: `"1d"` (1 day), `"1w"` (1 week), `"1m"` (1 month), `"1y"` (1 year). Defaults to `"1m"`.
**Description**
`USE WEBSITE` operates in two distinct modes:
1. **Preprocessing Mode** (Script Compilation): When found in a BASIC script during compilation, it registers the website for background crawling. The crawler service will fetch, extract, and index the website's content into a vector database collection. The crawl happens immediately on first compile, then recurs based on the REFRESH interval.
2. **Runtime Mode** (Conversation Execution): During a conversation, `USE WEBSITE` associates an already-crawled website collection with the current session, making it available for queries via `FIND` or `LLM` calls. This behaves similarly to `USE KB` - it's a session-scoped association.
If a website hasn't been registered during preprocessing, the runtime execution will auto-register it for crawling.
**Refresh Interval Behavior**
- **Smart Interval Selection**: If the same URL is registered multiple times with different REFRESH intervals, the **shortest interval** is always used
- **Default**: If no REFRESH is specified, defaults to `"1m"` (1 month)
- **Formats Supported**:
- `"1d"` = 1 day
- `"1w"` = 1 week
- `"1m"` = 1 month (default)
- `"1y"` = 1 year
- Custom: `"3d"`, `"2w"`, `"6m"`, etc.
**Examples**
Basic usage with default 1-month refresh:
```basic
USE WEBSITE "https://docs.example.com"
```
High-frequency website (daily refresh):
```basic
USE WEBSITE "https://news.example.com" REFRESH "1d"
```
Stable documentation (monthly refresh):
```basic
USE WEBSITE "https://api.example.com/docs" REFRESH "1m"
```
Multiple registrations - shortest interval wins:
```basic
USE WEBSITE "https://example.com" REFRESH "1w"
USE WEBSITE "https://example.com" REFRESH "1d"
' Final refresh interval: 1d (shortest)
```
**Runtime Example**
```basic
USE WEBSITE "https://company.com/policies" REFRESH "1w"
question = HEAR "What would you like to know about our policies?"
FIND question
answer = LLM "Based on the search results, provide a clear answer"
TALK answer
```
**Preprocessing Behavior**
When the script is compiled:
- The URL is validated
- The website is registered in the `website_crawls` table with the specified refresh policy
- The crawler service immediately starts crawling the website
- Subsequent crawls are scheduled based on the REFRESH interval
- Status can be: pending (0), crawled (1), or failed (2)
**Runtime Behavior**
When executed in a conversation:
- Checks if the website has been registered and crawled
- If not registered, auto-registers with default 1-month refresh
- Associates the website collection with the current session
- Makes the content searchable via `FIND` and available to `LLM`
**Database Schema**
The `website_crawls` table stores:
- `refresh_policy` - User-configured refresh interval (e.g., "1d", "1w", "1m")
- `expires_policy` - Internal representation in days
- `next_crawl` - Timestamp for next scheduled crawl
- `crawl_status` - 0=pending, 1=success, 2=processing, 3=error
**Related Keywords**
- [CLEAR WEBSITES](./keyword-clear-websites.md) - Remove all website associations from session
- [USE KB](./keyword-use-kb.md) - Similar functionality for knowledge base files
- [FIND](./keyword-find.md) - Search within loaded websites and KBs
- [LLM](./keyword-llm.md) - Process search results with AI

55
src/04-gbui/README.md Normal file
View file

@ -0,0 +1,55 @@
# Chapter 04: User Interface
General Bots UI system built with HTMX and server-side rendering.
## UI Modes
| Mode | Description | Use Case |
|------|-------------|----------|
| **default.gbui** | Full desktop suite | Complete productivity |
| **single.gbui** | Simple chat widget | Embedded chat |
| **console** | Terminal interface | Development/testing |
## Architecture
- **HTMX** - Dynamic updates without JavaScript frameworks
- **Server-Side Rendering** - Fast, SEO-friendly pages
- **Minimal JS** - No build process required
## Quick Access
```
http://localhost:8080 → Main interface
http://localhost:8080/chat → Chat app
http://localhost:8080/drive → File manager
http://localhost:8080/console → Terminal mode
```
## Suite Applications
| App | Purpose |
|-----|---------|
| Chat | AI assistant conversations |
| Drive | File management |
| Tasks | LLM-powered intelligent execution |
| Mail | Email client |
| Calendar | Scheduling |
| Meet | Video calls |
| Paper | AI writing |
| Research | AI search |
## Chapter Contents
- [Suite User Manual](./suite-manual.md) - End-user guide
- [UI Structure](./ui-structure.md) - Component layout
- [default.gbui](./default-gbui.md) - Full desktop mode
- [single.gbui](./single-gbui.md) - Chat widget mode
- [Console Mode](./console-mode.md) - Terminal interface
- [HTMX Architecture](./htmx-architecture.md) - Technical details
- [Suite Applications](./apps/README.md) - App documentation
- [How-To Tutorials](./how-to/README.md) - Step-by-step guides
## See Also
- [.gbtheme Package](../chapter-05-gbtheme/README.md) - Styling and themes
- [.gbui Structure](../chapter-02/gbui.md) - Package format

6
src/07-user-interface/admin-user-views.md → src/04-gbui/admin-user-views.md
View file

@ -205,7 +205,7 @@ Note: Sync controls (`/files/sync/start`, `/files/sync/stop`) communicate with t
## Related Documentation
- [Permissions Matrix](../09-security/permissions-matrix.md) - Detailed permission definitions
- [User Authentication](../09-security/user-auth.md) - Login and session management
- [REST Endpoints](../08-rest-api-tools/README.md) - Complete API reference
- [Permissions Matrix](../chapter-12-auth/permissions-matrix.md) - Detailed permission definitions
- [User Authentication](../chapter-12-auth/user-auth.md) - Login and session management
- [REST Endpoints](../chapter-10-rest/README.md) - Complete API reference
- [Suite User Manual](./suite-manual.md) - End-user guide

0
src/07-user-interface/apps/README.md → src/04-gbui/apps/README.md
View file

12
src/07-user-interface/apps/analytics.md → src/04-gbui/apps/analytics.md
View file

@ -334,7 +334,7 @@ Use Analytics in your bot dialogs:
### Query Metrics
```botserver/docs/src/07-user-interface/apps/analytics.basic
```botserver/docs/src/chapter-04-gbui/apps/analytics.basic
revenue = GET METRIC "total_revenue" FOR "this month"
lastMonth = GET METRIC "total_revenue" FOR "last month"
@ -346,7 +346,7 @@ TALK "Growth: " + FORMAT(growth, "#0.0") + "%"
### Generate Reports
```botserver/docs/src/07-user-interface/apps/analytics-reports.basic
```botserver/docs/src/chapter-04-gbui/apps/analytics-reports.basic
HEAR period AS TEXT "Which period? (weekly/monthly/quarterly)"
report = GENERATE REPORT "Sales Summary" FOR period
@ -360,7 +360,7 @@ TALK report.summary
### Get AI Insights
```botserver/docs/src/07-user-interface/apps/analytics-insights.basic
```botserver/docs/src/chapter-04-gbui/apps/analytics-insights.basic
insights = GET INSIGHTS FOR "Sales Dashboard"
TALK "Here are today's insights:"
@ -376,7 +376,7 @@ NEXT
### Create Dashboard Widget
```botserver/docs/src/07-user-interface/apps/analytics-widget.basic
```botserver/docs/src/chapter-04-gbui/apps/analytics-widget.basic
widget = NEW OBJECT
widget.type = "line_chart"
widget.title = "Daily Active Users"
@ -391,7 +391,7 @@ TALK "Widget added successfully"
### Scheduled Reports
```botserver/docs/src/07-user-interface/apps/analytics-scheduled.basic
```botserver/docs/src/chapter-04-gbui/apps/analytics-scheduled.basic
' This dialog runs on a schedule
report = GENERATE REPORT "Weekly Metrics" FOR "last 7 days"
@ -412,4 +412,4 @@ LOG "Weekly report sent to " + COUNT(recipients) + " recipients"
- [Research App](./research.md) - Deep dive into data questions
- [Paper App](./paper.md) - Create reports from insights
- [How To: Monitor Your Bot](../how-to/monitor-sessions.md)
- [Talk to Data Template](../../02-architecture-packages/templates.md)
- [Talk to Data Template](../../chapter-02/templates.md)

2
src/07-user-interface/apps/calendar.md → src/04-gbui/apps/calendar.md
View file

@ -260,4 +260,4 @@ Tasks with due dates automatically appear on your calendar. When you complete a
- [Suite Manual](../suite-manual.md) - Complete user guide
- [Tasks App](./tasks.md) - Task integration
- [Meet App](./meet.md) - Video meetings
- [Calendar API](../../08-rest-api-tools/calendar-api.md) - API reference
- [Calendar API](../../chapter-10-rest/calendar-api.md) - API reference

2
src/07-user-interface/apps/chat.md → src/04-gbui/apps/chat.md
View file

@ -96,7 +96,7 @@ Bot responses support full Markdown rendering:
### WebSocket Connection
```
ws://your-server:9000/ws
ws://your-server:8080/ws
```
**Message Types:**

2
src/07-user-interface/apps/compliance-api.md → src/04-gbui/apps/compliance-api.md
View file

@ -688,4 +688,4 @@ X-Signature: sha256=...
- [Compliance App](./compliance.md) - User interface guide
- [How To: Configure Compliance](../how-to/configure-compliance.md)
- [BASIC Compliance Keywords](../../04-basic-scripting/keywords-reference.md)
- [BASIC Compliance Keywords](../../chapter-06-gbdialog/keywords-reference.md)

223
src/07-user-interface/apps/compliance.md → src/04-gbui/apps/compliance.md
View file

@ -1,6 +1,6 @@
# Compliance Center
# Compliance - Security Scanner
> **Your privacy, security, and data governance guardian**
> **Your privacy and security guardian**
<img src="../../assets/suite/compliance-screen.svg" alt="Compliance Interface Screen" style="max-width: 100%; height: auto;">
@ -8,14 +8,7 @@
## Overview
Compliance Center is the comprehensive security, privacy, and data governance app in General Bots Suite. Monitor data handling, manage consent, respond to data subject requests, prevent data loss, manage legal holds, classify sensitive information, and ensure your bots comply with regulations like LGPD, GDPR, HIPAA, and CCPA.
**Key Capabilities:**
- **DLP (Data Loss Prevention)** - Detect and prevent sensitive data leaks
- **eDiscovery** - Legal holds, content search, and case management
- **Information Protection** - Classify and protect sensitive documents
- **Compliance Scanning** - Automated regulatory compliance checks
- **Data Subject Requests** - Handle GDPR/LGPD rights requests
Compliance is the security and privacy management app in General Bots Suite. Monitor data handling, manage consent, respond to data subject requests, and ensure your bots comply with regulations like LGPD, GDPR, and CCPA. Compliance helps you protect user data and maintain trust.
---
@ -51,169 +44,6 @@ The dashboard gives you an at-a-glance view of your compliance status:
---
---
## Data Loss Prevention (DLP)
Automatically detect and prevent sensitive data from being shared inappropriately.
### Sensitive Data Types Detected
| Type | Examples | Severity |
|------|----------|----------|
| **Credit Card** | Visa, MasterCard, Amex | Critical |
| **SSN/CPF** | Social Security, Brazilian CPF | Critical |
| **Health ID** | Medicare, Medical Record Numbers | Critical |
| **Bank Account** | Account numbers, IBAN | High |
| **API Keys** | AWS, Azure, GCP credentials | Critical |
| **Private Keys** | RSA, SSH, PGP keys | Critical |
| **JWT Tokens** | Authentication tokens | High |
| **Email** | Email addresses | Medium |
| **Phone** | Phone numbers | Medium |
| **IP Address** | IPv4, IPv6 addresses | Low |
### DLP Policies
Create policies to control how sensitive data is handled:
**Policy Actions:**
| Action | Description |
|--------|-------------|
| **Allow** | Log but permit the action |
| **Warn** | Show warning to user |
| **Redact** | Mask sensitive data automatically |
| **Block** | Prevent the action entirely |
| **Quarantine** | Hold for manual review |
**Example Policy:**
```
Name: Block Credit Cards in External Emails
Data Types: Credit Card
Scope: Outbound emails
Action: Block
Severity Threshold: High
```
### DLP Scanning Integration
DLP scans are integrated with:
- **Mail** - Inbound and outbound email scanning
- **Drive** - File upload scanning
- **Chat** - Message content scanning
- **Social** - Post content scanning
---
## eDiscovery
Manage legal holds, search content, and export data for legal proceedings.
### Case Management
Create and manage legal cases:
1. **Create Case** - Name, description, matter ID
2. **Add Custodians** - Users whose data to preserve
3. **Apply Legal Hold** - Prevent data deletion
4. **Search Content** - Find relevant documents
5. **Review & Tag** - Mark documents as relevant
6. **Export** - Generate production packages
### Legal Hold
Legal holds prevent data deletion for specified users:
| Status | Description |
|--------|-------------|
| **Active** | Data is preserved, deletion blocked |
| **Released** | Hold removed, normal retention applies |
| **Pending** | Awaiting approval |
**What's Preserved:**
- Emails and attachments
- Chat messages
- Drive files
- Calendar events
- Social posts
- Conversation logs
### Content Search
Search across all data sources:
**Search Operators:**
| Operator | Example | Description |
|----------|---------|-------------|
| `AND` | contract AND confidential | Both terms required |
| `OR` | contract OR agreement | Either term |
| `NOT` | contract NOT draft | Exclude term |
| `"..."` | "final agreement" | Exact phrase |
| `from:` | from:john@company.com | Sender filter |
| `to:` | to:legal@company.com | Recipient filter |
| `date:` | date:2024-01-01..2024-12-31 | Date range |
| `type:` | type:pdf | File type filter |
### Export Formats
| Format | Use Case |
|--------|----------|
| **PST** | Email archives for Outlook |
| **PDF** | Document production |
| **Native** | Original file formats |
| **ZIP** | Bulk download |
| **Load File** | Litigation support systems |
---
## Information Protection
Classify and protect documents based on sensitivity levels.
### Sensitivity Labels
| Label | Icon | Description | Protections |
|-------|------|-------------|-------------|
| **Public** | 🟢 | Can be shared externally | None |
| **Internal** | 🔵 | Employees only | Watermark |
| **Confidential** | 🟡 | Restricted groups | Encrypt, watermark |
| **Highly Confidential** | 🔴 | Need-to-know basis | Encrypt, no copy/print, expire |
### Auto-Labeling Rules
Automatically classify documents based on content:
| Rule | Trigger | Label Applied |
|------|---------|---------------|
| Contains "salary" or "compensation" | Keywords | Confidential |
| Contains CPF/SSN | PII detection | Highly Confidential |
| Contains "public announcement" | Keywords | Public |
| Medical records | Content type | Highly Confidential |
| Financial statements | Content type | Confidential |
### Protection Actions
Based on label, apply protections:
| Protection | Description |
|------------|-------------|
| **Encryption** | AES-256 encryption at rest |
| **Watermark** | Visual marking with user info |
| **No Copy** | Disable copy/paste |
| **No Print** | Disable printing |
| **No Forward** | Prevent email forwarding |
| **Expiration** | Auto-revoke access after date |
| **Audit** | Log all access attempts |
### Label Inheritance
- Files inherit labels from parent folders
- Attachments inherit labels from emails
- Exports maintain original labels
---
### Security Scanner
Automatically scan your bots and data for compliance issues.
@ -452,7 +282,7 @@ Use Compliance features in your dialogs:
### Check Consent
```botserver/docs/src/07-user-interface/apps/compliance-consent.basic
```botserver/docs/src/chapter-04-gbui/apps/compliance-consent.basic
hasConsent = CHECK CONSENT user.id FOR "marketing"
IF hasConsent THEN
@ -469,7 +299,7 @@ END IF
### Request Data Access
```botserver/docs/src/07-user-interface/apps/compliance-access.basic
```botserver/docs/src/chapter-04-gbui/apps/compliance-access.basic
TALK "I can help you access your personal data."
HEAR email AS EMAIL "Please confirm your email address"
@ -488,7 +318,7 @@ END IF
### Delete User Data
```botserver/docs/src/07-user-interface/apps/compliance-delete.basic
```botserver/docs/src/chapter-04-gbui/apps/compliance-delete.basic
TALK "Are you sure you want to delete all your data?"
TALK "This action cannot be undone."
HEAR confirm AS BOOLEAN
@ -507,7 +337,7 @@ END IF
### Log Compliance Event
```botserver/docs/src/07-user-interface/apps/compliance-log.basic
```botserver/docs/src/chapter-04-gbui/apps/compliance-log.basic
' Log when sensitive data is accessed
LOG COMPLIANCE EVENT
TYPE "data_access"
@ -541,13 +371,13 @@ The Compliance API allows programmatic access to compliance features.
All endpoints require API key authentication:
```botserver/docs/src/07-user-interface/apps/compliance-auth.txt
```botserver/docs/src/chapter-04-gbui/apps/compliance-auth.txt
Authorization: Bearer your-api-key
```
### Example: Check User Consent
```botserver/docs/src/07-user-interface/apps/compliance-api-example.json
```botserver/docs/src/chapter-04-gbui/apps/compliance-api-example.json
GET /api/compliance/consent/usr_abc123
Response:
@ -570,44 +400,9 @@ Response:
---
---
## API Endpoints Summary
### DLP Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/dlp/scan` | POST | Scan content for sensitive data |
| `/api/compliance/dlp/policies` | GET/POST | List or create DLP policies |
| `/api/compliance/dlp/policies/{id}` | PUT/DELETE | Update or delete policy |
| `/api/compliance/dlp/violations` | GET | List DLP violations |
### eDiscovery Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/ediscovery/cases` | GET/POST | List or create cases |
| `/api/compliance/ediscovery/cases/{id}` | GET/PUT | Get or update case |
| `/api/compliance/ediscovery/cases/{id}/holds` | POST | Apply legal hold |
| `/api/compliance/ediscovery/cases/{id}/search` | POST | Search case content |
| `/api/compliance/ediscovery/cases/{id}/export` | POST | Export case data |
### Information Protection Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/protection/labels` | GET/POST | List or create labels |
| `/api/compliance/protection/labels/{id}` | PUT/DELETE | Update or delete label |
| `/api/compliance/protection/classify` | POST | Classify a document |
| `/api/compliance/protection/rules` | GET/POST | Auto-labeling rules |
---
## See Also
- [Compliance API Reference](./compliance-api.md) - Full API documentation
- [Analytics App](./analytics.md) - Monitor compliance metrics
- [Dashboards App](./dashboards.md) - Create compliance dashboards
- [Sources App](./sources.md) - Configure bot policies
- [How To: Monitor Your Bot](../how-to/monitor-sessions.md)

6
src/07-user-interface/apps/designer.md → src/04-gbui/apps/designer.md
View file

@ -361,7 +361,7 @@ Designer flows generate BASIC code. You can view and customize it.
Right-click any component and select "View Code":
```botserver/docs/src/07-user-interface/apps/designer-generated.basic
```botserver/docs/src/chapter-04-gbui/apps/designer-generated.basic
' Generated from "Customer Support" flow
TALK "Hello! How can I help you today?"
@ -384,7 +384,7 @@ END IF
Use the **Code** component to add custom BASIC:
```botserver/docs/src/07-user-interface/apps/designer-custom.basic
```botserver/docs/src/chapter-04-gbui/apps/designer-custom.basic
' Custom calculation
discount = 0
@ -404,4 +404,4 @@ finalPrice = orderTotal - discount
- [Sources App](./sources.md) - Manage prompts and templates
- [Chat App](./chat.md) - Test your flows
- [How To: Write Your First Dialog](../how-to/write-first-dialog.md)
- [BASIC Keywords Reference](../../04-basic-scripting/keywords-reference.md)
- [BASIC Keywords Reference](../../chapter-06-gbdialog/keywords-reference.md)

2
src/07-user-interface/apps/drive.md → src/04-gbui/apps/drive.md
View file

@ -328,4 +328,4 @@ drive-quota-gb,10
- [Admin vs User Views](../admin-user-views.md) - Permission levels
- [Chat App](./chat.md) - Upload files via chat
- [Player App](./player.md) - View files in Player
- [Storage API](../../08-rest-api-tools/storage-api.md) - API reference
- [Storage API](../../chapter-10-rest/storage-api.md) - API reference

29
src/07-user-interface/apps/mail.md → src/04-gbui/apps/mail.md
View file

@ -305,34 +305,9 @@ email-from,Your Name <you@gmail.com>
---
## Integration Features
### Snooze
Hide an email until later. Click the snooze button in the toolbar to pick a time (later today, tomorrow, next week). The email reappears automatically at the chosen time via `POST /api/email/snooze`.
### CRM Panel
When viewing an email, the CRM panel automatically looks up the sender via `GET /api/crm/contact/by-email/:email` and shows linked deals. Click **Log to CRM** to record the email against a contact or opportunity.
### AI Lead Suggestion
If the email looks like a sales inquiry, an AI banner appears offering to create a lead via `POST /api/ai/extract-lead`.
### Campaign Actions
Add the sender to a marketing list directly from the email via `POST /api/crm/lists/:id`.
### Smart Replies
AI-suggested short replies appear below the email content.
## Enabling Mail
Add `mail` to `apps=` in `botserver/.product`:
```
apps=...,mail
```
## See Also
- [Suite Manual](../suite-manual.md) - Complete user guide
- [Chat App](./chat.md) - Send quick emails via chat
- [Email API](../../08-rest-api-tools/email-api.md) - API reference
- [SEND MAIL Keyword](../../04-basic-scripting/keyword-send-mail.md) - BASIC integration
- [Email API](../../chapter-10-rest/email-api.md) - API reference
- [SEND MAIL Keyword](../../chapter-06-gbdialog/keyword-send-mail.md) - BASIC integration

2
src/07-user-interface/apps/meet.md → src/04-gbui/apps/meet.md
View file

@ -313,4 +313,4 @@ Allow browser access to:
- [Suite Manual](../suite-manual.md) - Complete user guide
- [Calendar App](./calendar.md) - Schedule meetings
- [Chat App](./chat.md) - Quick calls from chat
- [Calls API](../../08-rest-api-tools/calls-api.md) - API reference
- [Calls API](../../chapter-10-rest/calls-api.md) - API reference

10
src/07-user-interface/apps/paper.md → src/04-gbui/apps/paper.md
View file

@ -489,7 +489,7 @@ Control Paper from your bot dialogs:
### Create a Document
```botserver/docs/src/07-user-interface/apps/paper-create.basic
```botserver/docs/src/chapter-04-gbui/apps/paper-create.basic
doc = CREATE DOCUMENT "Project Notes"
doc.content = "Meeting notes from " + TODAY
@ -499,7 +499,7 @@ TALK "Document created: " + doc.id
### Generate Content with AI
```botserver/docs/src/07-user-interface/apps/paper-generate.basic
```botserver/docs/src/chapter-04-gbui/apps/paper-generate.basic
HEAR topic AS TEXT "What should I write about?"
content = GENERATE TEXT "Write a brief introduction about " + topic
@ -515,7 +515,7 @@ TALK LEFT(content, 200) + "..."
### Export a Document
```botserver/docs/src/07-user-interface/apps/paper-export.basic
```botserver/docs/src/chapter-04-gbui/apps/paper-export.basic
HEAR docName AS TEXT "Which document should I export?"
doc = FIND DOCUMENT docName
@ -531,7 +531,7 @@ END IF
### Search Documents
```botserver/docs/src/07-user-interface/apps/paper-search.basic
```botserver/docs/src/chapter-04-gbui/apps/paper-search.basic
HEAR query AS TEXT "What are you looking for?"
results = SEARCH DOCUMENTS query
@ -548,7 +548,7 @@ END IF
### Summarize a Document
```botserver/docs/src/07-user-interface/apps/paper-summarize.basic
```botserver/docs/src/chapter-04-gbui/apps/paper-summarize.basic
HEAR docName AS TEXT "Which document should I summarize?"
doc = FIND DOCUMENT docName

4
src/07-user-interface/apps/player.md → src/04-gbui/apps/player.md
View file

@ -269,5 +269,5 @@ Player is fully responsive:
## See Also
- [Drive App](./drive.md) - File management
- [Drive Integration](../../10-configuration-deployment/drive.md) - File storage configuration
- [Storage API](../../08-rest-api-tools/storage-api.md) - File management API
- [Drive Integration](../../chapter-08-config/drive.md) - File storage configuration
- [Storage API](../../chapter-10-rest/storage-api.md) - File management API

10
src/07-user-interface/apps/research.md → src/04-gbui/apps/research.md
View file

@ -317,7 +317,7 @@ Use Research in your bot dialogs:
### Basic Search
```botserver/docs/src/07-user-interface/apps/research-basic.basic
```botserver/docs/src/chapter-04-gbui/apps/research-basic.basic
HEAR question AS TEXT "What would you like to know?"
result = SEARCH question
@ -332,7 +332,7 @@ NEXT
### Search Specific Sources
```botserver/docs/src/07-user-interface/apps/research-sources.basic
```botserver/docs/src/chapter-04-gbui/apps/research-sources.basic
' Search only documents
result = SEARCH "vacation policy" IN "documents"
@ -345,7 +345,7 @@ result = SEARCH "product specs" IN "products.gbkb"
### Research with Follow-up
```botserver/docs/src/07-user-interface/apps/research-followup.basic
```botserver/docs/src/chapter-04-gbui/apps/research-followup.basic
TALK "What would you like to research?"
HEAR topic AS TEXT
@ -365,7 +365,7 @@ TALK "Research complete!"
### Export Research
```botserver/docs/src/07-user-interface/apps/research-export.basic
```botserver/docs/src/chapter-04-gbui/apps/research-export.basic
HEAR query AS TEXT "What should I research?"
result = SEARCH query
@ -384,7 +384,7 @@ TALK "Research saved to Paper"
### Automated Research Report
```botserver/docs/src/07-user-interface/apps/research-report.basic
```botserver/docs/src/chapter-04-gbui/apps/research-report.basic
topics = ["market trends", "competitor analysis", "customer feedback"]
report = ""

2
src/07-user-interface/apps/sources.md → src/04-gbui/apps/sources.md
View file

@ -4,7 +4,7 @@
---
<img src="../../assets/07-user-interface/sources-interface.svg" alt="Sources Interface" style="max-width: 100%; height: auto;">
<img src="../../assets/chapter-04/sources-interface.svg" alt="Sources Interface" style="max-width: 100%; height: auto;">
## Overview

4
src/07-user-interface/apps/suite.md → src/04-gbui/apps/suite.md
View file

@ -102,7 +102,7 @@ Default template for browser access:
```bash
./botserver
# Browse to http://localhost:9000
# Browse to http://localhost:8080
# Loads Suite interface
```
@ -221,4 +221,4 @@ suite-sidebar-collapsed,false
- [Drive App](./drive.md) - File management
- [Tasks App](./tasks.md) - Task management
- [HTMX Architecture](../htmx-architecture.md) - Technical details
- [Theme Customization](../../07-user-interface-gbtheme/README.md) - Styling
- [Theme Customization](../../chapter-05-gbtheme/README.md) - Styling

229
src/04-gbui/apps/tasks.md Normal file
View file

@ -0,0 +1,229 @@
# Tasks
> **Describe What You Want, Get a Working App**
---
## What is Tasks?
Tasks is where you describe what you want and the system builds it. No coding - just tell it what you need.
| You Say | You Get |
|---------|---------|
| "CRM for my cellphone store" | Working app with customers, sales, inventory |
| "Track repair status" | Kanban board with status workflow |
| "Sales dashboard" | Charts and metrics auto-updating |
---
## How It Works
```
DESCRIBE → PLAN → EXECUTE → DONE
```
### 1. Describe
Write what you want in plain language:
```
"Create a CRM for my cellphone store with:
- Customer list (name, phone, email)
- Product inventory with stock levels
- Sales tracking
- Repair status board"
```
### 2. Plan
System shows the execution plan:
```
Step 1: Create tables (customers, products, sales, repairs)
Step 2: Generate application UI
Step 3: Add search and filters
Step 4: Configure repair workflow
Confidence: 92% | ETA: 3 minutes
```
### 3. Execute
Watch progress in real-time:
```
[████████████████░░░░] 75%
Step 3 of 4: Adding search...
```
### 4. Done
Your app is ready:
```
✅ Application: /apps/cellphone-crm
✅ Tables: customers, products, sales, repairs
```
---
## Creating a Task
### Write Your Intent
Be specific about what you want:
| ✅ Good | ❌ Too Vague |
|---------|--------------|
| "CRM for cellphone store with customer tracking and repair status" | "Make an app" |
| "Inventory with low stock alerts when below 10 units" | "Track stuff" |
| "Sales dashboard with daily revenue chart" | "Dashboard" |
### Choose Mode
| Mode | Best For |
|------|----------|
| **Automatic** | Trusted, simple tasks |
| **Supervised** | Learning, want to review each step |
| **Dry Run** | Testing - see what would happen |
### Click Execute
The system runs each step and shows progress.
---
## Task Progress
### Status Icons
| Icon | Meaning |
|------|---------|
| ✓ | Completed |
| ◐ | Running |
| ○ | Pending |
| ⚠ | Needs attention |
| ✕ | Failed |
### Steps Are Saved
Every step is stored so you can:
- **Resume** if interrupted
- **Track** exactly where you are
- **Debug** if something fails
---
## Your Generated App
Apps are created at `.gbdrive/apps/{name}/`:
```
.gbdrive/apps/cellphone-crm/
├── index.html # Your application
├── _assets/
│ ├── htmx.min.js
│ └── styles.css
└── schema.json # Table definitions
```
### Direct API Access
Your app talks directly to botserver:
```html
<!-- List customers -->
<div hx-get="/api/db/customers" hx-trigger="load">
<!-- Add customer -->
<form hx-post="/api/db/customers">
<!-- Search -->
<input hx-get="/api/db/customers"
hx-trigger="keyup changed delay:300ms">
```
No middleware - HTMX calls the API directly.
---
## Data Storage
All data uses the `user_data` virtual table:
```
Your app: cellphone-crm
Table: customers
↓
API: /api/db/customers
↓
Storage: user_data (namespaced)
```
### Benefits
- Tables created on demand
- Each app isolated
- Add fields anytime
- No migrations needed
---
## Task Actions
| Action | When | What It Does |
|--------|------|--------------|
| **Pause** | Running | Stop temporarily |
| **Resume** | Paused | Continue from where stopped |
| **Cancel** | Anytime | Stop and discard |
| **Retry** | Failed | Try failed step again |
---
## From Chat
Create tasks by talking to your bot:
**You:** "I need a CRM for my cellphone store"
**Bot:** "I'll create that. Here's the plan:
- 4 steps, ~3 minutes
- Tables: customers, products, sales, repairs
Execute?"
**You:** "Yes"
**Bot:** "Started. I'll notify you when done."
---
## Examples
### Cellphone Store CRM
```
"CRM with customers, products, sales, and repair tracking
with status: received, diagnosing, repairing, ready, delivered"
```
### Restaurant Reservations
```
"Reservation system with tables, bookings, and waitlist"
```
### Inventory Tracker
```
"Inventory with products, suppliers, and low stock alerts"
```
---
## See Also
- [Autonomous Tasks](../../21-autonomous-tasks/README.md) - Complete guide
- [Dev Chat Widget](../dev-chat.md) - Test while developing
- [HTMX Architecture](../htmx-architecture.md) - How the UI works

2
src/07-user-interface/console-mode.md → src/04-gbui/console-mode.md
View file

@ -90,7 +90,7 @@ Console mode supports any terminal with basic text output capabilities. UTF-8 su
## Tips
Console mode operates in read-only fashion and does not accept bot commands. For interactive bot testing, use the web interface available at http://localhost:9000. The display refreshes automatically every few seconds to show current status. Output is buffered for performance to avoid slowing down the server during high activity periods.
Console mode operates in read-only fashion and does not accept bot commands. For interactive bot testing, use the web interface available at http://localhost:8080. The display refreshes automatically every few seconds to show current status. Output is buffered for performance to avoid slowing down the server during high activity periods.
## Troubleshooting

6
src/07-user-interface/dev-chat.md → src/04-gbui/dev-chat.md
View file

@ -130,7 +130,7 @@ This means:
The widget connects via WebSocket for real-time updates:
```
ws://localhost:9000/ws/dev
ws://localhost:8080/ws/dev
```
When connected:
@ -238,6 +238,6 @@ The dev chat widget:
## See Also
- [Autonomous Tasks](../17-autonomous-tasks/README.md) - How apps are generated
- [Autonomous Tasks](../21-autonomous-tasks/README.md) - How apps are generated
- [HTMX Architecture](./htmx-architecture.md) - Frontend patterns
- [REST API](../08-rest-api-tools/README.md) - API reference
- [REST API](../10-rest/README.md) - API reference

0
src/07-user-interface/how-to/README.md → src/04-gbui/how-to/README.md
View file

4
src/07-user-interface/how-to/add-kb-documents.md → src/04-gbui/how-to/add-kb-documents.md
View file

@ -6,7 +6,7 @@
---
<img src="../../assets/07-user-interface/step-flow-4-steps.svg" alt="Add Documents to KB - 4 Step Process" style="max-width: 100%; height: auto;">
<img src="../../assets/chapter-04/step-flow-4-steps.svg" alt="Add Documents to KB - 4 Step Process" style="max-width: 100%; height: auto;">
---
@ -40,7 +40,7 @@ Before you begin, make sure you have:
A **Knowledge Base (KB)** is a collection of documents that your bot uses to answer questions. When a user asks something, the bot searches through these documents to find relevant information.
<img src="../../assets/07-user-interface/kb-semantic-search-flow.svg" alt="Knowledge Base Semantic Search Flow" style="max-width: 100%; height: auto;">
<img src="../../assets/chapter-04/kb-semantic-search-flow.svg" alt="Knowledge Base Semantic Search Flow" style="max-width: 100%; height: auto;">
---

6
src/07-user-interface/how-to/connect-whatsapp.md → src/04-gbui/how-to/connect-whatsapp.md
View file

@ -6,7 +6,7 @@
---
<img src="../../assets/07-user-interface/step-flow-4-steps.svg" alt="Connect WhatsApp - 4 Step Process" style="max-width: 100%; height: auto;">
<img src="../../assets/chapter-04/step-flow-4-steps.svg" alt="Connect WhatsApp - 4 Step Process" style="max-width: 100%; height: auto;">
---
@ -39,7 +39,7 @@ Before you begin, make sure you have:
## Understanding WhatsApp Integration
<img src="../../assets/07-user-interface/whatsapp-integration-flow.svg" alt="WhatsApp Integration Flow" style="max-width: 100%; height: auto;">
<img src="../../assets/chapter-04/whatsapp-integration-flow.svg" alt="WhatsApp Integration Flow" style="max-width: 100%; height: auto;">
---
@ -698,4 +698,4 @@ whatsapp-business-account-id,987654321098765
- [Chat App](../apps/chat.md) - Web chat interface
- [Sources App](../apps/sources.md) - Bot configuration
- [Compliance App](../apps/compliance.md) - Data privacy for WhatsApp
- [BASIC Keywords](../../04-basic-scripting/keywords-reference.md) - WhatsApp-specific keywords
- [BASIC Keywords](../../chapter-06-gbdialog/keywords-reference.md) - WhatsApp-specific keywords

4
src/07-user-interface/how-to/create-first-bot.md → src/04-gbui/how-to/create-first-bot.md
View file

@ -63,7 +63,7 @@ Launch your preferred web browser by clicking its icon.
┌─────────────────────────────────────────────────────────────────────────┐
│ 🌐 Browser [─][□][×]│
├─────────────────────────────────────────────────────────────────────────┤
│ ← → ↻ │ https://your-company.bot:9000 │ ☆ │ │
│ ← → ↻ │ https://your-company.bot:8080 │ ☆ │ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Loading... │
@ -76,7 +76,7 @@ Launch your preferred web browser by clicking its icon.
Type your General Bots address in the address bar and press **Enter**.
💡 **Tip**: Your URL will look something like:
- `http://localhost:9000` (development)
- `http://localhost:8080` (development)
- `https://bots.yourcompany.com` (production)
- `https://app.pragmatismo.cloud` (cloud hosted)

0
src/07-user-interface/how-to/monitor-sessions.md → src/04-gbui/how-to/monitor-sessions.md
View file

0
src/07-user-interface/how-to/write-first-dialog.md → src/04-gbui/how-to/write-first-dialog.md
View file

0
src/07-user-interface/htmx-architecture.md → src/04-gbui/htmx-architecture.md
View file

Some files were not shown because too many files have changed in this diff Show more