# General Bots Documentation (BotBook) **Version:** 6.2.0 **Purpose:** Comprehensive documentation for General Bots (mdBook format) ![General Bots Logo](https://github.com/GeneralBots/botserver/blob/main/logo.png?raw=true) --- ## 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)**. --- ## πŸ—οΈ Architecture General Bots Platform Architecture --- ## πŸ“¦ General Bots Repositories | Repository | Description | Status | |------------|-------------|--------| | [**botserver**](https://github.com/GeneralBots/botserver) | Core API server - LLM orchestration, automation, integrations | βœ… Production | | [**botui**](https://github.com/GeneralBots/botui) | Pure web UI - HTMX-based interface (suite & minimal) | βœ… Production | | [**botapp**](https://github.com/GeneralBots/botapp) | Tauri desktop wrapper - native file access, system tray | βœ… Production | | [**botlib**](https://github.com/GeneralBots/botlib) | Shared Rust library - common types, HTTP client, utilities | βœ… Production | | [**bottemplates**](https://github.com/GeneralBots/bottemplates) | Templates - bots, apps, prompts, UI components | βœ… Production | | [**botbook**](https://github.com/GeneralBots/botbook) | Documentation - mdBook format, multi-language | βœ… Production | --- ## πŸš€ Quick Start ### Prerequisites - **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 ```bash # Clone and run git clone https://github.com/GeneralBots/botserver cd botserver cargo run ``` On first run, botserver automatically: - Installs required components (PostgreSQL, S3 storage, Cache, LLM) - Sets up database with migrations - Downloads AI models - Starts HTTP server at `http://127.0.0.1:8080` ### Run the Desktop App ```bash # Clone botui (pure web) git clone https://github.com/GeneralBots/botui cd botui cargo run # Starts web server at :3000 # In another terminal, clone and run botapp (Tauri desktop) git clone https://github.com/GeneralBots/botapp 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 ### πŸ€– Multi-Vendor LLM API Unified interface for OpenAI, Groq, Claude, Anthropic, and local models. ### πŸ”§ MCP + LLM Tools Generation Instant tool creation from code and functions - no complex configurations. ### πŸ’Ύ Semantic Caching Intelligent response caching achieving **70% cost reduction** on LLM calls. ### 🌐 Web Automation Engine Browser automation combined with AI intelligence for complex workflows. ### πŸ“Š Enterprise Data Connectors Native integrations with CRM, ERP, databases, and external services. ### πŸ”„ Git-like Version Control Full history with rollback capabilities for all configurations and data. --- ## 🎯 4 Essential Keywords General Bots provides a minimal, focused system: ```basic USE KB "knowledge-base" ' Load knowledge base into vector database CLEAR KB "knowledge-base" ' Remove KB from session USE TOOL "tool-name" ' Make tool available to LLM 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 ![Chat](../assets/icons/gb-chat.svg) Analytics ``` #### 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 ``` --- ### πŸ’¬ Conversation Examples Use WhatsApp-style HTML format for bot interactions: ```html
``` --- ### πŸ“‹ 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) The main API server handling: - LLM orchestration and prompt management - Multi-channel communication (WhatsApp, Teams, Email, Web) - File storage and drive management - Task scheduling and automation - Authentication and authorization ### botui (Web Interface) Pure web UI with zero native dependencies: - **Suite**: Full-featured multi-app interface - **Minimal**: Lightweight single-page chat - HTMX-powered for minimal JavaScript - Works in any browser ### botapp (Desktop) Tauri wrapper adding native capabilities: - Local file system access - System tray integration - Native dialogs and notifications - Desktop-specific features ### botlib (Shared Library) Common Rust code shared across projects: - HTTP client for botserver communication - Shared types and models - Branding and configuration utilities - Error handling --- ## πŸ›‘οΈ Security - **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** --- ## πŸ†š Why General Bots? | vs. Alternative | General Bots Advantage | |-----------------|----------------------| | **ChatGPT/Claude** | Automates entire business processes, not just chat | | **n8n/Make** | Simpler approach with minimal programming | | **Microsoft 365** | User control, not locked ecosystems | | **Salesforce** | Open-source AI orchestration connecting all systems | --- ## πŸ”— Links - **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) --- ## 🀝 Contributing We welcome contributions! See our [Contributing Guidelines](https://github.com/GeneralBots/botserver/blob/main/docs/src/chapter-13-community/README.md). ### Contributors --- ## πŸ”‘ 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**. According to our dual licensing model, this program can be used either under the terms of the GNU Affero General Public License, version 3, or under a proprietary license. Copyright (c) pragmatismo.com.br. All rights reserved. --- > **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