botserver/docs/src

BotServer Documentation

Welcome to the BotServer documentation. This guide explains how to install, configure, extend, and deploy conversational AI bots using BotServer's template-based package system and BASIC scripting language.

---

About This Documentation

This documentation has been recently updated to accurately reflect the actual implementation of BotServer version 6.0.8. The following sections are now accurate:

✅ Accurate Documentation:

• Chapter 02: Package system (template-based .gbai structure)
• Chapter 06: Rust architecture (single-crate structure, module overview)
• Chapter 09: Core features
• Introduction: Architecture and capabilities

⚠️ Partial Documentation:

• Chapter 05: BASIC keywords (examples exist, full reference needs expansion)
• Chapter 08: Tool integration (concepts documented, implementation details needed)
• Chapter 11: Authentication (implemented but needs detail)

📝 Needs Documentation:

• UI module (src/ui/)
• UI tree module (src/ui_tree/)
• Riot compiler module (src/riot_compiler/)
• Prompt manager (src/prompt_manager/)
• API endpoints and web server routes
• MinIO/S3 drive integration details
• Video conferencing (LiveKit) integration

---

What is BotServer?

BotServer is an open-source conversational AI platform written in Rust. It enables users to create intelligent chatbots using:

• BASIC Scripting: Simple .bas scripts for conversation flows
• Template Packages: Organize bots as .gbai directories with dialogs, knowledge bases, and configuration
• Vector Search: Semantic document retrieval with Qdrant
• LLM Integration: OpenAI, local models, and custom providers
• Auto-Bootstrap: Automated installation of PostgreSQL, Redis, MinIO, and more
• Multi-Bot Hosting: Run multiple isolated bots on a single server

---

Quick Start

1. Installation: Follow Chapter 01: Run and Talk
2. Explore Templates: Check templates/announcements.gbai/ for examples
3. Create a Bot: Copy a template and modify it
4. Learn BASIC: Read Chapter 05: BASIC Reference
5. Configure: Edit config.csv in your .gbot/ directory
6. Deploy: Restart BotServer to activate changes

---

Table of Contents

Part I - Getting Started

• Chapter 01: Run and Talk - Installation and first conversation

Part II - Package System

• Chapter 02: About Packages - Overview of template-based packages
  • .gbai Architecture - Package structure and lifecycle
  • .gbdialog Dialogs - BASIC scripts
  • .gbkb Knowledge Base - Document collections
  • .gbot Configuration - Bot parameters
  • .gbtheme UI Theming - Web interface customization
  • .gbdrive File Storage - MinIO/S3 integration

Part III - Knowledge Base

• Chapter 03: gbkb Reference - Semantic search and vector database

Part IV - Themes and UI

• Chapter 04: gbtheme Reference - Customizing the web interface

Part V - BASIC Dialogs

• Chapter 05: gbdialog Reference - Complete BASIC scripting reference
  • Keywords: TALK, HEAR, LLM, SET_CONTEXT, USE_KB, and more

Part VI - Extending BotServer

• Chapter 06: Rust Architecture Reference - Internal architecture
  • Architecture Overview - Bootstrap process
  • Building from Source - Compilation and features
  • Module Structure - Single-crate organization
  • Service Layer - Module descriptions
  • Creating Custom Keywords - Extending BASIC
  • Adding Dependencies - Cargo.toml management

Part VII - Bot Configuration

• Chapter 07: gbot Reference - Configuration parameters

Part VIII - Tools and Integration

• Chapter 08: Tooling - External APIs and tool integration

Part IX - Feature Reference

• Chapter 09: Feature Matrix - Complete feature list
  • Core Features - Platform capabilities

Part X - Community

• Chapter 10: Contributing - Development guidelines

Part XI - Authentication and Security

• Chapter 11: Authentication - Security features

Appendices

• Appendix I: Database Model - Schema reference
• Glossary - Terms and definitions

---

Architecture Overview

BotServer is a monolithic Rust application (single crate) with the following structure:

Core Modules

• auth - Argon2 password hashing, session tokens
• bot - Bot lifecycle and management
• session - Persistent conversation state
• basic - BASIC interpreter (powered by Rhai)
• llm / llm_models - LLM provider integration
• context - Conversation memory management

Infrastructure

• bootstrap - Auto-installation of components
• package_manager - Manages PostgreSQL, Redis, MinIO, etc.
• web_server - Axum HTTP API and WebSocket
• drive - MinIO/S3 storage and vector DB
• config - Environment configuration

Features

• automation - Cron scheduling and events
• email - IMAP/SMTP integration (optional)
• meet - LiveKit video conferencing
• channels - Multi-channel support
• file - Document processing (PDF, etc.)
• drive_monitor - File system watching

---

Technology Stack

• Language: Rust 2021 edition
• Web: Axum + Tower + Tokio
• Database: Diesel ORM + PostgreSQL
• Cache: Redis/Valkey
• Storage: AWS SDK S3 (MinIO)
• Vector DB: Qdrant (optional)
• Scripting: Rhai engine
• Security: Argon2, AES-GCM
• Desktop: Tauri (optional)

---

Project Information

• Version: 6.0.8
• License: AGPL-3.0
• Repository: https://github.com/GeneralBots/BotServer
• Community: Open-source contributors from Pragmatismo.com.br

---

Documentation Status

This documentation is a living document that evolves with the codebase. Contributions are welcome! If you find inaccuracies or gaps:

1. Check the source code in src/ for ground truth
2. Submit documentation improvements via pull requests
3. Report issues on GitHub

See TODO.txt for known documentation gaps and future enhancements.

---

Next Steps

Start with Introduction for a comprehensive overview, or jump directly to Chapter 01: Run and Talk to install and run BotServer.