EXECUTIVE VISION: GENERAL BOTS PLATFORM

OPEN SOURCE ENTERPRISE AI PLATFORM

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

INVESTOR HIGHLIGHTS

FEATURE OVERVIEW

LLM-ASSISTED ATTENDANT FEATURES

When conversations transfer from bot to human, the LLM continues working as a copilot:

WhatsApp Commands for Attendants:

/queue    - View waiting customers
/take     - Take next conversation
/tips     - Get AI tips
/polish   - Improve message
/replies  - Get suggestions
/summary  - Conversation summary
/resolve  - Mark complete

DEPLOYMENT OPTIONS

Option 1: Pragmatismo Managed Hosting

• Fully managed infrastructure
• Access via: YourCompany.pragmatismo.com.br
• Professional support included
• Complete data ownership

Option 2: Self-Hosted

• Deploy on your own infrastructure
• Full control over hardware and configuration
• Access via your own domain
• No external dependencies

Option 3: Hybrid Deployment

• Run locally with cloud backup
• Export everything as ZIP anytime
• Move between hosting options freely
• No vendor lock-in

COMPETITIVE ADVANTAGE

TECHNICAL ARCHITECTURE

FEATURE TIERS

Core Edition (Default)

• UI Server
• Console Interface
• Chat functionality
• Automation engine
• Task management
• Drive integration
• LLM support
• Redis caching
• Directory services

Standard Edition

• All Core features plus:
• Email integration (IMAP/SMTP)
• Calendar management
• Video meetings (LiveKit)
• Enhanced automation

Enterprise Edition

• All Standard features plus:
• Compliance monitoring (LGPD/GDPR/HIPAA)
• Attendance tracking with LLM assist
• Vector database (Qdrant)
• NVIDIA GPU acceleration
• Advanced monitoring
• gRPC support
• Multi-channel messaging (WhatsApp, Teams, Instagram)
• Human handoff with AI copilot
• CRM automations (collections, scheduling, sales)

QUICK START

# config.csv - Enable all features
name,value
crm-enabled,true
attendant-llm-tips,true
attendant-polish-message,true
attendant-smart-replies,true
attendant-auto-summary,true
attendant-sentiment-analysis,true

# attendant.csv - Configure your team
id,name,channel,preferences,department,aliases
att-001,John Smith,all,sales,commercial,john;johnny
att-002,Maria Santos,whatsapp,support,customer-service,maria

Result: Full hybrid AI+Human support system in minutes.

Full Edition

• All features enabled
• Complete platform capabilities

COMPLIANCE & PRIVACY

General Bots includes built-in compliance templates:

Privacy Rights Center (privacy.gbai)

• Data Access Requests - LGPD Art. 18 / GDPR Art. 15
• Data Rectification - LGPD Art. 18 III / GDPR Art. 16
• Data Erasure - LGPD Art. 18 VI / GDPR Art. 17 (Right to be Forgotten)
• Data Portability - LGPD Art. 18 V / GDPR Art. 20
• Consent Management - LGPD Art. 8 / GDPR Art. 7
• Processing Objection - LGPD Art. 18 IV / GDPR Art. 21

Supported Frameworks

• LGPD (Lei Geral de Proteção de Dados - Brazil)
• GDPR (General Data Protection Regulation - EU)
• HIPAA (Health Insurance Portability and Accountability Act)
• CCPA (California Consumer Privacy Act)
• SOC 2 (Service Organization Control)
• ISO 27001 (Information Security Management)

QUICK START

# Install botserver
cargo install botserver

# Initialize your deployment
botserver --init my-company

# Start the server
botserver --start

PLATFORM COMPARISON

INTEGRATION CAPABILITIES

LLM Providers

• OpenAI (GPT-5, o3)
• Anthropic (Claude Sonnet 4.5, Opus 4.5)
• Meta (Llama)
• DeepSeek
• Local models via Ollama
• Any OpenAI-compatible API

Communication Channels

• WhatsApp Business
• Microsoft Teams
• Telegram
• Slack
• Instagram
• Web chat
• SMS

Storage Backends

• AWS S3
• MinIO
• Any S3-compatible storage
• Local filesystem

Directory Services

• Built-in user management
• LDAP integration
• Active Directory
• OAuth/OIDC SSO

ABOUT PRAGMATISMO

Pragmatismo develops General Bots as an open-source platform for enterprise AI and automation. Our focus is on delivering practical, production-ready solutions that organizations can deploy and customize to meet their specific needs.

Repository: github.com/GeneralBots/botserver

License: AGPL-3.0

QUICK START

Ready to see it in action? Skip to the hands-on guide:

⚡ Quick Start: Run Your First Bot in 5 Minutes →

Or continue reading for the full journey:

NEXT STEPS

Chapter 01: Run and Talk →

General Bots Roadmap 2018-2026

Timeline Overview

Total: 77 Features (49 Complete ✅ • 28 Planned 📋)

Feature Highlights

Tasks (AI Autonomous) GO

The flagship feature enabling fully autonomous AI task execution:

• Human provides intent in natural language
• AI creates execution plan
• AI generates code/content
• AI deploys result
• Human reviews and approves

Available in: 2025 H2 (scaffolding), Q1 2026 (production)

Generators

Technology Stack

Backend: Rust, Actix-Web, Tokio, SQLx
Database: PostgreSQL
Storage: MinIO (S3-compatible)
Cache: Valkey (Redis alternative)
UI: HTMX, Askama templates
Desktop/Mobile: Tauri

Status Legend

Click the View Interactive Roadmap button above to explore all 77 features with detailed descriptions. Scroll horizontally to navigate the timeline from 2018 to 2026.

Introduction to General Bots

⚡ Want to skip ahead? Quick Start → gets you running in 5 minutes.

Build conversational AI bots in minutes, not months. General Bots lets you create intelligent chatbots by writing simple BASIC scripts and dropping in your documents. No complex frameworks, no cloud dependencies, no AI expertise required.

The No Forms Movement

Since 2017, Pragmatismo has championed the No Forms philosophy. The idea is simple but revolutionary:

People should converse, not fill forms.

Traditional software forces users into rigid forms with dropdowns, checkboxes, and validation errors. But humans don’t communicate that way. We talk. We explain. We ask questions.

General Bots was born from this vision: replace forms with conversations.

Before: The Form Experience

┌─────────────────────────────────────────┐
│ Customer Support Form                    │
├─────────────────────────────────────────┤
│ Name: [_______________]                  │
│ Email: [_______________]                 │
│ Department: [Select ▼]                   │
│ Priority: ○ Low ○ Medium ○ High         │
│ Subject: [_______________]               │
│ Description:                             │
│ [                                    ]   │
│ [                                    ]   │
│                                          │
│ Attachments: [Choose File]               │
│                                          │
│ [Submit]                                 │
│                                          │
│ ⚠️ Error: Email format invalid           │
│ ⚠️ Error: Description required           │
└─────────────────────────────────────────┘

Problems:

• Intimidating for users
• Requires learning the interface
• Validation errors frustrate
• No guidance or context
• One-size-fits-all approach

After: The Conversation Experience

Benefits:

• Natural and intuitive
• Guides users step by step
• Adapts to each situation
• No errors, just clarifications
• Feels like talking to a human

Projections, Not Screens

The No Forms philosophy extends beyond chat. In General Bots:

• Visualizations replace dashboards - Data is projected contextually, not displayed in static grids
• Conversations replace menus - Ask for what you need, don’t hunt through options
• AI handles complexity - The system adapts, users don’t configure
• Voice-first design - Everything works without a screen

This is why General Bots focuses on:

1. Conversational interfaces - Chat, voice, messaging
2. Contextual projections - Show relevant info when needed
3. Minimal UI - The less interface, the better
4. AI interpretation - Understand intent, not just input

Quick Example

Want a student enrollment bot? Here’s all you need:

1. Drop your documents in a .gbkb folder:

edu.gbkb/
  enrollment-policy.pdf
  course-catalog.pdf

2. Write a simple tool (optional):

' enrollment.bas
PARAM name, email, course
SAVE "enrollments.csv", name, email, course
TALK "Welcome to " + course + "!"

3. Chat naturally:

User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: Sarah Chen
Bot: Welcome to Computer Science, Sarah!

No form. No UI. Just conversation.

What Makes General Bots Different

Just Run It

./botserver

That’s it. No Kubernetes, no cloud accounts. The bootstrap process installs everything locally in 2-5 minutes. PostgreSQL, vector database, object storage, cache - all configured automatically with secure credentials stored in Vault.

Real BASIC, Real Simple

We brought BASIC back for conversational AI. See our complete keyword reference:

' save-note.bas - A simple tool
PARAM topic, content
SAVE "notes.csv", topic, content, NOW()
TALK "Note saved!"

Four lines. That’s a working tool the AI can call automatically.

Documents = Knowledge

Drop PDFs, Word docs, or text files into .gbkb/ folders. They’re instantly searchable. No preprocessing, no configuration, no pipelines. The bot answers questions from your documents automatically.

Tools = Functions

Create .bas files that the AI discovers and calls automatically. Need to save data? Send emails? Call APIs? Just write a tool. The AI figures out when and how to use it.

Architecture at a Glance

General Bots is a single binary that includes everything:

One process, one port, one command to run. Deploy anywhere - laptop, server, LXC container.

Real-World Use Cases

Customer Support Bot

documents: FAQs, policies, procedures
tools: ticket creation, status lookup
result: 24/7 support that actually helps

Employee Assistant

documents: HR policies, IT guides, company info
tools: leave requests, equipment orders
result: Instant answers, automated workflows

Sales Catalog Bot

documents: product specs, pricing sheets
tools: quote generation, order placement
result: Interactive product discovery

Meeting Assistant

documents: agenda, previous minutes
tools: action item tracking, scheduling
result: AI-powered meeting facilitator

The Package System

Bots are organized as packages - just folders with a naming convention:

my-bot.gbai/                    # Package root
├── my-bot.gbdialog/            # BASIC scripts
│   └── start.bas               # Entry point
├── my-bot.gbkb/                # Knowledge base
│   ├── policies/               # Document collection
│   └── procedures/             # Another collection
└── my-bot.gbot/                # Configuration
    └── config.csv              # Bot settings

Copy the folder to deploy. That’s it. No XML, no JSON schemas, no build process.

Getting Started in 3 Steps

1. Install (2 minutes)

wget https://github.com/GeneralBots/botserver/releases/latest/botserver
chmod +x botserver
./botserver

2. Open Browser

http://localhost:8080

3. Start Chatting

The default bot is ready. Ask it anything. Modify templates/default.gbai/ to customize.

Core Philosophy

1. No Forms - Conversations replace forms everywhere
2. Simplicity First - If it needs documentation, it’s too complex
3. Everything Included - No external dependencies to manage
4. Production Ready - Secure, scalable, enterprise-grade from day one
5. AI Does the Work - Don’t write logic the LLM can handle
6. Projections Over Screens - Show data contextually, not in dashboards

Technical Highlights

• Language: Written in Rust for performance and safety
• Database: PostgreSQL with Diesel ORM
• Cache: Redis-compatible cache for sessions
• Storage: S3-compatible object store (MinIO)
• Vectors: Qdrant for semantic search
• Security: Vault for secrets, Argon2 passwords, AES encryption
• Identity: Zitadel for authentication and MFA
• LLM: OpenAI API, Anthropic, Groq, or local models
• Scripting: Rhai-powered BASIC interpreter

A Brief History

2017 - Pragmatismo launches General Bots with the No Forms manifesto. The vision: conversational interfaces should replace traditional forms in enterprise software.

2018-2020 - Node.js implementation gains traction. Hundreds of bots deployed across banking, healthcare, education, and government sectors in Brazil and beyond.

2021-2023 - Major enterprises adopt General Bots for customer service automation. The platform handles millions of conversations.

2024 - Complete rewrite in Rust for performance, security, and reliability. Version 6.0 introduces the new architecture with integrated services.

Today - General Bots powers conversational AI for organizations worldwide, staying true to the original vision: people should converse, not fill forms.

What’s Next?

• Chapter 01 - Install and run your first bot
• Chapter 02 - Understanding packages
• Chapter 06 - Writing BASIC dialogs
• Templates - Explore example bots

Community

General Bots is open source (AGPL-3.0) developed by Pragmatismo.com.br and contributors worldwide.

• GitHub: https://github.com/GeneralBots/botserver
• Version: 6.1.0
• Status: Production Ready

Ready to build your bot? Turn to Chapter 01 and let’s go!

Built with ❤️ from Brazil since 2017

Chapter 01: Run and Talk

⚡ In a hurry? Jump straight to Quick Start — you’ll be chatting with your bot in 5 minutes.

Get General Bots running and have your first conversation.

What You’ll Achieve

By the end of this chapter, you will:

• Have General Bots running on your machine
• Understand what happens during bootstrap
• Complete your first conversation with a bot
• Know how sessions and channels work

Choose Your Path

The 30-Second Version

./botserver

Open http://localhost:9000. Start chatting. That’s it.

Everything installs automatically on first run—PostgreSQL, storage, cache, and your first bot.

How It Works

Topics in This Chapter

Overview

What General Bots does and how it fits together.

Quick Start

The fastest path from zero to running bot.

Installation

Detailed setup options including LXC containers and production deployment.

First Conversation

Understanding how the bot responds and learns.

Sessions and Channels

How conversations are managed across WhatsApp, Web, Telegram, and more.

Coming From Executive Vision?

If you just read the Executive Vision, here’s what to know:

1. Everything in that feature table? It’s all included in the single botserver binary
2. No configuration needed — Bootstrap detects your system and sets everything up
3. Start simple — Run it, chat with it, then customize

The philosophy is: get running first, understand later.

Prerequisites

• Operating System: Linux, macOS, or Windows (WSL2 recommended)
• Disk Space: ~2GB for botserver-stack
• RAM: 4GB minimum, 8GB recommended
• Ports: 8080 (web), 5432 (database), 9000 (storage)

No Docker required. No cloud accounts. No API keys to start.

Next Step

Quick Start →

Overview

botserver is an open-source conversational AI platform built in Rust that enables developers to create, deploy, and manage intelligent bots with minimal configuration. This chapter provides a comprehensive introduction to the platform’s architecture, capabilities, and design philosophy.

Core Philosophy

botserver was designed around five guiding principles that shape every aspect of the platform. Zero Configuration means the system works out of the box with sensible defaults, eliminating lengthy setup processes. The Package-Based approach ensures bots are self-contained in .gbai folders that can be copied and deployed anywhere. BASIC Scripting provides simple, accessible programming for conversation flows that non-programmers can understand and modify. Multi-Channel support means you deploy once and run everywhere across Web, WhatsApp, Teams, and other platforms. Knowledge-First design provides built-in document management and semantic search as core capabilities rather than afterthoughts.

Architecture Overview

botserver uses a modular architecture organized into three distinct layers that work together to provide a complete conversational AI platform.

Storage Layer

The storage layer handles all data persistence needs. The SQL database stores structured data including users, sessions, and configurations using PostgreSQL with the Diesel ORM. Object storage provides S3-compatible file storage for documents and uploads, typically using MinIO for self-hosted deployments. The high-performance cache layer handles sessions and frequently accessed data using a Redis-compatible store. An optional vector database enables semantic search capabilities for knowledge bases using Qdrant or similar vector stores.

Application Layer

The application layer contains the core bot functionality. The Bot Engine processes conversations and manages state across interactions. The BASIC Interpreter executes conversation scripts written in the General Bots dialect of BASIC. The Package Manager handles bot deployment, lifecycle management, and hot-reloading of changes. Channel Adapters connect to various messaging platforms, translating between platform-specific formats and the internal message representation.

Service Layer

The service layer provides the infrastructure that supports bot operations. The UI Server handles HTTP API requests and WebSocket connections for real-time chat interfaces. The Scheduler executes cron-based tasks for automation and maintenance. LLM Integration connects to language models whether hosted locally or in the cloud. Authentication integrates with directory services for user management and access control.

Key Features

Conversation Management

botserver provides comprehensive conversation management capabilities. Sessions persist across interactions, maintaining context and state throughout multi-turn dialogs. The context management system tracks conversation history and user information across interactions. Parallel conversation handling allows a single bot instance to manage thousands of simultaneous conversations efficiently.

Knowledge Base System

The knowledge base system turns your documents into searchable, AI-accessible information. Document ingestion supports PDF, TXT, MD, and DOCX formats with automatic text extraction. The indexing pipeline processes documents into searchable chunks stored in the vector database. Semantic search finds relevant information based on meaning rather than just keyword matching. Context injection automatically provides relevant document excerpts to the LLM when generating responses.

BASIC Scripting Language

The BASIC scripting language makes bot development accessible to everyone. The simple syntax allows non-programmers to read and modify conversation flows. Built-in keywords handle common tasks like sending messages, saving data, and calling APIs. The tool integration system lets you create callable functions that the AI can invoke automatically. Event-driven programming support enables reactive bots that respond to schedules, webhooks, and system events.

Multi-Channel Support

Deploy your bot once and reach users across multiple channels. The web chat interface provides an embeddable widget for websites. WhatsApp Business API integration enables customer service on the world’s most popular messaging platform. Microsoft Teams support brings your bot into enterprise collaboration spaces. Email integration allows conversational interactions through traditional email. SMS support via providers enables text message interactions for users without data connectivity.

Enterprise Features

botserver includes capabilities required for enterprise deployments. Multi-tenancy support allows a single installation to serve multiple organizations with complete isolation. Role-based access control restricts actions based on user roles and permissions. Comprehensive audit logging tracks all actions for compliance and debugging. Horizontal scaling distributes load across multiple instances. High availability configurations ensure continuous operation even during failures.

System Requirements

Minimum Requirements

For development and testing purposes, botserver runs comfortably on modest hardware. You need at least 4GB of RAM to run all components. A single CPU core is sufficient for light workloads. Reserve at least 10GB of disk space for the application, databases, and documents. The platform runs on Linux, macOS, or Windows operating systems.

Recommended for Production

Production deployments benefit from more substantial resources. Plan for 16GB of RAM to handle concurrent users and large knowledge bases. Two or more CPU cores improve response times under load. Use 100GB of SSD storage for better database and file access performance. Linux servers running Ubuntu or Debian provide the most tested and reliable environment. For local LLM hosting, an NVIDIA RTX 3060 or better GPU with at least 12GB of VRAM enables on-premises inference without cloud API dependencies.

Configuration

Bot configuration uses config.csv files with key-value parameters. Server settings like server_host and server_port control where the UI server listens. LLM configuration through llm-url and llm-model specifies which language model to use. Email settings including email-from and email-server enable outbound email functionality. UI customization parameters like theme-color1, theme-color2, theme-title, and theme-logo brand the interface. Conversation settings such as episodic-memory-history and episodic-memory-threshold tune how context is managed. Refer to the config.csv files in bot packages for the complete list of available parameters.

Bot Package Structure

Each bot is a self-contained .gbai folder that includes everything needed for deployment. The structure organizes different aspects of the bot into subfolders with specific naming conventions.

mybot.gbai/
  mybot.gbot/
    config.csv
  mybot.gbdialog/
    start.bas
    tools/
  mybot.gbkb/
    documents/
  mybot.gbtheme/
    styles/

The .gbot subfolder contains configuration files including the main config.csv. The .gbdialog subfolder holds BASIC scripts with start.bas serving as the entry point and additional scripts providing tools. The .gbkb subfolder stores knowledge base documents organized into topical folders. The optional .gbtheme subfolder contains CSS and assets for UI customization.

Deployment Models

Standalone Server

The standalone deployment model runs a single botserver instance serving multiple bots. This approach provides the simplest setup with shared resources across bots. Standalone deployment works best for small to medium deployments where isolation between bots is not critical.

LXC Containers

Linux containers provide lightweight virtualization for bot isolation. Each bot or group of bots runs in its own container with dedicated resources. LXC deployment offers easy management through standard container tooling while maintaining lower overhead than full virtual machines.

Embedded Mode

Embedded deployment integrates botserver into existing applications as a library. This mode provides programmatic control over bot behavior and direct integration with application logic. Custom integrations can use the embedded mode to add conversational capabilities to any Rust application.

Getting Started

Installation begins by downloading and running the botserver binary. The bootstrap process automatically downloads all required components to the botserver-stack/ directory, including database binaries, the object storage server, cache server, LLM runtime, and other dependencies.

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.

Use Cases

Customer Support

Customer support bots automate FAQ responses and ticket handling. Load your support documentation, policies, and procedures into knowledge bases. Create tools for ticket creation and status lookup. The result is 24/7 support that handles common questions automatically while escalating complex issues to human agents.

Internal Tools

Employee assistant bots streamline internal operations. Knowledge bases contain HR policies, IT guides, and company information. Tools enable leave requests, equipment orders, and other common workflows. Employees get instant answers and automated processing for routine requests.

Educational Applications

Educational bots provide interactive learning experiences. Course materials and reference documents become searchable knowledge bases. Tools handle quiz administration, progress tracking, and enrollment. Students receive personalized guidance and immediate feedback.

Healthcare Applications

Healthcare bots assist with patient engagement while maintaining compliance. Appointment scheduling, medication reminders, and symptom checking tools automate routine interactions. Knowledge bases contain patient education materials. All interactions maintain audit trails for regulatory compliance.

Security Features

botserver implements comprehensive security at every layer. Authentication integrates with directory services for centralized user management. SSL/TLS encryption protects all network communications. Session tokens use cryptographically secure generation and validation. Input sanitization prevents injection attacks across all user inputs. SQL injection prevention uses parameterized queries throughout. XSS protection sanitizes output displayed to users. Rate limiting prevents abuse and denial of service attacks. Audit logging records all significant actions for compliance and forensics.

Monitoring and Operations

Health Checks

Health monitoring endpoints report component status for operational awareness. Database connectivity checks verify the storage layer is operational. Storage availability checks ensure object storage is accessible. Cache performance metrics track response times and hit rates.

Metrics

Operational metrics provide visibility into bot performance. Conversation counts show usage patterns over time. Response time measurements identify performance issues. Error rates highlight problems requiring attention. Resource usage tracking helps capacity planning.

Logging

Structured logging facilitates troubleshooting and analysis. Configurable log levels from ERROR through DEBUG control verbosity. Automatic rotation and archival prevent disk exhaustion. Search and filtering tools help locate specific events in large log files.

Extensibility

Channel Adapters

New messaging channels integrate through the adapter system. WebSocket protocols enable real-time bidirectional communication. REST API integration supports request-response style platforms. Custom protocols can be implemented for specialized messaging systems.

Storage Backends

Storage is abstracted to support multiple backend options. S3-compatible storage works with AWS, MinIO, and other providers. Database adapters could support different SQL databases. Cache providers can be swapped while maintaining the same interface.

Community and Support

Documentation

Comprehensive documentation covers all aspects of the platform. The User Guide walks through common tasks and best practices. The API Reference documents all endpoints and parameters. The BASIC Language Reference details every keyword and syntax rule. The Deployment Guide covers production installation and configuration.

Resources

Example bots in the templates/ directory demonstrate common patterns. Test suites verify functionality and provide usage examples. Migration tools help transition from other platforms to General Bots.

Contributing

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:

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.

Quick Start

Installation in 3 Steps

1. Run botserver

./botserver

That’s it! No configuration needed.

2. Wait for Bootstrap (2-5 minutes)

You’ll see:

botserver starting...
Bootstrap: Detecting system...
Installing PostgreSQL...
   Database created
   Schema initialized
Installing Drive...
   Object storage ready
   Buckets created
Installing Cache...
   Cache server running
Creating bots from templates...
   default.gbai deployed
   announcements.gbai deployed
botserver ready at http://localhost:9000

3. Open Browser

http://localhost:9000

Start chatting with your bot!

What Just Happened?

Bootstrap Flow

The automatic bootstrap process:

1. Detected your OS (Linux/macOS/Windows)
2. Downloaded PostgreSQL database to botserver-stack/
3. Downloaded drive (S3-compatible storage) to botserver-stack/
4. Downloaded cache component to botserver-stack/
5. Generated secure credentials
6. Created database schema
7. Deployed default bots to object storage
8. Started UI server on port 8080

Zero manual configuration required!

Using Existing Services

If you already have PostgreSQL or drive storage running, configure them in config.csv of your bot:

name,value
database-url,postgres://myuser:mypass@myhost:5432/mydb
drive-server,http://my-drive:9000
drive-accesskey,my-access-key
drive-secret,my-secret-key

Step 2: Write a Simple Tool

How Tools Work

Tools are just .bas files. Create enrollment.bas:

' Student enrollment tool
PARAM name, email, course
DESCRIPTION "Processes student enrollment"

SAVE "enrollments.csv", name, email, course, NOW()
TALK "Welcome to " + course + ", " + name + "!"

The LLM automatically discovers this tool and knows when to call it!

Step 3: Add Knowledge Base

Drop documents in a .gbkb/ folder:

mybot.gbai/
  mybot.gbkb/
    docs/
      manual.pdf
      faq.docx
      guide.txt

The bot automatically:

• Indexes documents with vector embeddings
• Answers questions from the content
• Updates when files change

Container Deployment (LXC)

For production isolation, botserver supports LXC (Linux Containers):

# Create container
lxc-create -n botserver -t download -- -d ubuntu -r jammy -a amd64

# Start and attach
lxc-start -n botserver
lxc-attach -n botserver

# Install botserver inside container
./botserver

Benefits:

• Process isolation
• Resource control
• Easy management
• Lightweight virtualization

Optional Components

After installation, add more features:

./botserver install email      # Email server
./botserver install directory  # Identity provider
./botserver install llm        # Local LLM server (offline mode)
./botserver install meeting    # Video conferencing

Example Bot Structure

mybot.gbai/
  mybot.gbdialog/          # Dialog scripts
    start.bas            # Entry point (required)
    get-weather.bas      # Tool (auto-discovered)
    send-email.bas       # Tool (auto-discovered)
  mybot.gbkb/              # Knowledge base
    docs/                # Document collection
    faq/                 # FAQ collection
  mybot.gbot/              # Configuration
    config.csv           # Bot parameters
  mybot.gbtheme/           # UI theme (optional)
    custom.css

Deploy new bots by uploading to object storage (creates a new bucket), not the local filesystem. The work/ folder is for internal use only.

Local Development with Auto-Sync

Edit bot files locally and sync automatically to drive storage:

Free S3 Sync Tools:

• Cyberduck - GUI file browser (Windows/Mac/Linux)
• rclone - Command-line sync (All platforms)
• WinSCP - File manager with S3 (Windows)
• S3 Browser - Freeware S3 client (Windows)

Quick Setup with rclone:

# Configure for drive storage
rclone config  # Follow prompts for S3-compatible storage

# Auto-sync local edits to bucket
rclone sync ./mybot.gbai drive:mybot --watch

Now when you:

• Edit .csv → Bot config reloads automatically
• Edit .bas → Scripts compile automatically
• Add docs to .gbkb/ → Knowledge base updates

How It Really Works

You DON’T write complex dialog flows. Instead:

1. Add Documents

mybot.gbkb/
  policies/enrollment-policy.pdf
  catalog/courses.pdf

2. Create Tools (Optional)

' enrollment.bas - just define what it does
PARAM name AS string
PARAM course AS string
SAVE "enrollments.csv", name, course

3. Start Chatting!

User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: John Smith
Bot: [Automatically calls enrollment.bas with collected params]
     Welcome to Computer Science, John Smith!

The LLM handles ALL conversation logic automatically!

Configuration (Optional)

Configure per-bot settings in config.csv:

name,value
server_port,8080
llm-url,http://localhost:8081
episodic-memory-threshold,4
theme-color1,#0d2b55

Troubleshooting

Port 8080 in use?

Edit templates/default.gbai/default.gbot/config.csv:

name,value
server_port,3000

Clean install?

# Remove everything and start fresh
rm -rf botserver-stack/
rm .env
./botserver  # Will regenerate everything

Check component status

./botserver status tables    # PostgreSQL
./botserver status drive     # Drive storage
./botserver status cache     # Cache component

Documentation

• Full Installation Guide - Detailed bootstrap explanation
• Tool Definition - Creating tools
• BASIC Keywords - Language reference
• Package System - Creating bots
• Architecture - How it works

The Magic Formula

Documents + Tools + LLM = Intelligent Bot

What You DON’T Need:

• IF/THEN logic
• Intent detection
• Dialog flow charts
• State machines
• Complex routing

What You DO:

• Drop documents in .gbkb/
• Create simple .bas tools (optional)
• Start chatting!

The LLM understands context, calls tools, searches documents, and maintains conversation naturally.

Philosophy

1. Just Run It - No manual configuration
2. Simple Scripts - BASIC-like language anyone can learn
3. Automatic Discovery - Tools and KBs auto-detected
4. Secure by Default - Credentials auto-generated
5. Production Ready - Built for real-world use

Real Example: Education Bot

1. Add course materials:

   edu.gbkb/
     courses/computer-science.pdf
     policies/enrollment.pdf
   

2. Create enrollment tool:

   ' enrollment.bas
   PARAM name AS string
   PARAM course AS string
   SAVE "enrollments.csv", name, course
   

3. Just chat:

   User: What courses do you offer?
   Bot: [Searches PDFs] We offer Computer Science, Data Science...
   
   User: I want to enroll
   Bot: [Calls enrollment.bas] Let me help you enroll...
   

No programming logic needed - the LLM handles everything!

Installation

botserver installs itself automatically through the bootstrap process. Just run the binary.

Runtime Dependencies

Before running the botserver binary, you must install required system libraries on the host system.

Quick Install (Recommended)

Download and run the dependency installer:

curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash

Or if you have the script locally:

sudo ./scripts/install-dependencies.sh

Manual Install (Debian/Ubuntu)

sudo apt update
sudo apt install -y \
    libpq5 \
    libssl3 \
    liblzma5 \
    zlib1g \
    ca-certificates \
    curl \
    wget \
    libabseil-dev \
    libclang-dev \
    pkg-config

# For container support (LXC)
sudo snap install lxd
sudo lxd init --auto

Manual Install (Fedora/RHEL)

sudo dnf install -y \
    libpq \
    openssl-libs \
    xz-libs \
    zlib \
    ca-certificates \
    curl \
    wget \
    lxc

⚠️ Common Error: If you see error while loading shared libraries: libpq.so.5, install libpq5 (Debian/Ubuntu) or libpq (Fedora/RHEL).

System Requirements

Quick Start

./botserver

The bootstrap process automatically:

1. Detects your system (OS/architecture)
2. Creates botserver-stack/ directory structure
3. Downloads PostgreSQL, Drive, Cache, LLM server
4. Initializes database and storage
5. Deploys default bot
6. Starts all services

First run takes 2-5 minutes.

Using Existing Services

If you have existing infrastructure, configure it in your bot’s config.csv:

name,value
database-url,postgres://myuser:mypass@myhost:5432/mydb
drive-server,http://my-drive:9000
drive-accesskey,my-access-key
drive-secret,my-secret-key

Default Ports

Verify Installation

# Check services
./botserver status

# Test database
psql $DATABASE_URL -c "SELECT version();"

# Test LLM
curl http://localhost:8081/v1/models

# Open UI
open http://localhost:9000

Bot Deployment

Bots deploy to object storage (not local filesystem):

mybot.gbai → creates 'mybot' bucket in drive

The work/ folder is for internal use only.

S3 Sync for Development

Use S3-compatible tools for local editing:

• Cyberduck (GUI)
• rclone (CLI)
• WinSCP (Windows)

# rclone sync example
rclone sync ./mybot.gbai drive:mybot --watch

Edits sync automatically - changes reload without restart.

Memory Optimization

For limited RAM systems:

name,value
llm-server-ctx-size,2048
llm-server-parallel,2

Use quantized models (Q3_K_M, Q4_K_M) for smaller memory footprint.

GPU Setup

For GPU acceleration:

name,value
llm-server-gpu-layers,35

Requires CUDA installed and 12GB+ VRAM.

Deployment Options

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:

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.

⚠️ IMPORTANT: Container create commands (botserver install ... --container) must be run from the host system, not inside a container.

Example: Create Vault and VectorDB

# Run on HOST system
botserver install vault --container --tenant mycompany
botserver install vector_db --container --tenant mycompany

# Verify containers
lxc list | grep mycompany

Troubleshooting

Next Steps

• Quick Start Guide - Create your first bot
• First Conversation - Test your bot
• Configuration Reference - All settings

Configuring Local Development Access

After bootstrap, botserver services are immediately accessible via IP addresses - no configuration required. For those who prefer friendly hostnames, optional DNS setup is also available.

Zero Configuration: IP Access (Default)

botserver certificates include 127.0.0.1 as a Subject Alternative Name (SAN), so mTLS works immediately via IP address without any system changes.

Service Ports

Quick Test

# Test API (no config needed)
curl -k https://127.0.0.1:8443/health

# With mTLS client certificate
curl --cert ./botserver-stack/conf/system/certificates/api/client.crt \
     --key ./botserver-stack/conf/system/certificates/api/client.key \
     --cacert ./botserver-stack/conf/system/certificates/ca/ca.crt \
     https://127.0.0.1:8443/api/v1/status

Code Examples

Python

import requests

response = requests.get(
    "https://127.0.0.1:8443/api/v1/bots",
    cert=("./botserver-stack/conf/system/certificates/api/client.crt",
          "./botserver-stack/conf/system/certificates/api/client.key"),
    verify="./botserver-stack/conf/system/certificates/ca/ca.crt"
)
print(response.json())

Node.js

const https = require('https');
const fs = require('fs');

const options = {
  hostname: '127.0.0.1',
  port: 8443,
  path: '/api/v1/bots',
  method: 'GET',
  cert: fs.readFileSync('./botserver-stack/conf/system/certificates/api/client.crt'),
  key: fs.readFileSync('./botserver-stack/conf/system/certificates/api/client.key'),
  ca: fs.readFileSync('./botserver-stack/conf/system/certificates/ca/ca.crt')
};

https.request(options, (res) => {
  res.on('data', (d) => process.stdout.write(d));
}).end();

Rust

use reqwest::Certificate;
use std::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cert = fs::read("./botserver-stack/conf/system/certificates/api/client.crt")?;
    let key = fs::read("./botserver-stack/conf/system/certificates/api/client.key")?;
    let ca = fs::read("./botserver-stack/conf/system/certificates/ca/ca.crt")?;
    
    let identity = reqwest::Identity::from_pem(&[cert, key].concat())?;
    let ca_cert = Certificate::from_pem(&ca)?;
    
    let client = reqwest::Client::builder()
        .identity(identity)
        .add_root_certificate(ca_cert)
        .build()?;
    
    let response = client
        .get("https://127.0.0.1:8443/api/v1/bots")
        .send()
        .await?;
    
    println!("{}", response.text().await?);
    Ok(())
}

Remote Server Access

If botserver runs on a different machine (e.g., 192.168.1.100), regenerate certificates with additional IP SANs:

./botserver regenerate-certs --san-ip 192.168.1.100 --san-ip 10.0.0.50

Or configure before bootstrap in botserver-stack/conf/system/ca-config.toml:

[certificates.api]
san_names = ["localhost", "api.botserver.local", "127.0.0.1", "192.168.1.100"]

Optional: Hostname Access

For browser access with friendly URLs, configure your system to resolve *.botserver.local hostnames.

Hostname Mapping

Option 1: Edit hosts file (Simplest)

Windows

Open Notepad as Administrator, edit C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local

PowerShell one-liner (run as Administrator):

@"
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
"@ | Add-Content C:\Windows\System32\drivers\etc\hosts

Linux

sudo tee -a /etc/hosts << 'EOF'
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
EOF

macOS

sudo tee -a /etc/hosts << 'EOF'
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
EOF

# Flush DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Option 2: Use botserver’s CoreDNS

botserver runs CoreDNS on port 53. Point your system to use it as DNS server.

Windows

# Get active interface
$interface = (Get-NetAdapter | Where-Object {$_.Status -eq "Up"}).Name

# Set DNS servers
Set-DnsClientServerAddress -InterfaceAlias $interface -ServerAddresses ("127.0.0.1","8.8.8.8")

Linux (systemd-resolved)

sudo mkdir -p /etc/systemd/resolved.conf.d/
sudo tee /etc/systemd/resolved.conf.d/botserver.conf << 'EOF'
[Resolve]
DNS=127.0.0.1
FallbackDNS=8.8.8.8 8.8.4.4
Domains=~botserver.local
EOF
sudo systemctl restart systemd-resolved

macOS

sudo mkdir -p /etc/resolver
sudo tee /etc/resolver/botserver.local << 'EOF'
nameserver 127.0.0.1
EOF

This routes only *.botserver.local queries to botserver’s DNS.

Trusting Self-Signed Certificates

For browser access without warnings, trust the CA certificate:

Windows

Import-Certificate -FilePath ".\botserver-stack\conf\system\certificates\ca\ca.crt" -CertStoreLocation Cert:\LocalMachine\Root

Linux

# Ubuntu/Debian
sudo cp ./botserver-stack/conf/system/certificates/ca/ca.crt /usr/local/share/ca-certificates/botserver-ca.crt
sudo update-ca-certificates

# Fedora/RHEL
sudo cp ./botserver-stack/conf/system/certificates/ca/ca.crt /etc/pki/ca-trust/source/anchors/botserver-ca.crt
sudo update-ca-trust

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./botserver-stack/conf/system/certificates/ca/ca.crt

Firefox

Firefox uses its own certificate store:

1. Settings → Privacy & Security → View Certificates
2. Authorities → Import
3. Select botserver-stack/conf/system/certificates/ca/ca.crt
4. Check “Trust this CA to identify websites”

Troubleshooting

DNS Not Resolving

# Check CoreDNS is running
./botserver status dns

# Test DNS directly
dig @127.0.0.1 api.botserver.local

macOS .local Conflicts

macOS reserves .local for Bonjour. Use the /etc/resolver/ method which doesn’t conflict.

Reverting Changes

# Remove hosts entries (Linux/macOS)
sudo sed -i '/botserver\.local/d' /etc/hosts

# Remove macOS resolver
sudo rm /etc/resolver/botserver.local

# Reset DNS (Linux)
sudo rm /etc/systemd/resolved.conf.d/botserver.conf
sudo systemctl restart systemd-resolved

# Reset DNS (Windows)
Set-DnsClientServerAddress -InterfaceAlias $interface -ResetServerAddresses

Summary

Default recommendation: Use IP addresses for development. No configuration needed.

First Conversation

After botserver starts, you can immediately start chatting with your bot. No programming required!

Just Start Talking

Open your browser to http://localhost:9000 and start chatting:

You: Hi!
Bot: Hello! How can I help you today?

You: I want to enroll in a course
Bot: I'll help you with enrollment. Let me collect your information...
     [Bot automatically calls enrollment.bas tool]

You: What documents do you have?
Bot: [Searches .gbkb/ folders and answers from your documents]

That’s it! The LLM handles everything automatically.

How It Works

Drop Documents in .gbkb/

mybot.gbai/
  mybot.gbkb/
    policies/
      enrollment-policy.pdf
      course-catalog.pdf
    faqs/
      student-faq.docx
      payment-guide.txt

The bot automatically indexes all documents, creates vector embeddings, searches when users ask questions, and provides accurate answers from your content.

Create Tools as .bas Files

Create enrollment.bas:

PARAM name AS string          LIKE "John Smith"           DESCRIPTION "Student full name"
PARAM email AS string         LIKE "john@example.com"     DESCRIPTION "Contact email"
PARAM course AS string        LIKE "Computer Science"     DESCRIPTION "Course to enroll in"

DESCRIPTION "Enrollment tool - collects student information and processes enrollment"

SAVE "enrollments.csv", name, email, course, NOW()
TALK "Enrollment complete! Welcome to " + course + ", " + name

The LLM automatically discovers this tool, knows when to call it based on user intent, collects required parameters through natural conversation, and executes the tool when all information is gathered.

The LLM Does Everything Else

You don’t need to write IF/THEN logic, intent detection, dialog flows, state machines, or complex routing. The LLM automatically understands user intent, calls appropriate tools, searches knowledge bases, maintains conversation context, and handles follow-up questions naturally.

Real Example Conversation

With enrollment.bas tool and course documents in .gbkb/:

User: Hello, I'd like to know about your computer science program

Bot: I'd be happy to help you learn about our Computer Science program! 
     Based on our course catalog, the program offers a comprehensive 
     4-year curriculum covering software development, algorithms, 
     databases, and AI. Would you like to know about specific courses 
     or the enrollment process?

User: Yes, I want to enroll

Bot: Great! I'll help you enroll in the Computer Science program. 
     Let me collect your information. What's your full name?

User: John Smith

Bot: Thank you, John. What email address should we use for contact?

User: john.smith@gmail.com

Bot: Perfect! I'm enrolling you in Computer Science now...
     [Executes enrollment.bas tool]
     Enrollment complete! Welcome to Computer Science, John Smith!
     You'll receive a confirmation at john.smith@gmail.com.

User: What are the payment options?

Bot: [Searches payment-guide.txt from .gbkb/]
     According to our payment guide, we offer three options:
     1. Full payment with 10% discount
     2. Monthly installments over 12 months
     3. Semester-based payments
     Which option would you prefer?

The Magic Formula

Documents in .gbkb/ combined with tools in .bas files and the LLM create an intelligent bot. No complex programming needed!

Creating Your First Bot

Start by creating the directory structure for your bot with folders for dialog scripts, knowledge base documents, and bot configuration. Add your documents to the .gbkb/ directory including PDFs, Word documents, text files, and Markdown files. Optionally create tools as .bas files to handle specific actions like processing forms or calling APIs. Then restart botserver and start chatting. The LLM will answer questions from your documents, call your tools when appropriate, and handle the entire conversation naturally.

mkdir -p mybot.gbai/mybot.gbdialog
mkdir -p mybot.gbai/mybot.gbkb/docs
mkdir -p mybot.gbai/mybot.gbot

Example tool in mybot.gbdialog/my-tool.bas:

PARAM user_name AS string
PARAM request AS string

DESCRIPTION "Handles user requests"

result = CALL "/api/process", user_name, request
TALK "Done! " + result

No Programming Required

Traditional chatbots require complex logic with IF/THEN statements, intent detection, and multi-step dialog management. With botserver, you simply create the tool with parameters and a description, and the LLM handles all the conversation logic automatically.

Traditional approach (don’t do this):

' Complex multi-step dialog
IF intent = "enrollment" THEN
    TALK "Let me help you enroll. What's your name?"
    HEAR name
    TALK "What's your email?"
    HEAR email
    ' ... lots more code ...
ENDIF

botserver approach (just create the tool):

' In enrollment.bas - becomes a tool automatically
PARAM name AS string
PARAM email AS string
DESCRIPTION "Collects enrollment information"

SAVE "enrollments.csv", name, email
TALK "Successfully enrolled " + name

What Can You Build?

A customer support bot uses product manuals in .gbkb/ and a create-ticket.bas tool, allowing the LLM to answer questions and create support tickets automatically.

An HR assistant combines the employee handbook in .gbkb/ with a leave-request.bas tool so the LLM can explain policies and process leave requests.

An education platform stores course materials in .gbkb/ and provides enrollment.bas and submit-assignment.bas tools, enabling the LLM to teach content and manage student tasks.

A sales assistant uses product catalogs in .gbkb/ with a create-quote.bas tool, allowing the LLM to answer product questions and generate quotes.

Advanced Features

Dynamic Tool Loading

The LLM can load tools based on context. In start.bas, you simply specify which knowledge bases to use, and tools in .gbdialog/ are auto-discovered. The LLM handles the conversation naturally without explicit HEAR statements.

Multi-Language Support

The LLM handles multiple languages automatically. Users can write in Portuguese, Chinese, or any other language, and the bot responds appropriately in the same language.

Context Awareness

The LLM maintains conversation context throughout the interaction. If a user starts to enroll but then asks about prerequisites, the bot handles the tangent and can return to the enrollment process afterward.

Tips for Success

Organize documents clearly by creating folders for policies, products, FAQs, and tutorials within your .gbkb/ directory. This helps the LLM find relevant information quickly.

Name tools descriptively with names like enrollment.bas, create-ticket.bas, and schedule-meeting.bas. The LLM understands what each tool does from its name and description.

Always add descriptions to tools using the DESCRIPTION keyword. A good description like “This tool processes student enrollment for courses” helps the LLM know when to use the tool.

Let the LLM work without trying to control every aspect of the conversation. Allow it to rephrase responses naturally, handle unexpected questions, and maintain conversation flow on its own.

Next Steps

The Quick Start guide walks you through building your first bot. The Packages chapter explains the package structure in detail. The Tool Definition documentation covers creating sophisticated tools. The Knowledge Base chapter describes document management and indexing.

Remember: Just add documents and tools, and the LLM does the rest!

Sessions and Channels

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.

What Is a Session?

A session is a persistent conversation container that tracks everything about an ongoing interaction. This includes who is talking through user identity, what has been said through message history, the current state including variables and context, any active tools and knowledge bases, and the bot configuration in use. Think of it like a phone call that can pause and resume anytime without losing the thread of conversation.

How Sessions Start

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.

API Access

Programmatic access to sessions uses the REST API. A POST request to /api/session returns a session ID and secret token. Subsequent requests include the token in the Authorization header as a Bearer token to maintain the session context.

# Get new session
curl -X POST http://localhost:9000/api/session
# Returns: {"session_id": "uuid-here", "token": "secret-token"}

# Use session
curl -H "Authorization: Bearer secret-token" \
     http://localhost:9000/api/chat

Anonymous vs Authenticated

Sessions come in two flavors depending on user identity. Anonymous sessions are auto-created with temporary identities for users who have not logged in. Authenticated sessions link to a user account and maintain permanent history that persists indefinitely.

Session Lifecycle

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.

What Gets Stored

PostgreSQL (Permanent Storage)

The database stores the authoritative session record. The sessions table tracks the unique ID, optional user reference, which bot is being used, creation timestamp, and last activity time. The messages table stores each message with its session reference, role (user, assistant, or system), content, and timestamp. The session_state table holds variables as JSONB data and tracks the current knowledge base and tool context.

Cache (Fast Access)

The cache layer provides rapid access to active session data. Recent messages, current variables, active knowledge bases and tools, and last activity timestamps are all cached under keys prefixed with the session UUID. This caching ensures responsive conversations without constant database queries.

Session Variables

Variables set in BASIC scripts persist across messages automatically. When you store a variable in one message, you can retrieve it in a later message whether that is minutes or days later.

' First message
name = HEAR
SET user_name = name

' Later message (minutes or days later)
GET user_name
TALK "Welcome back, " + user_name

Storage happens automatically through several layers. Writes go to cache immediately for fast access. Every message triggers persistence to PostgreSQL for durability. If the cache misses, data restores automatically from the database.

Context Management

Each session maintains its own isolated context. When one session loads a knowledge base, other sessions remain unaffected. This isolation ensures users see only the information relevant to their conversation.

' Session A
USE KB "policies"
' Only this session sees policies

' Session B (different user)
USE KB "products"  
' This session only sees products

Session contexts include active knowledge bases, loaded tools, LLM configuration overrides, and custom prompts. All of these are scoped to the individual session and do not leak between users.

Multi-Bot Sessions

Different bots create entirely separate sessions. A user visiting /default gets one session connected to the default bot, while visiting /support creates a different session for the support bot. Each bot session is completely independent with its own conversation history, knowledge bases, configuration, and no data sharing between them.

Session Security

Token Generation

Session tokens use cryptographically secure random generation with 256-bit entropy. Tokens are encoded in URL-safe base64 format and are unique per session. This makes tokens effectively impossible to guess or predict.

Token Validation

Every request undergoes validation to ensure security. The system verifies that the token exists, has not expired, matches the claimed session, and that the session is still active. Any failure in this chain rejects the request.

Security Features

Multiple security measures protect sessions. Unguessable tokens prevent session hijacking. New tokens for each session prevent session fixation attacks. Automatic cleanup removes old sessions to prevent accumulation. Rate limiting per session prevents abuse.

Debugging Sessions

View Current Session

Within a BASIC script, you can access session information directly.

session_id = GET "session.id"
TALK "Session: " + session_id

Database Inspection

Direct database queries help debug session issues. You can find all active sessions by querying for recent activity, or view message history for a specific session ordered by timestamp.

Cache Inspection

The cache contents can be examined using the valkey-cli tool. List all session keys or retrieve specific session data like variables or context directly from the cache.

Session Limits

Default limits control resource usage, though all are configurable. Message history keeps the last 50 messages in context. Variable storage allows up to 1MB per session. File uploads accept up to 10MB per file. Each server handles up to 1000 concurrent sessions. Rate limiting restricts each session to 60 messages per minute.

Advanced Features

Session Persistence

Sessions persist across server restarts through the cache and database layers. When users reconnect after a restart, their session state restores automatically. This happens transparently without any action required from users or bot developers.

Session Context Isolation

Each session maintains its own context for knowledge base and tool usage. When you load a knowledge base or enable a tool, the change affects only the current session. Other users in other sessions remain unaffected by your context changes.

' Each session has isolated context
USE KB "docs"
' Only affects current session

How It Works Automatically

Sessions require zero configuration from bot developers. Creation happens automatically on the first request from any client. Storage to database and cache happens automatically as conversations progress. Cleanup runs automatically after sessions expire. Security through token generation happens automatically without any setup. Multi-channel support through automatic adapter selection means the same session infrastructure works across all platforms.

You never need to manage sessions directly. Just use the conversation keywords like TALK, HEAR, SET, and GET. Everything else happens behind the scenes.

Common Patterns

Welcome Back

Personalize greetings by remembering when users last visited. Store the last visit timestamp and check for it on subsequent sessions to customize the welcome message.

last_visit = GET BOT MEMORY "last_visit_" + session_id
IF last_visit THEN
  TALK "Welcome back! Last seen: " + last_visit
ELSE
  TALK "Welcome! First time here?"
END IF
SET BOT MEMORY "last_visit_" + session_id, NOW()

Progressive Disclosure

Reveal more features as users become more engaged by tracking message count and adjusting guidance accordingly.

msg_count = GET "session.message_count"
IF msg_count < 3 THEN
  TALK "I can help with basic questions"
ELSE IF msg_count < 10 THEN
  TALK "Try our advanced features!"
ELSE
  TALK "You're a power user! Check tools menu"
END IF

Multi-User Support

Each user automatically receives their own isolated session. The system handles user separation without any explicit code required. Simply write your dialog logic and trust that each user’s data remains private to their session.

Troubleshooting

If sessions are not persisting, check that PostgreSQL is running and accessible. Verify that the cache server is reachable. Look for disk space issues that might prevent database writes.

If sessions expire too soon, adjust the timeout setting in config.csv. Check that server clocks are synchronized. Monitor for memory pressure that might cause early cache eviction.

If you cannot resume a session, the token might have become invalid through expiration or corruption. The session could have passed its expiration window. Database connection issues can also prevent session restoration.

Write Once, Run Everywhere

The same BASIC script runs across all channels including the UI interface, mobile apps, WhatsApp, Microsoft Teams, email conversations, and voice assistants. Your investment in dialog development pays off everywhere because each channel adapter handles the platform specifics while you focus on conversation logic.

' This same script works everywhere

TALK "Hello! How can I help?"
answer = HEAR
TALK "I understand you need help with: " + answer

Summary

Sessions and channels work together seamlessly in botserver. Sessions handle state management automatically across any channel, persist data reliably through cache and database layers, and scale efficiently to thousands of concurrent conversations. You focus on writing the conversation flow while the system handles memory management and multi-channel delivery transparently.

Chapter 2: Architecture & Packages

Architecture and deployment reference for developers.

Overview

botserver is built in Rust with a modular architecture. Extend it by creating custom keywords, services, or entire applications.

Architecture

┌─────────────────────────────────────────┐
│              Web Server (Axum)          │
├─────────────────────────────────────────┤
│         BASIC Runtime (Rhai)            │
├──────────┬──────────┬──────────┬────────┤
│   LLM    │ Storage  │  Vector  │ Cache  │
│ Service  │ (MinIO)  │ (Qdrant) │(Valkey)│
├──────────┴──────────┴──────────┴────────┤
│            PostgreSQL                   │
└─────────────────────────────────────────┘

Deployment Options

Module Structure

Creating Custom Keywords

#![allow(unused)]
fn main() {
// In src/basic/keywords/my_keyword.rs
pub fn my_keyword(context: &mut EvalContext) -> Result<Dynamic, Box<EvalError>> {
    // Your keyword logic
    Ok(Dynamic::from("result"))
}
}

Register in keywords/mod.rs and rebuild.

Autonomous Task AI

General Bots enables autonomous task execution where the machine does the work:

Human describes intent → AI plans → AI generates → AI deploys → AI monitors

Key concepts:

• Intent Compilation - LLM translates natural language to execution plans
• CREATE SITE - Generates HTMX apps bound to botserver API
• .gbdrive - Cloud-synced workspace for all task files
• Autonomous Execution - System runs plans with approval gates

See Autonomous Task AI for complete documentation.

Chapter Contents

• Architecture Overview - System design
• Building from Source - Compilation guide
• Container Deployment (LXC) - Linux containers
• Docker Deployment - Docker setup
• Scaling - Load balancing
• Infrastructure - Hardware planning
• Observability - Monitoring
• Autonomous Task AI - Machine does the work
• Custom Keywords - Extending BASIC
• Services - Service layer

See Also

• Installation - Getting started
• BASIC Reference - Scripting language

Architecture Overview

botserver follows a modular architecture designed for scalability, maintainability, and extensibility. Each module handles specific responsibilities and communicates through well-defined interfaces. This chapter provides a comprehensive tour of the system architecture and how components work together.

Core Architecture

The architecture diagrams below illustrate the major components and their relationships.

Data Flow Architecture

System Architecture

Module Dependency Graph

Module Organization

The codebase is organized into modules that group related functionality together. Each module has clear responsibilities and well-defined interfaces with other modules.

Data Flow Through Modules

Core Modules

The auth/ module handles authentication and authorization throughout the system. It manages user accounts and group memberships, implements role-based access control (RBAC), handles JWT token generation and validation, provides OAuth integration for external identity providers, and supports two-factor authentication for enhanced security.

The automation/ module provides the workflow automation engine. It handles process automation for complex multi-step operations, manages scheduled tasks that run at specified intervals, enables event-driven automation that responds to system events, orchestrates workflows across multiple services, and integrates with external systems for extended capabilities.

The basic/ module implements the BASIC dialect interpreter and runtime environment. It provides keyword implementations for all BASIC commands, handles script compilation from source to executable form, manages variables and their scopes, implements flow control structures like loops and conditionals, integrates with external tools the LLM can invoke, and provides comprehensive error handling with helpful messages.

The bootstrap/ module handles system initialization and startup procedures. It verifies all required components are available, sequences service startup in the correct order, runs database migrations to update schema, deploys default templates for new installations, performs health checks to ensure system readiness, and loads configuration from files and environment variables.

The bot/ module manages bot instances and their interactions. It handles the bot lifecycle including creation, mounting, and unmounting. It processes conversations between users and bots, handles user input and routes it appropriately, coordinates response generation from various sources, manages multi-bot deployments on a single server, and ensures session isolation between different users and bots.

Communication Modules

The channels/ module provides multi-channel messaging adapters that allow bots to communicate across different platforms. Supported channels include the web interface for browser-based chat, WhatsApp Business API for messaging app integration, Microsoft Teams for enterprise collaboration, Slack for team communication, Instagram for social media engagement, SMS for text messaging, and voice for telephone interactions.

The meet/ module enables real-time communication features. It provides video conferencing capabilities for face-to-face meetings, voice calling for audio-only communication, screen sharing for presentations and collaboration, recording functionality for meeting archives, transcription services for accessibility, and meeting scheduling integration with calendars.

The web_server/ module implements the HTTP server and web interface. It serves static files for the UI, handles WebSocket connections for real-time chat, routes REST API requests to appropriate handlers, manages CORS policies for browser security, and processes requests and responses throughout the system.

AI and Knowledge Modules

The llm/ module provides large language model integration. It handles model selection based on configuration and requirements, formats prompts according to model expectations, manages token counting and context limits, streams responses for real-time display, tracks API costs for budgeting, and implements model fallbacks when primary providers are unavailable.

The llm_models/ module contains specific implementations for different model providers. OpenAI integration supports GPT-5 and o3 models. Anthropic integration provides access to Claude Sonnet 4.5 and Opus 4.5 models. Google integration enables Gemini model usage. Meta integration supports Llama models for local deployment. Local model support allows self-hosted inference. Custom model implementations can be added for specialized providers.

The prompt_manager/ module provides centralized prompt management capabilities. It maintains prompt templates for consistent interactions, handles variable substitution in prompts, optimizes prompts for specific models, supports version control of prompt changes, enables A/B testing of different approaches, and tracks prompt performance metrics.

The context/ module manages conversation context throughout interactions. It optimizes the context window to fit within model limits, manages conversation history retention, compresses context when necessary to preserve information, filters context for relevance to current queries, and tracks multi-turn conversations across messages.

Storage and Data Modules

The drive/ module handles file and document management. It supports file upload and download operations, processes documents for indexing and search, maintains version control of files, manages sharing permissions between users, enforces quota limits on storage usage, and indexes content for search functionality.

The drive_monitor/ module provides storage monitoring and synchronization. It detects changes to files for automatic processing, synchronizes content across storage locations, resolves conflicts when multiple changes occur, manages backups of important data, and provides analytics on storage usage patterns.

The package_manager/ module handles bot package management. It loads packages from storage into the runtime, resolves dependencies between packages, manages package versions and updates, supports hot reload of changed packages without restart, and validates packages before deployment.

Processing Modules

The engines/ module contains various processing engines for different tasks. The rule engine evaluates business rules and conditions. The workflow engine orchestrates complex processes. The event processor handles system and external events. The message queue manages asynchronous communication. The job scheduler executes background tasks.

The calendar_engine/ module provides calendar and scheduling functionality. It manages events and appointments, checks availability for scheduling, coordinates meetings between participants, sends reminders for upcoming events, and handles timezone conversions correctly.

The task_engine/ module implements the task management system. It creates tasks from user requests or automation, assigns tasks to appropriate parties, tracks task status through completion, manages dependencies between tasks, and sends notifications about task updates.

The email/ module provides email integration capabilities. It sends email via SMTP protocols, receives email via IMAP connections, manages email templates for consistent formatting, tracks email delivery and opens, and handles bounced emails appropriately.

Utility Modules

The session/ module manages user sessions throughout their interactions. It creates sessions for new users, persists session state to storage, enforces session timeouts for security, handles concurrent sessions from the same user, and recovers sessions after server restarts.

The config/ module handles configuration management. It loads configuration from files and databases, reads environment variables for deployment settings, supports hot reload of configuration changes, validates configuration values, and provides sensible defaults for optional settings.

The shared/ module contains shared utilities and models used across the system. It defines database models for persistence, provides common types used throughout the codebase, implements helper functions for repeated tasks, centralizes constants and magic values, and defines error types for consistent error handling.

The compliance/ module implements regulatory compliance features. It ensures GDPR compliance for data protection, enforces data retention policies, maintains comprehensive audit logging, provides privacy controls for sensitive data, and manages user consent records.

The nvidia/ module provides GPU acceleration support for local model inference. It integrates with CUDA for GPU computation, runs model inference on GPU hardware, batches requests for efficient processing, and optimizes performance for available hardware.

The ui_tree/ module manages UI component trees for the interface. It maintains a virtual DOM for efficient updates, manages component lifecycles, handles state across components, processes events from user interactions, and optimizes rendering performance.

The web_automation/ module provides web scraping and automation capabilities. It automates browser interactions for data gathering, extracts content from web pages, fills forms programmatically, captures screenshots for documentation, and monitors pages for changes.

Data Flow

Request Processing Pipeline

When a user sends a message, it flows through several processing stages. First, the Channel Adapter receives the user input from the appropriate platform. The Session Manager then identifies the existing session or creates a new one. The Context Manager loads conversation history and relevant context. The BASIC Interpreter executes the dialog script that handles the message. If needed, LLM Integration processes natural language to understand intent. The Knowledge Base provides relevant information from loaded documents. The Response Generator formats the output for the user. Finally, the Channel Adapter delivers the response back through the original platform.

Storage Architecture

The primary database uses PostgreSQL to store structured data including user accounts, bot configurations, session data, conversation history, and system metadata. The Diesel ORM provides type-safe database access.

Object storage using Drive provides S3-compatible storage for files including user uploads, processed documents, media files, system backups, and application logs.

The cache layer provides fast access to frequently needed data. It stores session information for quick retrieval, caches commonly accessed data, implements rate limiting counters, holds temporary processing data, and supports pub/sub messaging between components.

The vector database uses Qdrant to store document embeddings for semantic search. It maintains the semantic search index, stores knowledge base vectors, and performs similarity matching for relevant content retrieval.

Security Architecture

Authentication Flow

The authentication process follows a secure sequence. Users provide credentials through the login interface. The auth module validates credentials against stored records. Upon successful validation, a JWT token is issued. Each subsequent request includes this token for verification. A session is established to maintain state. Permissions are checked before any operation is performed.

Data Protection

Data protection operates at multiple layers. Encryption at rest protects data stored in the database and files. Encryption in transit using TLS/SSL protects data during transmission. Sensitive data masking prevents exposure in logs and displays. PII detection identifies and protects personal information. Secure key management protects cryptographic keys from exposure.

Access Control

Access control mechanisms ensure appropriate authorization. Role-based permissions determine what actions users can perform. Resource-level authorization controls access to specific objects. API rate limiting prevents abuse and ensures fair usage. IP allowlisting restricts access to known addresses when configured. Comprehensive audit logging records all significant actions.

Deployment Architecture

Container Structure

Production deployments typically use containers for isolation and portability. The main application container runs the botserver binary. PostgreSQL runs in a separate database container. Drive storage uses an S3-compatible container like MinIO. The cache layer uses Valkey in its own container. Qdrant provides vector database functionality in another container. Nginx serves as a reverse proxy for external traffic.

Scaling Strategy

The system scales to handle increased load through several mechanisms. Horizontal scaling adds more web server instances behind a load balancer. Read replicas for the database handle query load. Distributed cache spreads session data across nodes. Load balancing distributes requests across available instances. Auto-scaling policies adjust capacity based on demand.

High Availability

High availability configurations ensure continuous operation. Multi-zone deployment protects against facility failures. Database replication maintains copies of data. Storage redundancy prevents data loss. Health monitoring detects problems quickly. Automatic failover redirects traffic when components fail.

Performance Optimization

Caching Strategy

Caching improves response times throughout the system. Response caching stores generated responses for reuse. Query result caching avoids repeated database queries. Static asset caching serves files directly from cache. API response caching stores external API results. Knowledge base caching keeps frequently accessed content in memory.

Async Processing

Asynchronous processing improves throughput and responsiveness. Background jobs handle long-running tasks without blocking. Message queues decouple producers from consumers. Event-driven architecture responds to changes efficiently. Non-blocking I/O maximizes resource utilization. Worker pools distribute processing across threads.

Resource Management

Careful resource management ensures efficient operation. Connection pooling reuses database connections. Memory management prevents leaks and excessive usage. Token optimization minimizes LLM API costs. Query optimization reduces database load. Lazy loading defers work until necessary.

Monitoring and Observability

Metrics Collection

Comprehensive metrics provide visibility into system behavior. System metrics track CPU, memory, and disk usage. Application metrics measure request rates and latencies. Business metrics track user engagement and outcomes. User analytics show usage patterns. Performance tracking identifies bottlenecks.

Logging

Structured logging supports debugging and analysis. All logs use consistent structured formats. Log aggregation collects logs from all components. Error tracking captures and groups exceptions. Audit trails record security-relevant events. Debug logging provides detailed information when needed.

Health Checks

Health checks ensure system availability and readiness. Liveness probes confirm the application is running. Readiness probes verify the application can serve requests. Dependency checks validate external services are available. Performance monitoring tracks response times. The alert system notifies operators of problems.

Extension Points

Plugin System

The system provides extension points for customization. Custom keywords extend the BASIC language with new capabilities. External tools integrate third-party services. API integrations connect to external systems. Custom channels add support for new platforms. Model providers integrate additional LLM services.

Webhook Support

Webhooks enable event-driven integrations. Incoming webhooks accept notifications from external systems. Outgoing webhooks notify external systems of events. Event subscriptions define what events trigger webhooks. Callback handling processes webhook responses. Retry mechanisms ensure delivery despite transient failures.

API Integration

Multiple API protocols support different integration needs. The REST API provides standard HTTP access. GraphQL support is planned for flexible queries. WebSocket connections enable real-time bidirectional communication. gRPC support is planned for high-performance integrations. OpenAPI specifications document all endpoints.

Development Workflow

Local Development

Setting up a local development environment follows a straightforward process. First, clone the repository to your machine. Install required dependencies using Cargo and system packages. Configure environment variables for local services. Run database migrations to set up the schema. Start the required services like PostgreSQL and cache. Load default templates for testing.

Testing Strategy

Testing ensures code quality at multiple levels. Unit tests verify individual functions and methods. Integration tests check interactions between components. End-to-end tests validate complete user workflows. Load testing measures performance under stress. Security testing identifies vulnerabilities.

CI/CD Pipeline

Continuous integration and deployment automates quality assurance. Automated testing runs on every commit. Code quality checks enforce standards. Security scanning identifies known vulnerabilities. The build process produces deployable artifacts. Deployment automation pushes releases to environments.

Future Architecture Plans

Planned Enhancements

Future development will expand system capabilities. Microservices migration will enable independent scaling of components. Kubernetes native deployment will simplify orchestration. Multi-region support will improve global performance. Edge deployment will reduce latency for distributed users. Serverless functions will enable elastic scaling for specific workloads.

Performance Goals

Performance targets guide optimization efforts. Response times should be sub-100ms for typical requests. The system should support 10,000 or more concurrent users. Uptime should reach 99.99% for production deployments. Elastic scaling should handle traffic spikes automatically. Global CDN integration should improve worldwide access times.

Module Structure

botserver is a single Rust crate (not a workspace) with multiple modules. The application is defined in Cargo.toml as the botserver crate, version 6.0.8.

Main Entry Points

The primary entry point is src/main.rs, which starts the Axum web server and initializes all components. The public library interface in src/lib.rs exports all major modules for external use.

Core Modules

The following modules are exported in src/lib.rs and comprise the core functionality:

User & Bot Management

The auth module handles user authentication, password hashing using Argon2, and session token management. The bot module manages bot lifecycle, configuration, and runtime operations. The session module provides user session handling and state management across conversations.

Conversation & Scripting

The basic module implements the BASIC-like scripting language interpreter for .gbdialog files. The context module manages conversation context and memory throughout user interactions. The channels module provides multi-channel support for web, voice, and various messaging platforms.

Knowledge & AI

The llm module provides LLM provider integration for OpenAI and local models. The llm_models module contains model-specific implementations and configurations. The nvidia module offers NVIDIA GPU acceleration support for local inference.

Infrastructure

The bootstrap module handles system initialization and the auto-bootstrap process. The package_manager module manages component installation and lifecycle. The config module provides application configuration and environment management. The shared module contains shared utilities, database models, and common types used throughout the codebase. The web_server module implements the Axum-based HTTP server and API endpoints.

Features & Integration

The automation module provides scheduled tasks and event-driven triggers. The drive_monitor module handles file system monitoring and change detection. The email module provides email integration via IMAP and SMTP as a conditional feature. The file module handles file processing and operations. The meet module integrates video meeting functionality through LiveKit.

Testing & Development

The tests module contains test utilities and test suites for validating functionality across the codebase.

Internal Modules

Several directories exist in src/ that are either internal implementations or not fully integrated into the public API.

The api/ directory contains the api/drive subdirectory with drive-related API code. The drive/ directory provides drive (S3-compatible) integration and vector database functionality through vectordb.rs. The ui/ directory contains UI-related modules including drive.rs, stream.rs, sync.rs, and local-sync.rs. The ui_tree/ directory provides UI tree structure functionality used in main.rs but not exported in lib.rs. The prompt_manager/ directory stores the prompt library and is not a Rust module but contains prompts.csv. The riot_compiler/ directory contains a Riot.js component compiler that exists but is currently unused. The web_automation/ directory is an empty placeholder for future functionality.

Dependency Management

All dependencies are managed through a single Cargo.toml at the project root.

The web framework layer uses axum, tower, and tower-http for HTTP handling. The async runtime is tokio for concurrent operations. Database access uses diesel for PostgreSQL and redis for cache component connectivity. AI and ML functionality relies on qdrant-client for vector database operations as an optional feature. Storage operations use aws-sdk-s3 for drive and S3-compatible storage backends. Scripting uses rhai as the BASIC-like language runtime. Security features include argon2 for password hashing and aes-gcm for encryption. Desktop support uses tauri as an optional feature.

Feature Flags

The crate supports optional features for customizing builds:

[features]
default = ["desktop"]
vectordb = ["qdrant-client"]
email = ["imap"]
desktop = ["dep:tauri", "dep:tauri-plugin-dialog", "dep:tauri-plugin-opener"]

Building

To build the project with different configurations:

# Standard build
cargo build --release

# Build without desktop features
cargo build --release --no-default-features

# Build with vector database support
cargo build --release --features vectordb

# Build with all features
cargo build --release --all-features

Module Organization Pattern

Most modules follow a consistent structure with a mod.rs file containing the main module implementation and a module_name.test.rs file for module-specific tests. Some modules have additional submodules or specialized files such as drive/vectordb.rs and ui/drive.rs for feature-specific functionality.

Service Layer

botserver’s service layer is organized into functional modules that handle specific aspects of the platform. Each module encapsulates related functionality and provides a clear API for interaction with other parts of the system. This chapter describes each service module and its responsibilities within the overall architecture.

Core Service Modules

Authentication and Security

The auth module provides secure user authentication and session management throughout the platform. Password hashing uses the Argon2 algorithm for secure password storage that resists both CPU and GPU-based attacks. Session token generation creates and validates unique tokens for maintaining authenticated state. User verification authenticates users against the database using stored credentials. Bot authentication manages bot-level authentication for API access, allowing bots to make authenticated requests to external services.

The module’s key responsibilities include hashing passwords with Argon2 before storage, generating cryptographically secure session tokens, validating user credentials during login, and managing the complete session lifecycle from creation through expiration.

Bot Management

The bot module handles bot lifecycle and configuration throughout the system. Bot creation initializes new bot instances with their required components. Configuration management loads and applies bot settings from config.csv files. Bot state tracking monitors bot status and health for operational awareness. Multi-tenant support isolates bots by tenant to prevent data leakage between organizations.

This module creates and deletes bot instances, loads bot configuration from the database, manages bot lifecycle including start, stop, and restart operations, and associates bots with users and sessions for proper isolation.

Session Management

The session module maintains user conversation state across interactions. Session storage persists conversation context to both cache and database. State management tracks user progress through dialogs and remembers variable values. Session cleanup removes expired sessions to free resources. Multi-user support isolates sessions by user to ensure privacy.

The module creates new sessions when users connect, stores and retrieves session variables, maintains conversation history for context, and cleans up abandoned sessions after timeout periods.

Conversation and Scripting Services

BASIC Interpreter

The basic module implements the BASIC-like scripting language for .gbdialog files. Script parsing reads BASIC dialog scripts and converts them to executable form. The execution engine powered by the Rhai scripting engine runs the parsed scripts. Keyword implementation provides custom keywords like TALK, HEAR, and LLM for bot functionality. Variable management handles script variables and maintains execution context across statements.

This module loads and parses .gbdialog scripts from bot packages, executes BASIC commands in sequence, provides custom keywords that extend the language for bot functionality, and manages script execution context including variables and flow control state.

Context Management

The context module manages conversation context and memory for LLM interactions. Conversation history storage maintains the message history for each session. Context retrieval loads relevant context for LLM calls based on the current query. Memory management limits context size to fit within model token limits. Context compaction summarizes old conversations to preserve meaning while reducing tokens.

The module appends messages to conversation history as they occur, retrieves appropriate context for LLM queries, implements context window management to stay within limits, and provides context to knowledge base queries for improved relevance.

Channel Abstraction

The channels module provides a unified interface for multiple communication channels. The web interface enables browser-based chat through the default UI. WebSocket support provides real-time bidirectional communication for responsive interactions. Voice integration handles audio input and output for voice-enabled bots. Platform adapters provide an extensible channel system for adding new platforms.

This module abstracts channel-specific implementations behind a common interface, routes messages to appropriate handlers based on channel type, formats responses appropriately for specific channels, and handles channel-specific features like typing indicators and read receipts.

AI and Knowledge Services

LLM Integration

The llm module integrates with large language models for natural language understanding and generation. Provider abstraction supports multiple LLM providers through a common interface. API communication handles API calls to LLM services including authentication and rate limiting. Streaming responses support token streaming for real-time response display. Error handling provides graceful degradation when API calls fail.

The module sends prompts to LLM providers using appropriate formats, parses and streams responses back to callers, handles API authentication and key management, and manages rate limiting with automatic retries when necessary.

LLM Models

The llm_models module contains model-specific implementations for different providers. Model configurations define parameters and capabilities for different models. Prompt templates handle model-specific prompt formatting requirements. Token counting estimates token usage before making API calls. Model selection chooses the appropriate model for each task based on requirements.

This module defines model capabilities and limits for each supported model, formats prompts according to each model’s expectations, calculates token costs for usage tracking, and selects optimal models for specific query types.

NVIDIA Integration

The nvidia module provides GPU acceleration support for local model inference. GPU detection identifies available NVIDIA GPUs in the system. Acceleration enables GPU-accelerated inference for local models. Resource management allocates GPU resources among concurrent requests.

Infrastructure Services

Bootstrap

The bootstrap module handles system initialization and first-time setup. Component installation downloads and installs required components including PostgreSQL, cache, and drive storage. Database setup creates schemas and applies migrations to prepare the database. Credential generation creates secure passwords for all services. Environment configuration writes .env files with generated settings. Template upload deploys bot templates to storage for immediate use.

The module detects installation mode to determine whether it is running locally or in containers, installs and starts all system components in the correct order, initializes the database with migrations and seed data, configures drive storage with appropriate buckets, and creates default bots from included templates.

Package Manager

The package_manager module manages component installation and lifecycle. The component registry tracks available components and their versions. Installation downloads and installs components from configured sources. Lifecycle management starts, stops, and restarts components as needed. Dependency resolution ensures components start in the correct order based on their dependencies.

Managed components include tables for PostgreSQL database, cache for Valkey caching, drive for S3-compatible object storage, llm for local LLM server, email for email server integration, proxy for reverse proxy functionality, directory for LDAP directory services, alm for application lifecycle management, dns for DNS server operations, meeting for LiveKit video conferencing, and vector_db for Qdrant vector database functionality.

Configuration

The config module loads and validates application configuration. Environment variables load from .env files and system environment. Validation ensures all required configuration is present before startup. Defaults provide sensible values for optional settings. Type safety parses configuration into strongly-typed structs for compile-time checking.

The module loads DATABASE_URL, DRIVE_SERVER, API keys, and other settings, validates configuration completeness at startup, provides configuration access to other modules through a shared struct, and handles configuration errors with helpful messages.

Shared Utilities

The shared module contains common functionality used across the system. Database models define the Diesel schema and models for all tables. Connection pooling manages R2D2 connection pools for efficient database access. Utilities provide common helper functions for repeated tasks. Types define shared type definitions used throughout the codebase.

This module defines the database schema with Diesel macros, provides database connection helpers for consistent access patterns, implements common utility functions for string manipulation and data transformation, and shares types across modules to ensure consistency.

Web Server

The web_server module implements the HTTP API using Axum. API routes define RESTful endpoints for bot interaction and management. The WebSocket handler manages real-time communication channels. Static files serve web UI assets for the browser interface. CORS configuration enables cross-origin resource sharing for embedded deployments. Middleware handles logging, authentication, and error handling for all requests.

This module defines API routes and their handlers, processes HTTP requests and generates responses, manages WebSocket connections for real-time chat, and serves static web interface files for the UI.

Feature Services

Automation

The automation module provides scheduled and event-driven task execution. Cron scheduling runs tasks on defined schedules using standard cron syntax. Event triggers react to system events by executing associated handlers. Background jobs execute long-running tasks without blocking the main thread. Job management tracks running jobs and allows cancellation when needed.

Drive Monitor

The drive_monitor module watches for file system changes in bot packages. File watching detects file creation, modification, and deletion events. Event processing handles file change events by triggering appropriate actions. Automatic indexing adds new documents to the knowledge base when they appear in monitored directories.

Email Integration

The email module handles email communication as an optional feature. IMAP support reads emails from configured inbox folders. SMTP support sends emails via the Lettre library. Email parsing extracts text content and attachments from received messages. Template rendering generates HTML emails from templates with variable substitution.

File Handling

The file module processes various file types for knowledge base ingestion. PDF extraction pulls text from PDF documents using pdf-extract. Document parsing handles various document formats including Word and plain text. File upload processes multipart file uploads from users. Storage integration saves processed files to drive storage for persistence.

Meeting Integration

The meet module integrates with LiveKit for video conferencing capabilities. Room creation establishes meeting rooms with appropriate settings. Token generation creates access tokens for meeting participants. Participant management tracks who is in each meeting. Recording captures meeting sessions for later review.

Storage Services

Drive

The drive module provides S3-compatible object storage integration. Drive integration uses the AWS SDK S3 client for compatibility with various providers. Bucket management creates and manages storage buckets for different bots. Object operations handle upload, download, and delete operations for files. Vector database integration connects to Qdrant for semantic search functionality.

UI Components

The ui module contains UI-related functionality for the web interface. Drive UI provides a file browser interface for managing documents. Stream handling implements server-sent events for real-time updates. Sync logic manages synchronization between local and remote files. Local sync enables desktop app file synchronization for offline access.

Testing

The tests module provides test utilities and integration tests for the platform. Test fixtures provide common test data and setup procedures. Integration tests validate end-to-end functionality across modules. Mock services substitute for external dependencies during testing. Test helpers provide utilities for writing consistent, readable tests.

Service Interaction Patterns

Layered Architecture

Services are organized into layers with clear dependencies. The infrastructure layer contains bootstrap, package_manager, config, shared, and web_server modules that provide foundational capabilities. The data layer contains drive, file, and session modules that handle persistence. The domain layer contains bot, auth, context, and basic modules that implement core business logic. The AI layer contains llm, llm_models, and nvidia modules for machine learning integration. The feature layer contains automation, email, meet, and drive_monitor modules that add optional capabilities. The presentation layer contains channels and ui modules that handle user interaction.

Dependency Injection

Services use Rust’s module system and trait-based design for dependency injection. Database connections are shared via connection pools managed by R2D2. Configuration is passed through the AppConfig struct which is initialized at startup and shared immutably. Services access their dependencies through function parameters rather than global state.

Error Handling

All services use anyhow::Result<T> for error handling, allowing errors to propagate up the call stack with context. Each layer adds relevant context to errors before propagating them. Critical services log errors using the log crate with appropriate severity levels. User-facing errors are translated to helpful messages without exposing internal details.

Async Operations

Most services are async and use Tokio as the runtime. This design allows concurrent handling of multiple user sessions without blocking. External API calls run concurrently to minimize latency. Background tasks use Tokio’s task spawning for parallel execution. The async design enables efficient resource utilization even under high load.

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):

cargo build --release --no-default-features

For desktop application development (requires GTK libraries):

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

sudo apt install git

macOS

brew install git

Windows

Download and install from: https://git-scm.com/download/win

Or use winget:

winget install Git.Git

Install Rust

If you don’t have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version
cargo --version

System Dependencies

Linux (Ubuntu/Debian)

Base dependencies (required for all builds):

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):

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:

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):

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):

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:

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

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

git clone --recursive https://github.com/GeneralBots/gb.git
cd gb

If you cloned without --recursive, initialize submodules:

git submodule update --init --recursive

Build Cache with sccache

sccache caches compilation artifacts for faster rebuilds.

Install and configure:

cargo install sccache
mkdir -p ~/.cargo
echo '[build]
compiler = "sccache"' >> ~/.cargo/config.toml
export RUSTC_WRAPPER=sccache

Verify cache hits:

sccache --show-stats

Clear cache if needed:

sccache --zero-stats

Build Configurations

Minimal Build (Recommended for Server)

Build without desktop GUI dependencies:

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):

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:

cargo build --release --features vectordb

With Email Support

Enable IMAP email integration:

cargo build --release --features email

Desktop Application

Build as desktop app with Tauri (default):

cargo build --release --features desktop

All Features

Build with all optional features:

cargo build --release --all-features

Feature Flags

botserver supports the following features defined in Cargo.toml:

[features]
default = ["desktop"]
vectordb = ["qdrant-client"]
email = ["imap"]
desktop = ["dep:tauri", "dep:tauri-plugin-dialog", "dep:tauri-plugin-opener"]

Feature Details

Build Profiles

Debug Build

For development with debug symbols and no optimizations:

cargo build

Binary location: target/debug/botserver

Release Build

Optimized for production with LTO and size optimization:

cargo build --release

Binary location: target/release/botserver

The release profile in Cargo.toml uses aggressive optimization:

[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:

cargo build --release

For static linking (portable binary):

RUSTFLAGS='-C target-feature=+crt-static' cargo build --release --target x86_64-unknown-linux-gnu

macOS

Build for current architecture:

cargo build --release

Build universal binary (Intel + Apple Silicon):

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:

cargo build --release

Binary location: target\release\botserver.exe

Cross-Compilation

Install Cross-Compilation Tools

cargo install cross

Build for Linux from macOS/Windows

cross build --release --target x86_64-unknown-linux-gnu

Build for Windows from Linux/macOS

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:

sudo apt install clang lld

Then configure Rust to use clang:

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:

sudo apt install libssl-dev

macOS:

export OPENSSL_DIR=$(brew --prefix openssl)
cargo build --release

Windows:

# 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):

sudo apt install libsoup-3.0-dev

Solution (Fedora/RHEL):

sudo dnf install libsoup3-devel

Solution (macOS):

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:

sudo apt install libpq-dev

macOS:

brew install postgresql
export PQ_LIB_DIR=$(brew --prefix postgresql)/lib

Windows:

# 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:

cargo install sccache
export RUSTC_WRAPPER=sccache
cargo build --release

Or reduce parallel jobs:

cargo build --release -j 2

Or limit memory per job:

CARGO_BUILD_JOBS=2 cargo build --release

Linker Errors

Ensure you have a C/C++ compiler:

Linux:

sudo apt install build-essential

macOS:

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:

sudo apt update
sudo apt install -y clang lld build-essential

2. Configure Rust to use clang:

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:

cargo clean
cargo build --release

Solution (macOS):

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:

sudo apt install libpq-dev

macOS:

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:

sudo apt install libssl-dev pkg-config

macOS:

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:

CARGO_BUILD_JOBS=2 cargo build --release

Or limit memory:

ulimit -v 4000000  # Limit to 4GB
cargo build --release

Error: Submodule references not found

Cause: Submodules not initialized.

Solution:

git submodule update --init --recursive

Or re-clone with submodules:

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:

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:

[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:

./target/release/botserver --version

Expected output: botserver 6.2.0 or similar.

Development Builds

Watch Mode

Auto-rebuild on file changes:

cargo install cargo-watch
cargo watch -x 'build --release'

Check Without Building

Fast syntax and type checking:

cargo check

With specific features:

cargo check --features vectordb,email

Testing

Run All Tests

cargo test

Run Tests for Specific Module

cargo test --package botserver --lib bootstrap::tests

Run Integration Tests

cargo test --test '*'

Code Quality

Format Code

cargo fmt

Lint Code

cargo clippy -- -D warnings

Check Dependencies

cargo tree

Find duplicate dependencies:

cargo tree --duplicates

Security Audit

Run security audit to check for known vulnerabilities in dependencies:

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:

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

strip target/release/botserver

Use UPX Compression

upx --best --lzma target/release/botserver

Note: UPX may cause issues with some systems. Test thoroughly.

Clean Build

Remove all build artifacts:

cargo clean

CI/CD Builds

For automated builds in CI/CD pipelines:

GitHub Actions

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:

# 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:

sudo install -m 755 target/release/botserver /usr/local/bin/

Or create a symlink:

ln -s $(pwd)/target/release/botserver ~/.local/bin/botserver

Verify installation:

botserver --version

Expected output: botserver 6.2.0 or similar.

Quick Reference

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 for next steps.

Cargo Tools Reference

This chapter documents essential Cargo tools for botserver development, including code coverage, security auditing, performance profiling, and code quality tools.

Overview

The Rust ecosystem provides powerful tools through Cargo extensions. These tools help maintain code quality, identify security vulnerabilities, measure test coverage, and optimize performance.

Code Coverage with cargo-tarpaulin

Installation

cargo install cargo-tarpaulin

Basic Usage

Run code coverage analysis:

cargo tarpaulin

This generates a coverage report showing which lines of code are exercised by tests.

Output Formats

Generate HTML report:

cargo tarpaulin --out Html

Generate multiple formats (coverage report, lcov for CI):

cargo tarpaulin --out Html --out Lcov --out Json

Coverage with Features

Test with specific features enabled:

cargo tarpaulin --features vectordb,email

Test all features:

cargo tarpaulin --all-features

Excluding Files

Exclude test files and generated code from coverage:

cargo tarpaulin --ignore-tests --exclude-files "gen/*" "tests/*"

Coverage Thresholds

Fail if coverage drops below a threshold (useful for CI):

cargo tarpaulin --fail-under 80

Verbose Output

Show detailed coverage per function:

cargo tarpaulin --verbose

Integration with CI

Example GitHub Actions workflow:

- name: Install tarpaulin
  run: cargo install cargo-tarpaulin

- name: Generate coverage
  run: cargo tarpaulin --out Xml --fail-under 70

- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v3
  with:
    files: cobertura.xml

Configuration File

Create .tarpaulin.toml for project-wide settings:

[config]
command = "test"
features = "vectordb"
ignore-tests = true
out = ["Html", "Lcov"]
exclude-files = ["gen/*"]
timeout = "120s"

Security Auditing with cargo-audit

Installation

cargo install cargo-audit

Basic Usage

Check for known security vulnerabilities in dependencies:

cargo audit

Continuous Auditing

Run audit as part of CI pipeline to catch new vulnerabilities:

cargo audit --deny warnings

Fix Vulnerabilities

Generate a fix for vulnerable dependencies (when possible):

cargo audit fix

Database Updates

Update the vulnerability database:

cargo audit fetch

Ignore Known Issues

Create .cargo/audit.toml to ignore specific advisories:

[advisories]
ignore = [
    "RUSTSEC-2020-0071",  # Reason for ignoring
]

JSON Output for CI

cargo audit --json > audit-report.json

Dependency Analysis with cargo-deny

Installation

cargo install cargo-deny

Configuration

Create deny.toml:

[advisories]
vulnerability = "deny"
unmaintained = "warn"

[licenses]
unlicensed = "deny"
allow = [
    "MIT",
    "Apache-2.0",
    "BSD-3-Clause",
]

[bans]
multiple-versions = "warn"
deny = [
    { name = "openssl" },  # Prefer rustls
]

[sources]
unknown-registry = "deny"
unknown-git = "deny"

Usage

Check all configured rules:

cargo deny check

Check specific categories:

cargo deny check advisories
cargo deny check licenses
cargo deny check bans
cargo deny check sources

Code Formatting with cargo-fmt

Usage

Format all code:

cargo fmt

Check formatting without changes:

cargo fmt --check

Configuration

Create rustfmt.toml:

edition = "2021"
max_width = 100
tab_spaces = 4
use_small_heuristics = "Default"
reorder_imports = true
group_imports = "StdExternalCrate"

Linting with cargo-clippy

Usage

Run clippy with warnings as errors:

cargo clippy -- -D warnings

Run with all lints:

cargo clippy -- -W clippy::all -W clippy::pedantic

Fix Suggestions Automatically

cargo clippy --fix --allow-dirty

Configuration

Add to Cargo.toml:

[lints.clippy]
all = "warn"
pedantic = "warn"
unwrap_used = "deny"
expect_used = "deny"

Or create .clippy.toml:

avoid-breaking-exported-api = false
msrv = "1.70"

Documentation with cargo-doc

Generate Documentation

cargo doc --open

With private items:

cargo doc --document-private-items --open

Check Documentation

Find broken links and missing docs:

cargo rustdoc -- -D warnings

Benchmarking with cargo-criterion

Installation

cargo install cargo-criterion

Usage

Run benchmarks:

cargo criterion

Benchmark Example

Create benches/my_benchmark.rs:

#![allow(unused)]
fn main() {
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 1,
        1 => 1,
        n => fibonacci(n-1) + fibonacci(n-2),
    }
}

fn benchmark(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, benchmark);
criterion_main!(benches);
}

Dependency Management with cargo-outdated

Installation

cargo install cargo-outdated

Usage

Check for outdated dependencies:

cargo outdated

Show only root dependencies:

cargo outdated --root-deps-only

Binary Size Analysis with cargo-bloat

Installation

cargo install cargo-bloat

Usage

Show largest functions:

cargo bloat --release -n 20

Show largest crates:

cargo bloat --release --crates

Size Comparison

Compare sizes between releases:

cargo bloat --release --crates > before.txt
# Make changes
cargo bloat --release --crates > after.txt
diff before.txt after.txt

Dependency Tree with cargo-tree

Usage

View full dependency tree:

cargo tree

Find duplicate dependencies:

cargo tree --duplicates

Find why a dependency is included:

cargo tree --invert tokio

Watch Mode with cargo-watch

Installation

cargo install cargo-watch

Usage

Auto-rebuild on changes:

cargo watch -x build

Auto-test on changes:

cargo watch -x test

Run multiple commands:

cargo watch -x check -x test -x clippy

Memory Profiling with cargo-valgrind

Installation (Linux)

sudo apt install valgrind
cargo install cargo-valgrind

Usage

cargo valgrind run

LLVM Coverage with cargo-llvm-cov

Installation

cargo install cargo-llvm-cov

Usage

More accurate coverage than tarpaulin for some cases:

cargo llvm-cov

Generate HTML report:

cargo llvm-cov --html

Recommended CI Pipeline

Example complete CI configuration using these tools:

name: CI

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      
      - name: Format check
        run: cargo fmt --check
      
      - name: Clippy
        run: cargo clippy -- -D warnings
      
      - name: Build
        run: cargo build --release
      
      - name: Test
        run: cargo test

  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      
      - name: Install tarpaulin
        run: cargo install cargo-tarpaulin
      
      - name: Coverage
        run: cargo tarpaulin --out Xml --fail-under 70
      
      - uses: codecov/codecov-action@v3

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      
      - name: Install audit
        run: cargo install cargo-audit
      
      - name: Security audit
        run: cargo audit --deny warnings

Quick Reference

Installation Script

Install all recommended tools at once:

#!/bin/bash
# install-cargo-tools.sh

cargo install cargo-tarpaulin
cargo install cargo-audit
cargo install cargo-deny
cargo install cargo-outdated
cargo install cargo-bloat
cargo install cargo-watch
cargo install cargo-criterion
cargo install cargo-llvm-cov

Next Steps

After setting up these tools:

1. Run cargo audit regularly to catch security issues
2. Add cargo tarpaulin to your CI pipeline
3. Use cargo clippy before every commit
4. Set up pre-commit hooks for automatic formatting

See Building from Source for build-specific information.

Container Deployment (LXC)

botserver uses LXC (Linux Containers) for isolated component deployment with system-level containerization.

⚠️ IMPORTANT: All container create and management commands must be run from the host system, not from inside a container. The botserver binary manages LXC containers from the host level.

What is LXC?

• System containers - Full Linux userspace (lightweight VMs)
• Shared kernel - More efficient than virtual machines
• Isolation - Separate processes, networking, filesystems
• Resource control - CPU, memory, I/O limits

Automatic Setup

Run on the host system:

./botserver --container

This automatically:

1. Detects LXC/LXD availability
2. Initializes LXD if needed
3. Creates Debian 12 containers per component
4. Mounts directories for persistent data
5. Configures networking and ports
6. Installs and starts services

Container Architecture

Container Naming

{tenant}-tables      → PostgreSQL
{tenant}-drive       → S3-compatible storage
{tenant}-cache       → Valkey cache
{tenant}-llm         → LLM server (optional)
{tenant}-email       → Mail server (optional)

Default tenant: default → default-tables, default-drive, etc.

Directory Mounting

Host: botserver-stack/tables/data/  → Container: /opt/gbo/data/
Host: botserver-stack/tables/conf/  → Container: /opt/gbo/conf/
Host: botserver-stack/tables/logs/  → Container: /opt/gbo/logs/

Data persists even if containers are deleted.

Port Forwarding

Common Operations

Run these commands on the host system:

# List containers
lxc list

# Execute command in container
lxc exec default-tables -- psql -U gbuser botserver

# View logs
lxc exec default-tables -- journalctl -u tables

# Stop/Start
lxc stop default-tables
lxc start default-tables

# Delete (data in mounts persists)
lxc delete default-tables --force

Resource Limits

lxc config set default-tables limits.cpu 2
lxc config set default-tables limits.memory 4GB

Snapshots

# Create
lxc snapshot default-tables backup-2024-01-15

# List
lxc info default-tables

# Restore
lxc restore default-tables backup-2024-01-15

Troubleshooting

Container vs Local

Example: Create Vault and VectorDB Containers

Run on the host system:

# Install Vault for secrets management
botserver install vault --container --tenant mycompany

# Install VectorDB (Qdrant) for embeddings
botserver install vector_db --container --tenant mycompany

# Verify containers are running
lxc list | grep mycompany

# Get container IPs
lxc list mycompany-vault -c n4 --format csv
lxc list mycompany-vectordb -c n4 --format csv

# Test services
curl http://<vault-ip>:8200/v1/sys/health
curl http://<vectordb-ip>:6333/health

Migration

Local → Container

Run on the host system:

pg_dump botserver > backup.sql
./botserver --container
lxc exec default-tables -- psql -U gbuser botserver < backup.sql

Container → Local

Run on the host system:

lxc exec default-tables -- pg_dump -U gbuser botserver > backup.sql
./botserver uninstall tables
./botserver install tables --local
psql -U gbuser botserver < backup.sql

Brother Mode Configuration

If you are running botserver itself inside a container (e.g., LXC or Docker) but want it to manage other LXC containers on the host (“Brother Mode”), you must expose the host’s LXD socket.

Required LXD Profile

To allow child containers to communicate with the host LXD daemon, add the lxd-sock proxy device to the default profile. This maps the host’s socket to /tmp/lxd.sock inside the container, avoiding conflicts with missing /var/lib/lxd directories in standard images.

LXD installed via snap uses /var/snap/lxd/common/lxd/unix.socket:

lxc profile device add default lxd-sock proxy \
  connect=unix:/var/snap/lxd/common/lxd/unix.socket \
  listen=unix:/tmp/lxd.sock \
  bind=container \
  uid=0 gid=0 mode=0660

For LXD installed via packages (non-snap), use:

lxc profile device add default lxd-sock proxy \
  connect=unix:/var/lib/lxd/unix.socket \
  listen=unix:/tmp/lxd.sock \
  bind=container \
  uid=0 gid=0 mode=0660

Note: The botserver installer attempts to configure this automatically. If you encounter “socket not found” errors, verify this proxy device exists.

See Also

• Installation - Local setup
• Docker Deployment - Docker alternative
• Architecture - System design

Docker Deployment

Note: Docker support is currently experimental.

Deployment Options

Option 1: All-in-One Container

Quick Start

docker run -d \
  --name botserver \
  -p 8000:8000 \
  -p 9000:9000 \
  -v botserver-data:/opt/gbo/data \
  -e ADMIN_PASS=your-secure-password \
  pragmatismo/botserver:latest

Docker Compose

version: '3.8'

services:
  botserver:
    image: pragmatismo/botserver:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
      - "9000:9000"
      - "9001:9001"
    volumes:
      - botserver-data:/opt/gbo/data
      - ./work:/opt/gbo/work
    environment:
      - ADMIN_PASS=${ADMIN_PASS:-changeme}
      - DOMAIN=${DOMAIN:-localhost}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  botserver-data:

Resources: 2 CPU cores, 4GB RAM minimum

Option 2: Microservices

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: botserver
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: botserver
    networks:
      - gb-network

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio-data:/data
    environment:
      MINIO_ROOT_USER: ${DRIVE_ACCESSKEY}
      MINIO_ROOT_PASSWORD: ${DRIVE_SECRET}
    networks:
      - gb-network

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant-data:/qdrant/storage
    networks:
      - gb-network

  botserver:
    image: pragmatismo/botserver:latest
    depends_on:
      - postgres
      - minio
      - qdrant
    ports:
      - "8000:8000"
    volumes:
      - ./work:/opt/gbo/work
    environment:
      DATABASE_URL: postgres://botserver:${DB_PASSWORD}@postgres:5432/botserver
      DRIVE_URL: http://minio:9000
      DRIVE_ACCESSKEY: ${DRIVE_ACCESSKEY}
      DRIVE_SECRET: ${DRIVE_SECRET}
      QDRANT_URL: http://qdrant:6333
      ADMIN_PASS: ${ADMIN_PASS}
    networks:
      - gb-network

networks:
  gb-network:

volumes:
  postgres-data:
  minio-data:
  qdrant-data:

Environment File (.env)

DB_PASSWORD=secure-db-password
DRIVE_ACCESSKEY=minioadmin
DRIVE_SECRET=secure-minio-secret
ADMIN_PASS=admin-password
DOMAIN=your-domain.com

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: botserver
spec:
  replicas: 3
  selector:
    matchLabels:
      app: botserver
  template:
    spec:
      containers:
      - name: botserver
        image: pragmatismo/botserver:latest
        ports:
        - containerPort: 8000
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "2Gi"
            cpu: "1000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
---
apiVersion: v1
kind: Service
metadata:
  name: botserver
spec:
  selector:
    app: botserver
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Health Endpoints

Troubleshooting

Migration from Non-Docker

# 1. Backup data
pg_dump botserver > backup.sql
mc cp --recursive /path/to/drive minio/backup/

# 2. Start Docker containers

# 3. Restore
docker exec -i gb-postgres psql -U botserver < backup.sql
docker exec gb-minio mc cp --recursive /backup minio/drive/

See Also

• Installation - Local installation
• Container Deployment (LXC) - Linux containers
• Scaling - Load balancing and scaling

Kubernetes Deployment

Scaling and Load Balancing

General Bots is designed to scale from a single instance to a distributed cluster using LXC containers. This chapter covers auto-scaling, load balancing, sharding strategies, and failover systems.

Scaling Architecture

General Bots uses a horizontal scaling approach with LXC containers:

                    ┌─────────────────┐
                    │   Caddy Proxy   │
                    │  (Load Balancer)│
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  LXC Container  │ │  LXC Container  │ │  LXC Container  │
│   botserver-1   │ │   botserver-2   │ │   botserver-3   │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   PostgreSQL    │ │     Redis       │ │     Qdrant      │
│   (Primary)     │ │   (Cluster)     │ │   (Cluster)     │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Auto-Scaling Configuration

config.csv Parameters

Configure auto-scaling behavior in your bot’s config.csv:

# Auto-scaling settings
scale-enabled,true
scale-min-instances,1
scale-max-instances,10
scale-cpu-threshold,70
scale-memory-threshold,80
scale-request-threshold,1000
scale-cooldown-seconds,300
scale-check-interval,30

Scaling Rules

Define custom scaling rules:

# Scale up when average response time exceeds 2 seconds
scale-rule-response-time,2000
scale-rule-response-action,up

# Scale down when CPU drops below 30%
scale-rule-cpu-low,30
scale-rule-cpu-low-action,down

# Scale up on queue depth
scale-rule-queue-depth,100
scale-rule-queue-action,up

LXC Container Management

Creating Scaled Instances

# Create additional botserver containers
for i in {2..5}; do
  lxc launch images:debian/12 botserver-$i
  lxc config device add botserver-$i port-$((8080+i)) proxy \
    listen=tcp:0.0.0.0:$((8080+i)) connect=tcp:127.0.0.1:9000
done

Container Resource Limits

Set resource limits per container:

# CPU limits (number of cores)
lxc config set botserver-1 limits.cpu 4

# Memory limits
lxc config set botserver-1 limits.memory 8GB

# Disk I/O priority (0-10)
lxc config set botserver-1 limits.disk.priority 5

# Network bandwidth (ingress/egress)
lxc config device set botserver-1 eth0 limits.ingress 100Mbit
lxc config device set botserver-1 eth0 limits.egress 100Mbit

Auto-Scaling Script

Create /opt/gbo/scripts/autoscale.sh:

#!/bin/bash

# Configuration
MIN_INSTANCES=1
MAX_INSTANCES=10
CPU_THRESHOLD=70
SCALE_COOLDOWN=300
LAST_SCALE_FILE="/tmp/last_scale_time"

get_avg_cpu() {
    local total=0
    local count=0
    for container in $(lxc list -c n --format csv | grep "^botserver-"); do
        cpu=$(lxc exec $container -- cat /proc/loadavg | awk '{print $1}')
        total=$(echo "$total + $cpu" | bc)
        count=$((count + 1))
    done
    echo "scale=2; $total / $count * 100" | bc
}

get_instance_count() {
    lxc list -c n --format csv | grep -c "^botserver-"
}

can_scale() {
    if [ ! -f "$LAST_SCALE_FILE" ]; then
        return 0
    fi
    last_scale=$(cat "$LAST_SCALE_FILE")
    now=$(date +%s)
    diff=$((now - last_scale))
    [ $diff -gt $SCALE_COOLDOWN ]
}

scale_up() {
    current=$(get_instance_count)
    if [ $current -ge $MAX_INSTANCES ]; then
        echo "Already at max instances ($MAX_INSTANCES)"
        return 1
    fi
    
    new_id=$((current + 1))
    echo "Scaling up: creating botserver-$new_id"
    
    lxc launch images:debian/12 botserver-$new_id
    lxc config set botserver-$new_id limits.cpu 4
    lxc config set botserver-$new_id limits.memory 8GB
    
    # Copy configuration
    lxc file push /opt/gbo/conf/botserver.env botserver-$new_id/opt/gbo/conf/
    
    # Start botserver
    lxc exec botserver-$new_id -- /opt/gbo/bin/botserver &
    
    # Update load balancer
    update_load_balancer
    
    date +%s > "$LAST_SCALE_FILE"
    echo "Scale up complete"
}

scale_down() {
    current=$(get_instance_count)
    if [ $current -le $MIN_INSTANCES ]; then
        echo "Already at min instances ($MIN_INSTANCES)"
        return 1
    fi
    
    # Remove highest numbered instance
    target="botserver-$current"
    echo "Scaling down: removing $target"
    
    # Drain connections
    lxc exec $target -- /opt/gbo/bin/botserver drain
    sleep 30
    
    # Stop and delete
    lxc stop $target
    lxc delete $target
    
    # Update load balancer
    update_load_balancer
    
    date +%s > "$LAST_SCALE_FILE"
    echo "Scale down complete"
}

update_load_balancer() {
    # Generate upstream list
    upstreams=""
    for container in $(lxc list -c n --format csv | grep "^botserver-"); do
        ip=$(lxc list $container -c 4 --format csv | cut -d' ' -f1)
        upstreams="$upstreams\n        to $ip:9000"
    done
    
    # Update Caddy config
    cat > /opt/gbo/conf/caddy/upstream.conf << EOF
upstream botserver {
    $upstreams
    lb_policy round_robin
    health_uri /api/health
    health_interval 10s
}
EOF
    
    # Reload Caddy
    lxc exec proxy-1 -- caddy reload --config /etc/caddy/Caddyfile
}

# Main loop
while true; do
    avg_cpu=$(get_avg_cpu)
    echo "Average CPU: $avg_cpu%"
    
    if can_scale; then
        if (( $(echo "$avg_cpu > $CPU_THRESHOLD" | bc -l) )); then
            scale_up
        elif (( $(echo "$avg_cpu < 30" | bc -l) )); then
            scale_down
        fi
    fi
    
    sleep 30
done

Load Balancing

Caddy Configuration

Primary load balancer configuration (/opt/gbo/conf/caddy/Caddyfile):

{
    admin off
    auto_https on
}

(common) {
    encode gzip zstd
    header {
        -Server
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
}

bot.example.com {
    import common
    
    # Health check endpoint (no load balancing)
    handle /api/health {
        reverse_proxy localhost:9000
    }
    
    # WebSocket connections (sticky sessions)
    handle /ws* {
        reverse_proxy botserver-1:9000 botserver-2:9000 botserver-3:9000 {
            lb_policy cookie
            lb_try_duration 5s
            health_uri /api/health
            health_interval 10s
            health_timeout 5s
        }
    }
    
    # API requests (round robin)
    handle /api/* {
        reverse_proxy botserver-1:9000 botserver-2:9000 botserver-3:9000 {
            lb_policy round_robin
            lb_try_duration 5s
            health_uri /api/health
            health_interval 10s
            fail_duration 30s
        }
    }
    
    # Static files (any instance)
    handle {
        reverse_proxy botserver-1:9000 botserver-2:9000 botserver-3:9000 {
            lb_policy first
        }
    }
}

Load Balancing Policies

Rate Limiting

Configure rate limits in config.csv:

# Rate limiting
rate-limit-enabled,true
rate-limit-requests,100
rate-limit-window,60
rate-limit-burst,20
rate-limit-by,ip

# Per-endpoint limits
rate-limit-api-chat,30
rate-limit-api-files,50
rate-limit-api-auth,10

Rate limiting in Caddy:

bot.example.com {
    # Global rate limit
    rate_limit {
        zone global {
            key {remote_host}
            events 100
            window 1m
        }
    }
    
    # Stricter limit for auth endpoints
    handle /api/auth/* {
        rate_limit {
            zone auth {
                key {remote_host}
                events 10
                window 1m
            }
        }
        reverse_proxy botserver:9000
    }
}

Sharding Strategies

Database Sharding Options

Option 1: Tenant-Based Sharding

Each tenant gets their own database:

┌─────────────────┐
│   Router/Proxy  │
└────────┬────────┘
         │
    ┌────┴────┬──────────┐
    │         │          │
    ▼         ▼          ▼
┌───────┐ ┌───────┐ ┌───────┐
│Tenant1│ │Tenant2│ │Tenant3│
│  DB   │ │  DB   │ │  DB   │
└───────┘ └───────┘ └───────┘

Configuration:

# Tenant sharding
shard-strategy,tenant
shard-tenant-db-prefix,gb_tenant_
shard-auto-create,true

Option 2: Hash-Based Sharding

Distribute data by hash of primary key:

User ID: 12345
Hash: 12345 % 4 = 1
Shard: shard-1

Configuration:

# Hash sharding
shard-strategy,hash
shard-count,4
shard-key,user_id
shard-algorithm,modulo

Option 3: Range-Based Sharding

Partition by ID ranges:

# Range sharding
shard-strategy,range
shard-ranges,0-999999:shard1,1000000-1999999:shard2,2000000-:shard3

Option 4: Geographic Sharding

Route by user location:

# Geographic sharding
shard-strategy,geo
shard-geo-us,postgres-us.example.com
shard-geo-eu,postgres-eu.example.com
shard-geo-asia,postgres-asia.example.com
shard-default,postgres-us.example.com

Vector Database Sharding (Qdrant)

Qdrant supports automatic sharding:

# Qdrant sharding
qdrant-shard-count,4
qdrant-replication-factor,2
qdrant-write-consistency,majority

Collection creation with sharding:

#![allow(unused)]
fn main() {
// In vectordb code
let collection_config = CreateCollection {
    collection_name: format!("kb_{}", bot_id),
    vectors_config: VectorsConfig::Single(VectorParams {
        size: 384,
        distance: Distance::Cosine,
    }),
    shard_number: Some(4),
    replication_factor: Some(2),
    write_consistency_factor: Some(1),
    ..Default::default()
};
}

Redis Cluster

For high-availability caching:

# Redis cluster
cache-mode,cluster
cache-nodes,redis-1:6379,redis-2:6379,redis-3:6379
cache-replicas,1

Failover Systems

Health Checks

Configure health check endpoints:

# Health check configuration
health-enabled,true
health-endpoint,/api/health
health-interval,10
health-timeout,5
health-retries,3

Health check response:

{
  "status": "healthy",
  "version": "6.1.0",
  "uptime": 86400,
  "checks": {
    "database": "ok",
    "cache": "ok",
    "vectordb": "ok",
    "llm": "ok"
  },
  "metrics": {
    "cpu": 45.2,
    "memory": 62.1,
    "connections": 150
  }
}

Automatic Failover

Database Failover (PostgreSQL)

Using Patroni for PostgreSQL HA:

# patroni.yml
scope: botserver-cluster
name: postgres-1

restapi:
  listen: 0.0.0.0:8008
  connect_address: postgres-1:8008

etcd:
  hosts: etcd-1:2379,etcd-2:2379,etcd-3:2379

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
    postgresql:
      use_pg_rewind: true
      parameters:
        max_connections: 200
        shared_buffers: 2GB

postgresql:
  listen: 0.0.0.0:5432
  connect_address: postgres-1:5432
  data_dir: /var/lib/postgresql/data
  authentication:
    superuser:
      username: postgres
      password: ${POSTGRES_PASSWORD}
    replication:
      username: replicator
      password: ${REPLICATION_PASSWORD}

Cache Failover (Redis Sentinel)

# Redis Sentinel configuration
cache-mode,sentinel
cache-sentinel-master,mymaster
cache-sentinel-nodes,sentinel-1:26379,sentinel-2:26379,sentinel-3:26379

Circuit Breaker

Prevent cascade failures:

# Circuit breaker settings
circuit-breaker-enabled,true
circuit-breaker-threshold,5
circuit-breaker-timeout,30
circuit-breaker-half-open-requests,3

States:

• Closed: Normal operation
• Open: Failing, reject requests immediately
• Half-Open: Testing if service recovered

Graceful Degradation

Configure fallback behavior:

# Fallback configuration
fallback-llm-enabled,true
fallback-llm-provider,local
fallback-llm-model,DeepSeek-R3-Distill-Qwen-1.5B

fallback-cache-enabled,true
fallback-cache-mode,memory

fallback-vectordb-enabled,true
fallback-vectordb-mode,keyword-search

Monitoring Scaling

Metrics Collection

Key metrics to monitor:

# Scaling metrics
metrics-scaling-enabled,true
metrics-container-count,true
metrics-scaling-events,true
metrics-load-distribution,true

Alerting Rules

Configure alerts for scaling issues:

# alerting-rules.yml
groups:
  - name: scaling
    rules:
      - alert: HighCPUUsage
        expr: avg(cpu_usage) > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage detected"
          
      - alert: MaxInstancesReached
        expr: container_count >= max_instances
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Maximum instances reached, cannot scale up"
          
      - alert: ScalingFailed
        expr: scaling_errors > 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Scaling operation failed"

Best Practices

Scaling

1. Start small - Begin with auto-scaling disabled, monitor patterns first
2. Set appropriate thresholds - Too low causes thrashing, too high causes poor performance
3. Use cooldown periods - Prevent rapid scale up/down cycles
4. Test failover - Regularly test your failover procedures
5. Monitor costs - More instances = higher infrastructure costs

Load Balancing

1. Use sticky sessions for WebSockets - Required for real-time features
2. Enable health checks - Remove unhealthy instances automatically
3. Configure timeouts - Prevent hanging connections
4. Use connection pooling - Reduce connection overhead

Sharding

1. Choose the right strategy - Tenant-based is simplest for SaaS
2. Plan for rebalancing - Have procedures to move data between shards
3. Avoid cross-shard queries - Design to minimize these
4. Monitor shard balance - Uneven distribution causes hotspots

Next Steps

• Container Deployment - LXC container basics
• Architecture Overview - System design
• Monitoring Dashboard - Observe your cluster

Infrastructure Design

This chapter covers the complete infrastructure design for General Bots, including scaling, security, secrets management, observability, and high availability.

Architecture Overview

General Bots uses a modular architecture where each component runs in isolated LXC containers. This provides isolation where each service has its own filesystem and process space, scalability through adding more containers to handle increased load, security since compromised components cannot affect others, and portability allowing containers to move between hosts easily.

Component Diagram

High Availability Architecture

Production-ready infrastructure with automatic scaling, load balancing, and multi-tenant isolation.

Encryption at Rest

All data stored by General Bots is encrypted at rest using AES-256-GCM.

Database Encryption

PostgreSQL uses Transparent Data Encryption (TDE):

# config.csv
encryption-at-rest,true
encryption-algorithm,aes-256-gcm
encryption-key-source,vault

Enable in PostgreSQL:

-- Enable pgcrypto extension
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Encrypted columns use pgp_sym_encrypt
ALTER TABLE bot_memories 
ADD COLUMN value_encrypted bytea;

UPDATE bot_memories 
SET value_encrypted = pgp_sym_encrypt(value, current_setting('app.encryption_key'));

File Storage Encryption

MinIO server-side encryption is enabled using SSE-S3 for automatic encryption or SSE-C for customer-managed keys:

# Enable SSE-S3 encryption
mc encrypt set sse-s3 local/gbo-bucket

# Or use customer-managed keys (SSE-C)
mc encrypt set sse-c local/gbo-bucket

Configuration:

# config.csv
drive-encryption,true
drive-encryption-type,sse-s3
drive-encryption-key,vault:gbo/encryption/drive_key

Redis Encryption

Redis with TLS and encrypted RDB provides secure caching:

# redis.conf
tls-port 6379
port 0
tls-cert-file /opt/gbo/conf/certificates/redis/server.crt
tls-key-file /opt/gbo/conf/certificates/redis/server.key
tls-ca-cert-file /opt/gbo/conf/certificates/ca.crt

# Enable RDB encryption (Redis 7.2+)
rdb-save-incremental-fsync yes

Vector Database Encryption

Qdrant with encrypted storage uses TLS for transport and filesystem-level encryption for data at rest:

# qdrant/config.yaml
storage:
  storage_path: /opt/gbo/data/qdrant
  on_disk_payload: true
  
service:
  enable_tls: true
  
# Disk encryption handled at filesystem level

Filesystem-Level Encryption

For comprehensive encryption, use LUKS on the data partition:

# Create encrypted partition for /opt/gbo/data
cryptsetup luksFormat /dev/sdb1
cryptsetup open /dev/sdb1 gbo-data
mkfs.ext4 /dev/mapper/gbo-data
mount /dev/mapper/gbo-data /opt/gbo/data

Media Processing: LiveKit

LiveKit handles all media processing needs for General Bots. WebRTC is native to LiveKit. Recording is built-in via the Egress service. Transcoding uses the Egress service. Streaming and AI integration are built into LiveKit.

LiveKit’s Egress service handles room recording, participant recording, livestreaming to YouTube and Twitch, and track composition.

LiveKit Configuration

# config.csv
meet-provider,livekit
meet-server-url,wss://localhost:7880
meet-api-key,vault:gbo/meet/api_key
meet-api-secret,vault:gbo/meet/api_secret
meet-recording-enabled,true
meet-transcription-enabled,true

Messaging: Redis

General Bots uses Redis for all messaging needs including session state, PubSub for real-time communication, and Streams for persistence:

#![allow(unused)]
fn main() {
// Session state
redis::cmd("SET").arg("session:123").arg(state_json)

// PubSub for real-time
redis::cmd("PUBLISH").arg("channel:bot-1").arg(message)

// Streams for persistence (optional)
redis::cmd("XADD").arg("stream:events").arg("*").arg("event").arg(data)
}

Configuration:

# config.csv
messaging-provider,redis
messaging-persistence,streams
messaging-retention-hours,24

Sharding Strategies

Option 1: Tenant-Based Sharding (Recommended)

Each tenant or organization gets isolated databases.

Multi-Tenant Architecture

Each tenant gets isolated resources with dedicated database schemas, cache namespaces, and vector collections. The router maps tenant IDs to their respective data stores automatically.

Key isolation features include database-per-tenant or schema-per-tenant options, namespace isolation in Valkey cache, collection isolation in Qdrant vectors, and bucket isolation in SeaweedFS storage.

Configuration:

# config.csv
shard-strategy,tenant
shard-auto-provision,true
shard-isolation-level,database

Advantages include complete data isolation which is compliance friendly, easy backup and restore per tenant, simplicity, and no cross-tenant queries. Disadvantages include more resources per tenant, complex tenant migration, and connection pool overhead.

Option 2: Hash-Based Sharding

Distribute by user or session ID hash. For example, a user_id of 12345 produces a hash that modulo num_shards equals 2, routing to shard-2.

Configuration:

# config.csv
shard-strategy,hash
shard-count,4
shard-key,user_id
shard-algorithm,consistent-hash

Advantages include even distribution, predictable routing, and good performance for high-volume single-tenant deployments. Disadvantages include complex resharding, difficult cross-shard queries, and no tenant isolation.

Option 3: Time-Based Sharding

For time-series data like logs and analytics:

# config.csv
shard-strategy,time
shard-interval,monthly
shard-retention-months,12
shard-auto-archive,true

This automatically creates partitions named messages_2024_01, messages_2024_02, messages_2024_03, and so on.

Option 4: Geographic Sharding

Route by user location:

# config.csv
shard-strategy,geo
shard-regions,us-east,eu-west,ap-south
shard-default,us-east
shard-detection,ip

Geographic Distribution

The global router uses GeoIP to direct users to the nearest regional cluster. US-East in Virginia runs a full cluster, EU-West in Frankfurt runs a full cluster, and AP-South in Singapore runs a full cluster. Each regional cluster runs independently with data replication between regions for disaster recovery.

Auto-Scaling with LXC

Configuration

# config.csv - Auto-scaling settings
scale-enabled,true
scale-min-instances,1
scale-max-instances,10
scale-cpu-threshold,70
scale-memory-threshold,80
scale-request-threshold,1000
scale-cooldown-seconds,300
scale-check-interval,30

Scaling Rules

Auto-Scale Service

The auto-scaler runs as a systemd service:

# /etc/systemd/system/gbo-autoscale.service
[Unit]
Description=General Bots Auto-Scaler
After=network.target

[Service]
Type=simple
ExecStart=/opt/gbo/scripts/autoscale.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Container Lifecycle

The startup flow begins with creating the LXC container from a template, then configuring resources for CPU, memory, and storage, then starting the botserver binary, and finally marking the container as ready and adding it to the load balancer pool.

The shutdown flow begins with an active container serving requests, then draining to stop accepting new connections, then stopping with a graceful botserver shutdown, and finally deleting or returning the container to the pool.

Load Balancing

Caddy Configuration

{
    admin off
    auto_https on
}

bot.example.com {
    # Rate limiting
    rate_limit {
        zone api {
            key {remote_host}
            events 100
            window 1m
        }
    }
    
    # WebSocket (sticky sessions)
    handle /ws* {
        reverse_proxy botserver-1:9000 botserver-2:9000 {
            lb_policy cookie
            health_uri /api/health
            health_interval 10s
        }
    }
    
    # API (round robin)
    handle /api/* {
        reverse_proxy botserver-1:9000 botserver-2:9000 {
            lb_policy round_robin
            fail_duration 30s
        }
    }
}

Rate Limiting Configuration

# config.csv - Rate limiting
rate-limit-enabled,true
rate-limit-requests,100
rate-limit-window,60
rate-limit-burst,20
rate-limit-by,ip

# Per-endpoint limits
rate-limit-api-chat,30
rate-limit-api-files,50
rate-limit-api-auth,10
rate-limit-api-llm,20

Failover Systems

Health Checks

Every service exposes /health:

{
  "status": "healthy",
  "version": "6.1.0",
  "checks": {
    "database": {"status": "ok", "latency_ms": 5},
    "cache": {"status": "ok", "latency_ms": 2},
    "vectordb": {"status": "ok", "latency_ms": 10},
    "llm": {"status": "ok", "latency_ms": 50}
  }
}

Circuit Breaker

# config.csv
circuit-breaker-enabled,true
circuit-breaker-threshold,5
circuit-breaker-timeout,30
circuit-breaker-half-open-requests,3

The circuit breaker has three states. Closed represents normal operation while counting failures. Open means failing fast and returning errors immediately. Half-Open tests with limited requests before deciding to close or reopen.

Database Failover

PostgreSQL with streaming replication provides high availability.

Database Replication

PostgreSQL replication is managed by Patroni for automatic failover. The Primary serves as the write leader handling all write operations. The Replica provides synchronous replication from the primary for read scaling. Patroni acts as the failover manager performing automatic leader election on failure.

Failover happens automatically within seconds, with clients redirected via the connection pooler.

Graceful Degradation

# config.csv - Fallbacks
fallback-llm-enabled,true
fallback-llm-provider,local
fallback-llm-model,DeepSeek-R3-Distill-Qwen-1.5B

fallback-cache-enabled,true
fallback-cache-mode,memory

fallback-vectordb-enabled,true
fallback-vectordb-mode,keyword-search

Secrets Management (Vault)

Architecture

The minimal .env file contains only Vault connection details. All other secrets are stored in Vault and fetched at runtime. The Vault server stores secrets organized by path including gbo/drive for access keys, gbo/tables for database credentials, gbo/cache for passwords, gbo/directory for client credentials, gbo/email for mail credentials, gbo/llm for provider API keys, gbo/encryption for master and data keys, and gbo/meet for API credentials.

Zitadel vs Vault

Zitadel handles user authentication, OAuth/OIDC, and MFA. Vault handles service credentials, API keys, and encryption keys. Use both together where Zitadel manages user identity and SSO while Vault manages service secrets and encryption keys.

Minimal .env with Vault

# .env - Only Vault and Directory needed
VAULT_ADDR=https://localhost:8200
VAULT_TOKEN=hvs.your-token-here

# Directory for user auth (Zitadel)
DIRECTORY_URL=https://localhost:9000
DIRECTORY_CLIENT_ID=your-client-id
DIRECTORY_CLIENT_SECRET=your-client-secret

# All other secrets fetched from Vault at runtime

Observability

Option 1: InfluxDB + Grafana (Current)

For time-series metrics:

# config.csv
observability-provider,influxdb
observability-url,http://localhost:8086
observability-org,pragmatismo
observability-bucket,metrics

Option 2: Vector + InfluxDB (Recommended)

Vector serves as a log and metric aggregator. botserver logs flow to Vector which pipelines them to InfluxDB for metrics storage and Grafana for dashboards.

Vector configuration:

# vector.toml
[sources.botserver_logs]
type = "file"
include = ["/opt/gbo/logs/*.log"]

[transforms.parse_logs]
type = "remap"
inputs = ["botserver_logs"]
source = '''
. = parse_json!(.message)
'''

[sinks.influxdb]
type = "influxdb_metrics"
inputs = ["parse_logs"]
endpoint = "http://localhost:8086"
org = "pragmatismo"
bucket = "metrics"

Replacing log.* Calls with Vector

Instead of replacing all log calls, configure Vector to collect logs from files, parse and enrich them, and route to appropriate sinks:

# Route errors to alerts
[transforms.filter_errors]
type = "filter"
inputs = ["parse_logs"]
condition = '.level == "error"'

[sinks.alertmanager]
type = "http"
inputs = ["filter_errors"]
uri = "http://alertmanager:9093/api/v1/alerts"

Search: Qdrant

Qdrant handles all search needs in General Bots, providing both vector similarity search for semantic queries and payload filtering for keyword-like queries.

Hybrid Search with Qdrant

Qdrant supports hybrid search combining vector similarity with keyword filters:

#![allow(unused)]
fn main() {
// Combine vector similarity + keyword filter
let search_request = SearchPoints {
    collection_name: "kb".to_string(),
    vector: query_embedding,
    limit: 10,
    filter: Some(Filter {
        must: vec![
            Condition::Field(FieldCondition {
                key: "content".to_string(),
                r#match: Some(Match::Text("keyword".to_string())),
            }),
        ],
        ..Default::default()
    }),
    ..Default::default()
};
}

Workflow Scheduling: SET SCHEDULE

General Bots uses the SET SCHEDULE keyword for all scheduling needs:

REM Run every day at 9 AM
SET SCHEDULE "daily-report" TO "0 9 * * *"
    TALK "Running daily report..."
    result = GET "/api/reports/daily"
    SEND MAIL "admin@example.com", "Daily Report", result
END SCHEDULE

MFA with Zitadel

Configuration

MFA is handled transparently by Zitadel:

# config.csv
auth-mfa-enabled,true
auth-mfa-methods,totp,sms,email,whatsapp
auth-mfa-required-for,admin,sensitive-operations
auth-mfa-grace-period-days,7

Zitadel MFA Settings

In the Zitadel console, navigate to Settings then Login Behavior. Enable Multi-Factor Authentication and select allowed methods including TOTP for authenticator apps, SMS, Email, and WebAuthn/FIDO2.

WhatsApp MFA Channel

# config.csv
auth-mfa-whatsapp-enabled,true
auth-mfa-whatsapp-provider,twilio
auth-mfa-whatsapp-template,mfa_code

The flow proceeds as follows: the user logs in with password, Zitadel triggers MFA, a code is sent via WhatsApp, the user enters the code, and the session is established.

Summary: What You Need

PostgreSQL, Redis, Qdrant, MinIO, and Zitadel are required components. Vault, InfluxDB, and LiveKit are recommended for production deployments. Vector is optional for log aggregation.

Next Steps

The Scaling and Load Balancing chapter provides a detailed scaling guide. The Container Deployment chapter covers LXC setup. The Security Features chapter offers a security deep dive. The LLM Providers appendix helps with model selection.

Observability

This chapter describes the observability infrastructure that General Bots provides for monitoring system health, collecting logs, and tracking metrics. The observability system operates automatically without requiring code changes, giving administrators visibility into platform behavior and helping identify issues before they impact users.

Understanding the Observability System

General Bots implements observability through an integrated pipeline that collects, parses, routes, and stores operational data from all system components. The pipeline reads log files from the centralized logs directory within the botserver-stack folder, extracts structured information including log levels, timestamps, and messages, routes different types of data to appropriate destinations such as alerts for errors and storage for metrics, and enriches entries with contextual information like hostnames and service names.

This automated approach means administrators don’t need to instrument code or configure complex logging frameworks. The system captures operational data from all components using consistent formats and routes it to useful destinations without manual intervention.

Log Directory Organization

The logging system organizes output by component within the ./botserver-stack/logs/ directory. System logs from the main botserver application appear in the system subdirectory. Storage service operations are captured in the drive subdirectory. Database activity from PostgreSQL goes to the tables subdirectory. The cache subdirectory contains logs from the caching layer. LLM server interactions are recorded in the llm subdirectory.

Additional services have their own logging locations. Email service logs appear in the email subdirectory. Identity and authentication events are captured in the directory subdirectory. Vector database operations go to the vectordb subdirectory. Video meeting activities are logged in the meet subdirectory.

This organization makes it straightforward to investigate issues in specific components without wading through unrelated log entries.

Installation and Configuration

The observability component installs automatically during the bootstrap process, ensuring that monitoring begins from the first system start. Administrators who need to install it separately can use the botserver install command with the observability parameter.

Configuration for the observability pipeline resides in the monitoring configuration file within the botserver-stack conf directory. This Vector configuration file controls how logs are collected, parsed, transformed, and routed to their destinations.

Log Format Conventions

botserver generates logs in a standard format that includes the timestamp in ISO 8601 format with millisecond precision, the log level indicating severity, the module path identifying the code location, and the message describing what occurred. This structured format enables automated parsing while remaining human-readable for direct inspection.

The pipeline parses these logs automatically, extracting fields for indexing and routing. Errors are identified by level and routed to alerting systems while informational messages flow to long-term storage for historical analysis.

Metrics Collection

The platform exposes operational metrics through a Prometheus-compatible endpoint at /api/metrics, enabling integration with standard monitoring infrastructure. Available metrics track log event counts by severity level, error totals broken down by service, currently active session counts, total messages processed since startup, and LLM response latency measurements.

These metrics enable administrators to understand system behavior over time, identify trends that might indicate developing problems, and verify that the platform operates within expected parameters. The Prometheus format ensures compatibility with common visualization and alerting tools.

Alerting Configuration

The observability system can send alerts automatically when error conditions occur. Webhook alerts POST event data to the admin alerts API endpoint, enabling integration with custom alerting systems. Slack integration sends notifications to configured channels when properly configured. Email alerts reach administrators directly when SMTP settings are provided.

Alert thresholds are configurable through the bot’s config.csv file. The CPU threshold setting triggers alerts when processor utilization exceeds the specified percentage. Memory threshold configuration works similarly for RAM usage. Response time thresholds flag slow operations that might indicate performance degradation.

Tuning these thresholds for your environment prevents alert fatigue from false positives while ensuring genuine issues receive attention.

Dashboard Visualization

A pre-built Grafana dashboard template is available in the templates directory, providing immediate visualization of key metrics. The dashboard includes panels for active sessions showing current load, messages per minute indicating throughput, error rates highlighting problems, and LLM latency percentiles revealing AI response performance.

Importing this dashboard into a Grafana instance connected to your metrics storage creates an operational overview suitable for operations teams and helps during incident investigation.

Log Level Configuration

The logging system supports four severity levels that control which messages are captured and the volume of output generated.

Error level captures failures that require attention, such as database connection losses or file permission problems. Warning level records unexpected conditions that were handled but might indicate developing issues. Info level logs normal operations and key events, providing a record of system activity without excessive detail. Debug level includes detailed flow information useful during development and troubleshooting but too verbose for normal production operation.

The log level setting in config.csv controls the minimum severity that produces output. Setting it to info captures everything except debug messages, providing operational visibility without overwhelming log storage.

Troubleshooting Common Issues

When logs aren’t being collected as expected, several common causes should be investigated. First, verify that the observability service is running and hasn’t crashed or been stopped. Second, check that the log directory permissions allow the collection process to read the files. Third, review the observability service’s own logs for errors that might explain the collection failure.

High log volume can overwhelm storage and make analysis difficult. Raising the log level from debug to info significantly reduces volume by eliminating detailed trace messages. Configuring retention policies in the metrics storage prevents unbounded growth. Filtering debug-level logs before they reach long-term storage reduces costs while preserving important operational data.

Operational Guidelines

Effective observability requires attention to both technical configuration and operational practices. Log content should never include sensitive data like passwords, tokens, or personally identifiable information, as logs often flow to systems with broader access than the application itself.

Using appropriate log levels keeps signal-to-noise ratios manageable. Reserve error level for actual failures requiring investigation. Use info level for normal operations that help understand system behavior. Avoid overusing warning level, which loses meaning when applied too broadly.

Monitoring should focus on trends rather than just instantaneous values. Gradual increases in error rates or response times often indicate developing problems before they become critical failures. Alert configuration should consider baseline behavior and flag deviations rather than simple threshold crossings.

Establishing observability early in deployment ensures that baseline data exists when problems occur. Trying to instrument a system during an incident rarely produces useful results.

Related Documentation

For additional context on operating General Bots at scale, the Scaling and Load Balancing chapter explains how observability integrates with clustered deployments. The Infrastructure Design chapter provides the full architectural overview showing how observability fits into the complete system. The Monitoring Dashboard section describes the built-in monitoring interface available through the administrative UI.

Monitoring Setup

Autonomous Task AI

The Machine Does the Work

Overview

Autonomous Tasks let you describe what you want and the system builds it. No coding required - just describe your application in plain language.

You say:

“Create a CRM for my cellphone store”

You get:

• Working HTMX application at /apps/cellphone-crm
• Database tables: customers, products, sales, repairs
• Forms, lists, search, filters - all functional
• Direct connection to botserver API

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Your App                                 │
│                                                                  │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐                 │
│   │  Forms   │    │  Lists   │    │  Actions │                 │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘                 │
│        │               │               │                        │
│        └───────────────┼───────────────┘                        │
│                        │ HTMX                                   │
└────────────────────────┼────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      botserver API                               │
│                                                                  │
│   /api/db/*          /api/drive/*         /api/llm/*           │
│   CRUD operations    File storage         AI features           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              PostgreSQL + MinIO + LLM                           │
│              (user_data virtual table)                          │
└─────────────────────────────────────────────────────────────────┘

Key insight: Apps talk directly to botserver. No middleware, no generated backend code - just HTMX calling the API.

The user_data Virtual Table

All app data lives in one flexible table system:

App: cellphone-crm
Table: customers
     │
     ▼
Namespace: cellphone-crm.customers
     │
     ▼
Storage: user_data table with proper indexing

Your app calls /api/db/customers and botserver handles the rest.

Benefits

• No migrations - Tables created on demand
• Isolation - Each app’s data is separate
• Flexibility - Add fields anytime
• Security - Per-app access control

How It Works

1. Describe

Tell the system what you want:

"Create a CRM for my cellphone store with:
- Customer tracking (name, phone, email)
- Product inventory with stock levels
- Sales linked to customers
- Repair status board"

2. Plan

System creates execution steps:

Step 1: Create tables (customers, products, sales, repairs)
Step 2: Generate HTMX application
Step 3: Add search and filters
Step 4: Configure repair workflow

3. Execute

Each step runs and shows progress:

[████████████████░░░░] 75%
Step 3 of 4: Adding search...

4. Deliver

Your app is ready:

✅ Application: /apps/cellphone-crm
✅ Tables: customers, products, sales, repairs
✅ Features: CRUD, search, status board

Generated App Structure

.gbdrive/apps/cellphone-crm/
├── index.html          # HTMX application
├── _assets/
│   ├── htmx.min.js     # HTMX library
│   ├── app.js          # Helpers
│   └── styles.css      # Styling
└── schema.json         # Table definitions

HTMX Patterns

List with Auto-Refresh

<div id="customers"
     hx-get="/api/db/customers"
     hx-trigger="load, every 30s"
     hx-swap="innerHTML">
    Loading...
</div>

Create Form

<form hx-post="/api/db/customers"
      hx-target="#customers"
      hx-swap="afterbegin">
    <input name="name" required>
    <input name="phone">
    <button type="submit">Add</button>
</form>

Search

<input type="search"
       hx-get="/api/db/customers"
       hx-trigger="keyup changed delay:300ms"
       hx-target="#customers"
       placeholder="Search...">

Delete

<button hx-delete="/api/db/customers/${id}"
        hx-target="closest tr"
        hx-confirm="Delete?">
    🗑️
</button>

API Mapping

Query Parameters

?q=john              # Search
?status=active       # Filter
?sort=created_at     # Sort
?order=desc          # Direction
?limit=20&offset=40  # Pagination

Task Steps Storage

Every task stores its steps for:

• Continuation - Resume if interrupted
• Progress - Know exactly where you are
• Debugging - See what happened

{
  "task_id": "abc123",
  "steps": [
    {"order": 1, "name": "Create tables", "status": "completed"},
    {"order": 2, "name": "Generate UI", "status": "running", "progress": 60},
    {"order": 3, "name": "Add search", "status": "pending"}
  ]
}

Execution Modes

Dev Chat Widget

Test your app without leaving the page:

1. Add ?dev=1 to URL or run on localhost
2. Click the floating chat icon (or Ctrl+Shift+D)
3. Talk to modify your app in real-time

<script src="/_assets/dev-chat.js"></script>

The dev chat uses the same user_data system for history storage.

Example: Cellphone Store CRM

Request:

“CRM for cellphone store with customers, products, sales, and repair tracking”

Result:

Features:

• Customer list with search
• Product inventory with stock alerts
• Sales entry form
• Repair status board (Kanban)

Access: /apps/cellphone-crm

Best Practices

Be Specific

✅ Good:

“CRM for cellphone store with customer tracking, sales, and repair status workflow”

❌ Vague:

“Make an app”

Include Workflows

✅ Good:

“Repair status: received → diagnosing → repairing → ready → delivered”

❌ Missing:

“Track repairs”

Mention Relationships

✅ Good:

“Sales linked to customers and products”

❌ Unclear:

“Sales tracking”

See Also

• Autonomous Tasks Chapter - Complete guide
• CREATE SITE - The keyword behind it
• REST API - API reference
• HTMX Architecture - Frontend patterns

The gbapp Philosophy: Let Machines Do Machine Work

Core Principle: Automation First

In 2025, the gbapp philosophy is simple and powerful: if a machine can do the work, let it do the work. This principle guides every decision about how to build and extend General Bots. Rather than writing code manually, you describe what you need and let AI handle the implementation details.

The Hierarchy of Development

The development approach in General Bots follows a clear hierarchy based on what percentage of work falls into each category.

LLM First (90% of cases)

The vast majority of work should be handled by letting AI write the code for you. Instead of implementing complex logic yourself, describe what you want in natural language and let the LLM generate the solution.

' Don't write complex logic - describe what you want
result = LLM "Generate a function that validates email addresses and returns true/false: " + email

BASIC for Flow Control (9% of cases)

BASIC serves as the orchestration layer that connects AI calls together. Think of it as glue code that manages the flow between different operations. The logic itself lives in LLM calls while BASIC handles sequencing and data flow.

' BASIC is just glue between AI calls
data = GET "api/data"
processed = LLM "Process this: " + data
SET "results", processed

Rust for Core Only (1% of cases)

Writing Rust code should be reserved for rare situations where you are contributing new keywords to the core platform, building fundamental infrastructure that many bots will use, or optimizing critical performance paths where every millisecond matters. Most developers will never need to write Rust because BASIC and LLM calls handle nearly every use case.

What gbapp Really Is

Understanding what gbapp is and is not helps clarify the development model.

The gbapp concept is not about external plugin packages that you download separately. It is not about separate npm modules or package managers. It is not a way to bypass BASIC and write custom code. It is not about runtime extensions that modify behavior dynamically.

Instead, gbapp represents virtual crates inside the src/ directory that are Rust modules compiling together into a single binary. The concept serves as a bridge between older plugin-based thinking and the modern integrated approach. It provides a familiar mental model for developers who want to contribute to the platform. Most importantly, gbapp embodies a mindset of coding through automation rather than manual implementation.

Real-World Examples

The contrast between traditional development and the General Bots approach becomes clear through examples.

Traditional Approach

In the old way of thinking, you might write hundreds of lines of custom Node.js, Python, or C# code for data validation. A function like validateComplexBusinessRules would contain extensive logic handling edge cases, format checking, and business rule verification. This code requires maintenance, testing, and documentation.

The General Bots Approach

With the automation-first philosophy, the same task takes three lines. You fetch your business rules from a file, ask the LLM to validate data against those rules, and handle the result. The AI understands the rules and applies them correctly without you implementing the validation logic.

' 3 lines - let AI handle complexity
rules = GET "business-rules.txt"
validation = LLM "Validate this data against these rules: " + data + " Rules: " + rules
IF validation CONTAINS "valid" THEN TALK "Approved" ELSE TALK "Rejected: " + validation

The Multi-SDK Reality

You do not need separate SDKs or plugins for different services. Everything integrates through BASIC combined with LLM calls.

Integrating Any API

When you need to work with an external API, you do not need to find and install an SDK. Just fetch the data and let the LLM interpret and format it.

' No SDK needed - just describe what you want
data = GET "https://server/data"
answer = LLM "Do a good report from this json: " + data
TALK answer

Working with Any Database

Database operations do not require an ORM or query builder. The AI understands SQL and can generate queries from natural language descriptions.

' No ORM needed - AI understands SQL
results = FIND "users", "all users who logged in today"

Processing Any Format

You do not need parser libraries for different file formats. The LLM can transform data between formats based on your description.

' No parser library needed
xml_data = GET "complex.xml"
json = LLM "Convert this XML to JSON: " + xml_data
SET BOT MEMORY "processed_data", json

When to Write Code

Understanding when each approach applies helps you work efficiently.

Use LLM When

LLM calls are appropriate for processing unstructured data, implementing business logic, transforming between formats, making decisions, generating content, and analyzing patterns. This covers roughly ninety percent of everything you might want to do.

Use BASIC When

BASIC code handles orchestrating AI calls in sequence, simple flow control with conditionals and loops, managing state and variables, and connecting different systems together. Think of BASIC as the glue that holds everything together.

Use Rust When

Rust development is only necessary when building new keywords that will become part of the core platform, creating a new gbapp module in the src/ directory, performing system-level optimization for critical paths, or contributing new features that will benefit all users. Almost no one needs to write Rust for their bots.

The gbapp Mindset

Shifting your thinking is the most important part of adopting this philosophy.

Stop thinking about how to code a solution, what library you need to import, or how to extend the system with plugins. Start thinking about how to describe what you want to AI, what the simplest BASIC flow looks like, and how your patterns could help everyone using the platform.

Data Enrichment Example

Consider a data enrichment task that pulls information about companies from their websites.

The traditional approach requires over a thousand lines of code spread across multiple npm packages. You need complex error handling for network requests, HTML parsing for different website structures, and a maintenance nightmare as websites change their formats.

The General Bots approach handles the same task in a few lines. You find companies that need enrichment, loop through them, fetch each website, ask the LLM to extract company information, and save the results. The AI handles all the complexity of parsing different website formats.

items = FIND "companies", "needs_enrichment=true"
FOR EACH item IN items
    website = WEBSITE OF item.company
    page = GET website
    enriched = LLM "Extract company info from: " + page
    SET "companies", "id=" + item.id, "data=" + enriched
NEXT

Report Generation Example

Generating reports traditionally requires a custom reporting engine, template systems, complex formatting logic, and PDF libraries. That infrastructure takes significant development and ongoing maintenance.

With General Bots, you find the relevant data, ask the LLM to create an executive summary, and generate a site with the results. Three lines replace an entire reporting infrastructure.

data = FIND "sales", "month=current"
report = LLM "Create executive summary from: " + data
CREATE SITE "report", "template", report

The Ultimate Test

Before writing any code, ask yourself three questions in order. First, can the LLM do this? The answer is usually yes. Second, can BASIC orchestrate it? Almost always yes. Third, do you really need Rust? Almost never.

Only proceed to writing custom code if you have genuinely exhausted the first two options. The LLM and BASIC combination handles far more than most developers initially expect.

Benefits of This Approach

For Developers

This approach enables development that is roughly one hundred times faster than traditional coding. You have no dependency management headaches and no version conflicts between packages. The maintenance burden drops dramatically because there is no custom code to maintain. You can focus on business logic and what you want to accomplish rather than implementation details.

For Organizations

Organizations benefit from reduced complexity in their bot deployments. Maintenance costs drop because there is less custom code to support. Iterations happen faster since changes involve modifying descriptions rather than rewriting code. There is no vendor lock-in to specific libraries or frameworks. Anyone in the organization can contribute because they do not need traditional programming skills.

For the Community

Shared improvements benefit everyone using the platform. There is no fragmentation into incompatible plugin ecosystems. Users experience consistency across different bots and deployments. The community advances collectively rather than each organization maintaining separate extensions.

The Future is Already Here

In 2025, this approach is not aspirational but reality. Applications built entirely with BASIC and LLM calls run in production today. Most use cases require zero custom code. AI handles complexity better than hand-written algorithms in many domains. Machines do machine work while humans focus on human work like understanding requirements and making decisions.

Migration Path

From Extensions to Virtual Crates

If you have existing plugin-style extensions, the migration path consolidates them into the main source tree. An old extension might have been a separate folder with hundreds of lines of JavaScript, a package.json, and complex logic. The new approach places a small Rust module in src/ that registers BASIC keywords, while the actual logic moves to a few lines of BASIC in your .gbdialog folder that leverage LLM calls.

From Code to Descriptions

Migration from traditional code involves converting algorithms into natural language descriptions. Instead of writing the logic to process data, you describe what processing you need and let the LLM implement it.

From Libraries to LLM

Instead of importing twenty npm packages for various functionality, you make single LLM calls with descriptions of what you need. The AI has knowledge of countless libraries and formats built into its training.

Development Guidelines

Follow these practices to work effectively with the automation-first philosophy. Describe problems to the LLM in clear, specific terms. Use BASIC as minimal glue between AI operations. Contribute keywords to the core when you discover patterns that would benefit everyone. Share your patterns with the community so others can learn. Think automation-first for every task you encounter.

Avoid common mistakes that fight against this philosophy. Do not write complex algorithms when a description would suffice. Do not build separate plugins that fragment the ecosystem. Do not create custom frameworks that add unnecessary complexity. Do not maintain separate codebases when everything should be in one place. Do not fight the machine by insisting on manual implementation.

The Virtual Crate Architecture

Each gbapp is now a module in the src/ directory. The structure maps conceptually familiar package names to Rust modules. The core gbapp lives in src/core/. The BASIC interpreter is src/basic/. Channel adapters are in src/channels/. Your contribution would go in src/your_feature/. This elegant mapping preserves the conceptual model of separate packages while leveraging Rust’s module system and compiling everything into a single optimized binary.

Conclusion

The gbapp concept in 2025 has evolved from external packages to virtual crates. These Rust modules inside src/ compile into a single, optimized binary while preserving the familiar mental model of separate functional packages.

The philosophy remains constant: machines are better at machine work. Your job is to describe what you want, not implement how to do it. The combination of BASIC for orchestration and LLM for logic eliminates the need for traditional programming in almost all cases.

Examples Repository

The /templates/ directory contains real-world examples of applications built entirely with BASIC and LLM calls. A CRM system requires about fifty lines of BASIC. Email automation needs around thirty lines. Data pipelines work in twenty lines. Report generators take about fifteen lines. Each of these would have required thousands of lines of traditional code, demonstrating the dramatic productivity improvement this philosophy enables.

.gbai Architecture

A bot is just a folder. The .gbai extension marks a directory as a botserver package containing everything needed to run a conversational AI bot - scripts, documents, configuration, and themes.

The Dead Simple Structure

my-bot.gbai/                    # This folder = your entire bot
  my-bot.gbdialog/           # BASIC conversation scripts
  my-bot.gbkb/               # Documents for Q&A
  my-bot.gbot/               # Configuration
  my-bot.gbtheme/            # Optional UI customization

That’s it. No manifests, no build files, no dependencies. Copy the folder to deploy.

Visual Architecture

Architecture

How Bootstrap Finds Bots

At startup, botserver scans templates/ for any folder ending in .gbai:

templates/
  default.gbai/       → Creates bot at /default
  support.gbai/       → Creates bot at /support  
  sales.gbai/         → Creates bot at /sales

Each .gbai becomes a URL endpoint automatically. Zero configuration.

What Goes Where

.gbdialog/ - Your Bot’s Brain

BASIC scripts that control conversation flow:

my-bot.gbdialog/
  start.bas           # Optional - needed to activate tools/KB
  auth.bas            # Login flow
  tools/              # Callable functions
    book-meeting.bas
    check-status.bas
  handlers/           # Event responses
    on-email.bas

Example start.bas (optional, but required for tools/KB):

USE KB "policies"
USE TOOL "book-meeting"
USE TOOL "check-status"
TALK "Hi! I'm your assistant with tools and knowledge ready."

Note: If you don’t need tools or knowledge bases, start.bas is optional. The LLM will handle basic conversations without it.

.gbkb/ - Your Bot’s Knowledge

Documents organized by topic:

my-bot.gbkb/
  policies/           # HR documents
    vacation.pdf
    handbook.docx
  products/           # Product info
    catalog.pdf
    pricing.xlsx
  support/            # Help docs
    faq.md

Each folder becomes a searchable collection. Drop files in, bot learns automatically.

.gbot/ - Your Bot’s Settings

Single config.csv file with key-value pairs:

llm-model,your-preferred-model
temperature,0.7
max-tokens,2000
welcome-message,Hello! How can I help?
session-timeout,1800

No complex JSON or YAML. Just simple CSV that opens in Excel.

.gbtheme/ - Your Bot’s Look (Optional)

Custom web interface styling:

my-bot.gbtheme/
  styles.css          # Custom CSS
  logo.png           # Brand assets
  templates/         # HTML overrides
    chat.html

If missing, uses default theme. Most bots don’t need this.

Real Example: Support Bot

Here’s a complete customer support bot:

support.gbai/
  support.gbdialog/
    start.bas         # Optional, but needed for tools/KB
    tools/
      create-ticket.bas
      check-status.bas
  support.gbkb/
    faqs/
      common-questions.pdf
    guides/
      troubleshooting.docx
  support.gbot/
    config.csv

start.bas (activates tools and knowledge bases):

USE KB "faqs"
USE KB "guides"
USE TOOL "create-ticket"
USE TOOL "check-status"

TALK "Support bot ready. How can I help?"

create-ticket.bas:

PARAM issue, priority
DESCRIPTION "Creates support ticket"

ticket_id = GENERATE_ID()
SAVE "tickets.csv", ticket_id, issue, priority, NOW()
TALK "Ticket #" + ticket_id + " created"

config.csv:

llm-model,your-preferred-model
bot-name,TechSupport
greeting,Welcome to support!

Deployment = Copy Folder

Local Development

cp -r my-bot.gbai/ templates/
./botserver restart
# Visit http://localhost:9000/my-bot

Production Server

scp -r my-bot.gbai/ server:~/botserver/templates/
ssh server "cd botserver && ./botserver restart"

Deployment

LXC Container

lxc file push my-bot.gbai/ container/app/templates/

No build step. No compilation. Just copy files.

Multi-Bot Hosting

One botserver runs multiple bots:

templates/
  support.gbai/       # support.example.com
  sales.gbai/         # sales.example.com
  internal.gbai/      # internal.example.com
  public.gbai/        # www.example.com

Each bot:

• Gets own URL endpoint
• Has isolated sessions
• Runs independently
• Shares infrastructure

Naming Conventions

Required

• Folder must end with .gbai
• Subfolders must match: botname.gbdialog, botname.gbkb, etc.
• start.bas is optional, but required if you want to use tools or knowledge bases (must USE TOOL and USE KB to activate them)

Recommended

• Use lowercase with hyphens: customer-service.gbai
• Group related bots: support-tier1.gbai, support-tier2.gbai
• Version in folder name if needed: chatbot-v2.gbai

Bootstrap Process

When botserver starts:

Takes about 5-10 seconds per bot.

UI Architecture

The web interface uses HTMX with server-side rendering - minimal client-side code:

• Askama templates for HTML generation
• HTMX for dynamic updates without JavaScript
• No webpack, no npm build
• Edit and refresh to see changes
• Zero compilation time

Package Size Limits

Default limits (configurable in config.csv):

Example override in your bot’s config.csv:

name,value
package-max-size,209715200
user-file-limit,52428800

Troubleshooting

Bot not appearing?

• Check folder ends with .gbai
• Verify subfolders match bot name
• If using tools/KB, ensure start.bas exists with USE TOOL/USE KB commands

Documents not searchable?

• Ensure files are in .gbkb/ subfolder
• Check file format is supported
• Wait 30 seconds for indexing

Scripts not running?

• Validate BASIC syntax
• Check file has .bas extension
• Review logs for errors

Best Practices

Do’s

• Keep packages under 50MB
• Organize knowledge by topic
• Use clear folder names
• Test locally first

Don’ts

• Don’t nest .gbai folders
• Don’t mix test/prod in same folder
• Don’t hardcode absolute paths
• Don’t store secrets in scripts

Summary

The .gbai architecture keeps bot development simple. No complex frameworks, no build systems, no deployment pipelines. Just organize your files in folders, and botserver handles the rest. Focus on content and conversation, not configuration.

Next: Learn about .gbdialog Dialogs for writing conversation scripts.

.gbdialog Dialogs

The .gbdialog 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:

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 for complete documentation.

What is .gbdialog?

.gbdialog files are written in a specialized BASIC dialect that controls:

• Tool execution and integrations
• LLM prompting and context
• Knowledge base activation
• Session and memory management
• External API calls

Modern Approach: Let the LLM Work

Minimal BASIC Philosophy

Instead of complex logic, use the LLM’s natural understanding:

' Example from announcements.gbai/update-summary.bas
' Generate summaries from documents
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume

' Example from law.gbai/case.bas
' Load context and let LLM answer questions
text = GET "case-" + cod + ".pdf"
text = "Based on this document, answer the person's questions:\n\n" + text
SET CONTEXT text
TALK "Case loaded. You can ask me anything about the case."

Key Components

1. LLM Integration

' LLM is for background processing only - generates content once for all users
' Example: Generate a summary that all users will see
text = GET "document.pdf"
summary = LLM "Summarize this document: " + text
SET BOT MEMORY "daily_summary", summary

' For interactive conversations, use SET CONTEXT and TALK
SET CONTEXT "user_type" AS "premium customer"
TALK "How can I help you today?"

2. Tool Execution

' Define tools with parameters
PARAM name AS string LIKE "John Smith" DESCRIPTION "Customer name"
PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email"

' LLM automatically knows when to call this
SAVE "customers.csv", name, email
TALK "Registration complete!"

3. Knowledge Base Usage

See Knowledge Base documentation for details.

' Activate knowledge base collections
USE KB "products"
USE KB "policies"

' The system AI searches these automatically during conversations
' No LLM command needed - just TALK to the user
TALK "What product information can I help you with?"

Script Structure

Entry Point: start.bas (Optional)

The start.bas file in the .gbdialog folder is optional, but required if you want to activate tools or knowledge bases:

' Optional start script - needed only to activate tools/KB
USE KB "company_docs"
USE TOOL "book-meeting"
USE TOOL "check-status"
TALK "Welcome! How can I assist you today?"

When you need start.bas:

• To activate knowledge bases with USE KB
• To activate tools with USE TOOL
• To set initial context or configuration

When you don’t need start.bas:

• For simple conversational bots
• When the LLM can handle everything without tools/KB
• For basic Q&A without document search

Tool Definitions

Create separate .bas files for each tool. See KB and Tools for more information:

' enrollment.bas - The LLM knows when to use this
PARAM student_name AS string
PARAM course AS string
DESCRIPTION "Enrolls a student in a course"

SAVE "enrollments.csv", student_name, course, NOW()
TALK "Enrolled successfully!"

Best Practices

1. Minimal Logic

' Good - Let system AI handle the conversation naturally
TALK "How can I help you?"
' System AI understands context and responds appropriately

' Avoid - Don't micromanage the flow
' IF user_says_this THEN do_that...

2. Clear Tool Descriptions

DESCRIPTION "This tool books appointments for customers"
' The LLM uses this description to know when to call the tool

3. Context Over Conditions

' Provide context, not rules
SET CONTEXT "business_hours" AS "9AM-5PM weekdays"
TALK "When would you like to schedule?"
' System AI naturally understands to mention hours when relevant

4. Trust the System AI

' The system AI handles conversations naturally
TALK "Hello! I'm here to help."
' System handles greetings, questions, complaints naturally

Common Patterns

Document Summarization - Background Processing (from announcements.gbai)

' Schedule automatic updates - runs in background
SET SCHEDULE "59 * * * *"

' Fetch and summarize documents ONCE for all users
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume  ' Stored for all users

Interactive Case Analysis - User Conversations (from law.gbai)

' Ask for case number - interactive with user
TALK "What is the case number?"
HEAR cod

' Load case document
text = GET "case-" + cod + ".pdf"

IF text THEN 
    ' Set context for system AI to use in conversation
    text = "Based on this document, answer the person's questions:\n\n" + text
    SET CONTEXT text 
    TALK "Case loaded. Ask me anything about it."
ELSE
    TALK "Case not found, please try again."
END IF

Tool Definition Pattern

' Tool parameters (auto-discovered by LLM)
PARAM name AS string
PARAM email AS string
DESCRIPTION "Enrollment tool"

' Tool logic (called when LLM decides)
SAVE "enrollments.csv", name, email
TALK "Successfully enrolled " + name

Multi-Collection Search

USE KB "products"
USE KB "reviews"  
USE KB "specifications"

' System AI searches these collections automatically during conversation
TALK "What would you like to know about our products?"

Advanced Features

Memory Management

See Storage documentation for persistent data options.

SET BOT MEMORY "company_policy", policy_text
' Available across all sessions

retrieved = GET BOT MEMORY "company_policy"

External APIs

See External APIs chapter for integration patterns.

result = GET "https://api.example.com/data"
' For background processing only
summary = LLM "Summarize this data: " + result
SET BOT MEMORY "api_summary", summary

Suggestions

See UI Interface for UI integration.

ADD SUGGESTION "Schedule Meeting" AS "schedule"
ADD SUGGESTION "View Products" AS "products"
' UI shows these as quick actions

Error Handling

The system handles errors gracefully:

• Syntax errors caught at compile time
• 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

Scripts run in a sandboxed environment with:

• Access to session state
• LLM generation capabilities
• 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

Old Way (Complex Logic)

' DON'T DO THIS - 1990s style
' IF INSTR(user_input, "order") > 0 THEN
'   IF INSTR(user_input, "status") > 0 THEN
'     TALK "Checking order status..."
'   ELSE IF INSTR(user_input, "new") > 0 THEN
'     TALK "Creating new order..."
'   END IF
' END IF

New Way (System AI Intelligence)

' DO THIS - Let system AI handle conversation naturally
TALK "How can I help you with your order?"
' System AI understands context and intent automatically

The key is to trust the system AI and write less code for more intelligent behavior.

Important Distinction

• LLM Command: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
• Interactive Conversations: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow

See Also

• Chapter 1: Quick Start - Getting started with your first bot
• Chapter 2: Bot Architecture - Understanding all components
• Chapter 3: Knowledge Base - Working with KB collections
• Chapter 5: Keywords Reference - Complete BASIC command reference
• Chapter 9: Conversation Flow - Advanced dialog patterns

.gbkb Knowledge Base

The .gbkb package contains your bot’s domain knowledge - documents that the AI uses to answer questions accurately about your specific organization, products, or services.

What It Does

When you place documents in a .gbkb folder, the system automatically:

1. Extracts text from your files (PDF, DOCX, TXT, MD, HTML, CSV)
2. Creates searchable indexes using vector embeddings
3. Enables semantic search so users can ask questions naturally

This means your bot answers based on YOUR documents, not just general AI knowledge.

Folder Structure

mybot.gbai/
└── mybot.gbkb/
    ├── policies/           ← Collection: "policies"
    │   ├── vacation.pdf
    │   └── handbook.docx
    ├── products/           ← Collection: "products"
    │   ├── catalog.pdf
    │   └── specs.xlsx
    └── support/            ← Collection: "support"
        └── faq.md

Each subfolder becomes a collection you can activate independently.

Using in BASIC Scripts

' Activate collections for this conversation
USE KB "policies"
USE KB "products"

' Now the AI automatically searches these when answering
TALK "How can I help you today?"

' Later, clear when done
CLEAR KB "policies"

Supported File Types

Key Points

• Automatic indexing - Just drop files in folders
• Semantic search - Users don’t need exact keywords
• Multiple collections - Organize by topic, activate as needed
• No code required - The AI handles search automatically

Learn More

• Chapter 03: Knowledge Base System - Technical deep-dive on indexing, vectors, and search
• USE KB Keyword - Complete keyword reference
• CLEAR KB Keyword - Managing active collections

.gbot Bot Configuration

The .gbot package serves as the configuration center for your bot, containing the settings that define how the bot behaves, which AI models it uses, and how it interacts with users. This chapter explains the configuration system and guides you through the available options.

Understanding Bot Configuration

Every bot in General Bots requires configuration to operate effectively. The .gbot folder within your bot package holds these settings, primarily through a config.csv file that uses simple key-value pairs. This approach makes configuration accessible to anyone comfortable with spreadsheet applications while remaining powerful enough for complex deployments.

The configuration system influences several aspects of bot behavior. Bot identity settings control how the bot presents itself to users. LLM configuration determines which language model powers the bot’s intelligence and how it generates responses. Context management settings affect how the bot maintains conversation history and retrieves relevant information. Integration parameters connect the bot to external services and APIs.

The config.csv File

Configuration lives in a straightforward CSV format with two columns: key and value. This design choice prioritizes accessibility—you can edit configuration in any text editor or spreadsheet application without learning complex syntax. Each row represents a single setting, making it easy to scan and modify.

The file supports various data types implicitly. Text values are stored as-is, numbers are parsed when needed, and boolean values typically use “true” and “false” strings. The system handles type conversion automatically when reading configuration, so you rarely need to worry about explicit typing.

Bot Identity Configuration

Identity settings establish how your bot presents itself during conversations. The bot_name parameter provides the display name users see when interacting with the bot. A descriptive bot_description helps users understand the bot’s purpose and capabilities. Version tracking through the version parameter supports deployment management and debugging.

These identity settings matter because they shape user expectations. A bot named “Legal Document Assistant” with an appropriate description sets different expectations than a generic “Helper Bot.” Clear identity configuration improves user experience by establishing context before conversations begin.

Language Model Settings

LLM configuration represents perhaps the most important settings in your bot. The llm_provider parameter specifies which AI service powers your bot, supporting options like OpenAI, Azure OpenAI, or local model servers. The llm_model parameter identifies the specific model to use, such as GPT-5, Claude Sonnet 4.5, or a local GGUF model.

Response characteristics are controlled through several parameters. The temperature setting affects response creativity, with lower values producing more focused and deterministic outputs while higher values allow more varied and creative responses. The max_tokens parameter limits response length, preventing runaway generation and managing costs for cloud-based providers.

The system_prompt parameter provides instructions that shape the bot’s personality and behavior throughout conversations. This prompt is prepended to every interaction, giving the model consistent guidance about how to respond, what tone to use, and what boundaries to respect.

Context Management

Context settings control how the bot maintains awareness of conversation history and relevant information. The context_window parameter determines how many previous messages remain visible to the model during each interaction. Larger windows provide better continuity but consume more tokens.

The context_provider setting influences how context is assembled and presented to the model. Different providers may apply various strategies for selecting and formatting context, optimizing for different use cases.

Memory functionality, controlled by the memory_enabled setting, allows bots to retain information across sessions. When enabled, bots can remember user preferences, previous interactions, and other persistent data that improves personalization.

Configuration Loading and Precedence

The system assembles configuration from multiple sources, applying them in a specific order that allows flexible overrides. Default values provide baseline behavior when no explicit configuration exists. Settings in your .gbot/config.csv file override these defaults for your specific bot.

Environment variables can override config.csv settings, useful for deployment scenarios where configuration varies between environments. Database configuration provides another override layer, supporting runtime configuration changes that persist across restarts. Finally, runtime API calls can temporarily adjust settings without permanent changes.

This precedence system enables sophisticated deployment patterns. Development environments might use local configuration files while production deployments pull settings from environment variables or databases. The same bot package can behave differently across environments without modification.

Dynamic Configuration with Bot Memory

Beyond static configuration, bots can store and retrieve dynamic settings using bot memory. The SET BOT MEMORY keyword stores values that persist across all sessions, effectively creating runtime configuration that can be modified through bot scripts.

This capability supports scenarios where configuration needs to adapt based on usage patterns, administrative decisions, or external inputs. A bot might store preferred response styles, accumulated statistics, or cached data that influences its behavior.

Best Practices

Effective configuration follows several principles. Keep identity settings clear and accurate—users trust bots more when their purpose is evident. Choose LLM settings that balance capability with cost and latency requirements. Set appropriate context windows that provide continuity without excessive token consumption.

Document non-obvious configuration choices, either in comments within config.csv or in accompanying documentation. This practice helps future maintainers understand why settings were chosen and whether they should be adjusted.

Test configuration changes in development environments before deploying to production. Some settings interact in non-obvious ways, and testing catches issues before they affect users.

Summary

The .gbot configuration system provides comprehensive control over bot behavior through accessible CSV files augmented by environment variables, database settings, and runtime adjustments. Understanding these configuration options and their precedence helps you build bots that behave predictably across different deployment scenarios while remaining adaptable to changing requirements.

.gbtheme UI Theming

The .gbtheme package provides visual customization for your bot’s web interface through straightforward CSS-based theming. This approach prioritizes simplicity—you create CSS files that override default styles, without needing complex build tools, template engines, or JavaScript frameworks.

The Philosophy of Simple Theming

Many theming systems require elaborate toolchains, preprocessors, and build processes that create barriers for non-developers who want to customize their bot’s appearance. General Bots takes a different approach by using plain CSS files that any web designer can create and modify.

This simplicity doesn’t sacrifice capability. CSS custom properties (variables) provide the flexibility to change colors, typography, spacing, and other visual characteristics throughout the interface by modifying a few central values. The bot’s default interface handles all the complex layout and functionality concerns, leaving themes to focus purely on appearance.

Theme Structure

A theme consists of one or more CSS files placed in the .gbtheme folder within your bot package. The simplest theme might be a single default.css file containing variable overrides. More complex setups might include multiple theme files for different contexts—a dark theme for evening use, a high-contrast theme for accessibility, or seasonal themes for special occasions.

The system automatically loads the default theme on startup, and scripts can switch between available themes at runtime based on user preferences, time of day, or any other logic you implement.

CSS Variables and Customization

The bot interface defines a set of CSS custom properties that control fundamental visual characteristics. By overriding these properties in your theme file, you can transform the interface’s appearance with minimal code.

The primary-color variable establishes your main brand color, used for headers, buttons, and other prominent elements. The secondary-color provides accent coloring for highlights and interactive elements. Background and text-color control the basic page appearance and readability.

Typography settings including font-family let you match your organization’s brand standards. Structural properties like border-radius affect the overall feel—sharp corners suggest professionalism while rounded corners feel friendlier. Spacing controls help maintain consistent visual rhythm throughout the interface.

These variables cascade through the interface components, meaning a single change propagates everywhere that property is used. This approach makes comprehensive theming achievable with just a handful of variable overrides.

Creating Effective Themes

Building a theme starts with understanding your visual goals. Corporate deployments often need to match existing brand guidelines, requiring specific colors, fonts, and visual treatments. Consumer-facing bots might prioritize approachability and visual appeal. Internal tools might emphasize clarity and efficiency over aesthetics.

A minimal theme might override only the primary and secondary colors to match brand standards while accepting defaults for everything else. This approach gets results quickly with minimal effort. As needs grow, you can progressively add more customization.

When creating dark themes, remember to adjust not just the background color but also text colors, borders, shadows, and any other elements that assume a light background. Contrast matters for readability—test your themes with actual content to ensure text remains legible.

Accessibility considerations should inform theme design. Ensure sufficient contrast ratios between text and backgrounds, avoid relying solely on color to convey information, and test with various visual impairments in mind.

Dynamic Theme Switching

Bots can change themes at runtime through the CHANGE THEME keyword in BASIC scripts. This capability enables several useful patterns.

User preference systems let visitors choose their preferred theme, with the selection stored in user memory for future visits. Time-based switching can apply dark themes during evening hours automatically. Contextual theming might use different visual treatments for different conversation modes or topics.

Theme switching happens instantly without page reloads, providing smooth transitions that maintain conversation flow.

Configuration Integration

Theme settings can also be specified in the bot’s config.csv file, providing default values that themes can override. The theme parameter specifies which theme file to load by default. The theme-color1 and theme-color2 parameters provide primary and secondary colors that the interface uses when no theme file specifies otherwise.

These configuration values serve as fallbacks—CSS files in the .gbtheme folder take precedence when they define the same properties. This layering allows simple color customization through configuration while supporting full CSS theming for more sophisticated needs.

No Build Process Required

Unlike many modern web development workflows, .gbtheme requires no build tools, preprocessors, or compilation steps. You write CSS files, place them in the appropriate folder, and they take effect. Changes appear immediately through hot reloading, making iterative design work fast and responsive.

This simplicity means designers without development environment setup can contribute themes. Anyone who can write CSS can customize the interface, lowering barriers to visual customization.

Migrating from Complex Systems

Organizations moving from platforms with complex theming systems can extract their essential visual parameters and recreate them as CSS variable overrides. The process typically involves identifying brand colors and typography from the existing theme, mapping those values to General Bots CSS variables, testing the result against the interface, and iteratively refining until the appearance matches expectations.

Much of the complexity in traditional theming systems exists to handle layout and functionality concerns that General Bots manages through its default interface. By focusing themes purely on visual styling, the migration process becomes much simpler.

Best Practices

Effective theming follows several principles. Keep theme files focused and minimal—override only what you need to change rather than redefining everything. Start with a single default.css file and add complexity only as requirements demand.

Test themes across different devices and screen sizes to ensure they work well everywhere. Pay attention to interactive states like hover, focus, and active to ensure the interface remains usable and visually coherent.

Document theme choices, especially when values differ from brand guidelines for technical reasons. Future maintainers will appreciate understanding why specific decisions were made.

Maintain consistency within themes—if you override one color, consider whether related elements need adjustment to maintain visual harmony.

Summary

The .gbtheme system demonstrates that powerful customization doesn’t require complex tooling. Through CSS variables and standard stylesheets, you can transform the bot interface’s appearance while the platform handles the underlying complexity. This approach respects the skills of designers and developers alike, enabling visual customization without artificial barriers.

.gbdrive File Storage

The .gbdrive system provides centralized file storage for all bot packages, leveraging S3-compatible object storage to deliver reliable, scalable storage infrastructure. This chapter explains how file storage works, how files are organized, and how to interact with stored content.

Understanding File Storage in General Bots

Every bot requires storage for its various components—scripts, documents, configuration files, user uploads, and generated content. Rather than managing files across disparate locations, General Bots consolidates storage through the .gbdrive system, which provides a consistent interface regardless of the underlying storage backend.

The storage system builds on S3-compatible object storage, meaning it works with self-hosted solutions like MinIO as well as cloud providers like AWS S3, Backblaze B2, or DigitalOcean Spaces. This flexibility allows deployments to choose storage solutions that match their requirements for cost, performance, and data residency.

Beyond simple file storage, the system provides versioning capabilities, access control, automatic synchronization, and integration with other bot components like knowledge bases and themes.

Storage Organization

Files are organized using a bucket-per-bot structure that keeps each bot’s content isolated and manageable. Within a bot’s storage bucket, the familiar package structure appears: .gbdialog for scripts, .gbkb for knowledge base collections, .gbot for configuration, and .gbtheme for interface customization.

Additionally, each bot has space for user-uploaded files, generated content, and other runtime data. This organization mirrors the logical structure you work with during development, making it intuitive to understand where files reside and how they relate to bot functionality.

The system maintains this structure automatically when bots are deployed or updated, ensuring that the storage state reflects the current bot configuration without manual intervention.

.gbusers - Per-User Storage

The .gbusers folder within .gbdrive provides isolated storage space for each user interacting with the bot. This enables personalized document storage, user-specific settings, and application data that persists across sessions.

User Folder Structure

User folders are identified by the user’s email address or phone number:

mybot.gbai/
  mybot.gbdrive/
    users/
      john@example.com/           # User identified by email
        papers/
          current/                # Active/working documents
            untitled-1.md
            meeting-notes.md
          named/                  # Saved/named documents
            quarterly-report/
              document.md
              attachments/
            project-proposal/
              document.md
        uploads/                  # User file uploads
        exports/                  # Generated exports (PDF, DOCX, etc.)
        settings/                 # User preferences
          preferences.json
      +5511999887766/             # User identified by phone number
        papers/
          current/
          named/
        uploads/

User Identifier Format

Users are identified by their primary contact method:

• Email: john@example.com, maria@company.com.br
• Phone: +5511999887766, +1234567890 (E.164 format)

The identifier is sanitized for filesystem compatibility while remaining human-readable.

Paper Document Storage

The Paper application stores user documents in the papers/ directory:

• papers/current/: Working documents that are actively being edited. These may be auto-saved drafts or recently accessed files.
• papers/named/: Documents that have been explicitly saved with a name. Each named document gets its own folder to support attachments and metadata.

Example document structure:

papers/
  current/
    untitled-1.md           # Auto-saved draft
    untitled-2.md           # Another working document
  named/
    meeting-notes-2024/
      document.md           # The main document content
      metadata.json         # Title, created_at, updated_at, etc.
      attachments/          # Embedded images or files
        image-001.png
    research-paper/
      document.md
      metadata.json

Accessing User Storage from BASIC

BASIC scripts can access user storage using the USER DRIVE keyword:

' Read a user's document
content = READ USER DRIVE "papers/current/notes.md"

' Write to user's storage
SAVE USER DRIVE "papers/named/report/document.md", report_content

' List user's papers
papers = LIST USER DRIVE "papers/named/"

' Delete a user document
DELETE USER DRIVE "papers/current/draft.md"

User Storage API

The REST API provides endpoints for user storage operations:

GET  /api/drive/user/list?path=papers/current/
POST /api/drive/user/read
     { "path": "papers/named/report/document.md" }
POST /api/drive/user/write
     { "path": "papers/current/notes.md", "content": "..." }
POST /api/drive/user/delete
     { "path": "papers/current/draft.md" }

All user storage API calls require authentication and automatically scope operations to the authenticated user’s folder.

Storage Quotas

Each user has configurable storage limits:

Configure in config.csv:

user-storage-quota,104857600
user-file-limit,5242880
user-file-count,500

Working with Files

File operations in General Bots happen through several interfaces depending on your needs. The BASIC scripting language provides keywords for reading file content directly into scripts, enabling bots to process documents, load data, or access configuration dynamically.

Files can also be managed through the administrative API for bulk operations, migrations, or integration with external systems. The web interface provides user-facing upload and download capabilities where appropriate.

When files change in storage, the system detects modifications and triggers appropriate responses. Script changes cause recompilation, document changes trigger knowledge base reindexing, and configuration changes reload bot settings. This hot-reloading capability accelerates development and enables runtime updates without service interruption.

Integration with Bot Components

The storage system integrates deeply with other bot components, serving as the foundation for several capabilities.

Knowledge bases draw their source documents from storage, with the indexing system monitoring for changes and updating embeddings accordingly. When you add a document to a .gbkb folder, it automatically becomes part of the bot’s searchable knowledge.

Theme assets including CSS files and images are served from storage, with appropriate caching to ensure good performance. Changes to theme files take effect quickly without requiring restarts.

Tool scripts in .gbdialog folders are loaded from storage, parsed, and made available for execution. The compilation system tracks dependencies and rebuilds as needed when source files change.

Paper Application Integration

The Paper document editor automatically saves to the user’s .gbusers folder:

1. Auto-save: Every 30 seconds, working documents are saved to papers/current/
2. Explicit save: When users click “Save”, documents move to papers/named/{document-name}/
3. Export: Generated exports (PDF, DOCX) are saved to exports/ and offered for download
4. AI-generated content: AI responses can be inserted into documents and saved automatically

Access Control

Different files require different access levels, and the storage system enforces appropriate controls:

• Public files: Accessible without authentication, suitable for shared resources
• Authenticated access: Requires valid user credentials, protects user-specific content
• User-scoped access: Users can only access their own .gbusers folder content
• Bot-internal files: Accessible only to the bot system itself
• Administrative files: Require elevated privileges to access or modify

User storage in .gbusers is strictly isolated—users cannot access other users’ folders through any API or BASIC keyword.

Storage Backend Options

The storage system supports multiple backends to accommodate different deployment scenarios. The default configuration uses self-hosted S3-compatible object storage, providing full control over where data resides. Any S3-compatible service works as an alternative, including major cloud providers.

For development and testing, local filesystem storage offers simplicity and easy inspection of files. Production deployments might use hybrid configurations with multiple backends providing redundancy or geographic distribution.

Backend selection happens through configuration, and the rest of the system interacts with storage through a consistent interface regardless of which backend is active. This abstraction allows deployments to change storage strategies without modifying bot code.

Directory Structure Reference

Complete .gbdrive structure with all components:

mybot.gbai/
  mybot.gbdrive/
    dialogs/              # Compiled dialog scripts cache
    kb/                   # Knowledge base index data
    cache/                # Temporary cache files
    exports/              # Bot-level exports
    uploads/              # Bot-level uploads
    users/                # Per-user storage (.gbusers)
      user@email.com/
        papers/
          current/        # Working documents
          named/          # Saved documents
        uploads/          # User uploads
        exports/          # User exports
        settings/         # User preferences
      +1234567890/
        papers/
        uploads/
        exports/
        settings/

Summary

The .gbdrive storage system provides the foundation for all file-based operations in General Bots. Through S3-compatible object storage, organized bucket structures, automatic synchronization, and deep integration with other components, it delivers reliable file management that supports both development workflows and production operation.

The .gbusers folder structure enables personalized storage for each user, supporting applications like Paper that require persistent document storage. By organizing user data under their email or phone identifier, the system maintains clear separation while enabling powerful per-user features.

Understanding how storage works helps you organize bot content effectively and leverage the automatic capabilities the system provides.

Bot Templates

botserver includes pre-built bot templates for various use cases. Each template is a complete .gbai package ready to deploy.

Complete Template List (Flat Reference)

Templates by Category

Core Templates

HR & People

IT & Support

CRM & Sales

Finance & Accounting

Operations

Template Structure

All templates follow this standard directory layout:

template-name.gbai/
  template-name.gbdialog/    # BASIC dialog scripts
    start.bas                # Entry point (required)
    *.bas                    # Tool scripts (auto-discovered)
    *-jobs.bas               # Scheduled jobs
  template-name.gbkb/        # Knowledge base collections
    collection1/             # Documents for USE KB "collection1"
  template-name.gbdrive/     # File storage (not KB)
    uploads/                 # User uploaded files
    exports/                 # Generated files
  template-name.gbot/        # Configuration
    config.csv               # Bot parameters
  template-name.gbtheme/     # UI theme (optional)
    default.css              # Theme CSS

Quick Start Guide

1. Choose a Template

Select based on your needs:

• Simple chat: Use default.gbai
• Business app: Choose crm.gbai, bi.gbai, or erp.gbai
• AI features: Pick ai-search.gbai or llm-tools.gbai
• Communication: Select broadcast.gbai or whatsapp.gbai

2. Deploy the Template

# Templates are auto-deployed during bootstrap
# Access at: http://localhost:9000/template-name

3. Customize Configuration

Edit template-name.gbot/config.csv:

name,value
bot-name,My Custom Bot
welcome-message,Hello! How can I help?
llm-model,model.gguf
temperature,0.7

4. Add Knowledge Base

Place documents in .gbkb folders:

• Each folder becomes a collection
• Use USE KB "folder-name" in scripts
• Documents are automatically indexed

5. Create Tools

Add .bas files to .gbdialog:

• Each file becomes a tool
• Auto-discovered by the system
• Called automatically by LLM when needed

Required Files for Each Template

start.bas (Required)

' Template Name - Start Script

' Setup Tools
ADD TOOL "tool-name-1"
ADD TOOL "tool-name-2"

' Setup Knowledge Base
USE KB "template-name.gbkb"

' Set Context
SET CONTEXT "context name" AS "You are a [role]. You help with [tasks]."

' Setup Suggestions
CLEAR SUGGESTIONS
ADD SUGGESTION "action1" AS "Display text 1"
ADD SUGGESTION "action2" AS "Display text 2"

' Welcome Message
BEGIN TALK
    **Template Title**
    
    Welcome message here.
    
    **What I can help with:**
    • Feature 1
    • Feature 2
END TALK

BEGIN SYSTEM PROMPT
    Detailed instructions for the AI...
END SYSTEM PROMPT

Tool File Template

PARAM paramname AS STRING LIKE "example" DESCRIPTION "What this parameter is"
PARAM optionalparam AS STRING LIKE "default" DESCRIPTION "Optional parameter"

DESCRIPTION "What this tool does. Called when user wants to [action]."

' Business logic
let result = "processed"

' Save data (field names = variable names)
SAVE "table.csv", paramname, optionalparam, result

' Store in memory
SET BOT MEMORY "last_item", result

' Response
TALK "✅ Action completed successfully!"

config.csv Template

name,value
episodic-memory-history,2
episodic-memory-threshold,4
theme-color1,#1565C0
theme-color2,#E3F2FD
theme-logo,https://pragmatismo.com.br/icons/general-bots.svg
theme-title,Template Name - General Bots

Syntax Rules for Templates

DO ✅

' Variable names (no underscores in names)
let ticketnumber = "TKT001"
let useremail = "user@example.com"

' SAVE with field names = variable names
SAVE "table.csv", ticketnumber, useremail, status

' Keywords with spaces
SET BOT MEMORY "last_ticket", ticketnumber
SET CONTEXT "name" AS "description"
ADD SUGGESTION "key" AS "Display text"
CLEAR SUGGESTIONS
USE KB "myknowledge"
USE TOOL "mytool"

' GET BOT MEMORY as function
let lastticket = GET BOT MEMORY("last_ticket")

DON’T ❌

' NO: Complex object operations
SET object.field = value  ' WRONG
SAVE "table", object.id, object  ' WRONG

Creating Custom Templates

To create your own template:

1. Copy template.gbai as starting point
2. Define clear purpose - one template, one job
3. Structure folders properly:
   • .gbdialog for scripts
   • .gbkb for knowledge collections
   • .gbdrive for general files
   • .gbot for configuration
4. Include examples - sample data and dialogs
5. Test thoroughly - verify all features

Best Practices

Template Selection

1. Start small: Begin with default.gbai
2. Match use case: Choose aligned templates
3. Combine features: Mix templates as needed
4. Keep originals: Copy before modifying

Customization Strategy

Minimal BASIC Approach

Instead of complex dialog flows, use simple LLM calls:

' Let system AI handle conversations naturally
TALK "How can I assist you?"
' System AI understands and responds appropriately

Tool Creation

Only create .bas files for specific actions:

• API calls
• Database operations
• File processing
• Calculations

Knowledge Base Organization

• One folder per topic/collection
• Name folders clearly
• Keep documents updated
• Index automatically

Performance Tips

• Remove unused template files
• Index only necessary documents
• Configure appropriate cache settings
• Monitor resource usage

Support Resources

• README files in each template folder
• Example configurations included
• Sample knowledge bases provided
• Community forums for discussions

Business Intelligence Template (bi.gbai)

A General Bots template for automated business intelligence reporting and data visualization.

Overview

The BI template provides scheduled analytics reporting with automatic chart generation and delivery. It’s designed for organizations that need automated consumption reports, category analysis, and customer-specific insights.

Features

• Scheduled Reporting - Automated report generation on configurable schedules
• Time-Series Charts - Monthly consumption trends visualization
• Category Analysis - Product category breakdown with donut charts
• Per-Customer Reports - Individual customer consumption analysis
• Multi-Channel Delivery - Send reports via chat, email, or messaging platforms

Package Structure

bi.gbai/
├── bi.gbai/
│   ├── bi-admin.bas      # Administrative scheduled reports
│   └── bi-user.bas       # Per-customer report generation

Scripts

Configuration

Configure the template in your bot’s config.csv:

Usage

Administrative Reports

The bi-admin.bas script runs on a schedule and generates:

1. Monthly Consumption Chart - Time-series showing spending trends
2. Product Category Breakdown - Donut chart of spending by category

SET SCHEDULE "1 * * * * *"

billing = FIND "Orders"

' Monthly consumption
data = SELECT SUM(UnitPrice * Quantity) as Value, 
       MONTH(OrderDate)+'/'+YEAR(OrderDate) 
       FROM billing 
       GROUP BY MONTH(OrderDate), YEAR(OrderDate)

img = CHART "timeseries", data
SEND FILE img, "Monthly Consumption"

Per-Customer Reports

The bi-user.bas script iterates through customers to generate personalized reports:

customers = FIND "Customers"

FOR EACH c IN customers
    data = SELECT SUM(UnitPrice * Quantity) AS Value, 
           MONTH(OrderDate)+'/'+YEAR(OrderDate) 
           FROM billing
           JOIN Customers ON billing.CustomerID = Customers.CustomerID
           GROUP BY MONTH(OrderDate), YEAR(OrderDate)
           WHERE Customers.CustomerID = c.CustomerID

    img = CHART "timeseries", data
    SEND FILE img, "Monthly Consumption"
END FOR

Chart Types

The template supports various chart types:

Data Requirements

Orders Table Schema

The template expects a billing/orders data source with:

• OrderDate - Date of the transaction
• UnitPrice - Price per unit
• Quantity - Number of units
• ProductID - Foreign key to products
• CustomerID - Foreign key to customers

Products Table Schema

• ProductID - Primary key
• CategoryID - Foreign key to categories
• ProductName - Product name

Categories Table Schema

• CategoryID - Primary key
• CategoryName - Category display name

Example Output

Monthly Consumption Report

📊 Monthly Consumption Report
-----------------------------
Generated: 2024-01-15 08:00

[Time Series Chart Image]

Total Revenue: $125,430
Top Month: December ($18,500)
Growth Rate: +12% MoM

Category Breakdown

📊 Product Category Distribution
--------------------------------

[Donut Chart Image]

Electronics: 35%
Clothing: 28%
Home & Garden: 22%
Other: 15%

Customization

Adding New Reports

Create additional .bas files in the bi.gbai folder:

' sales-by-region.bas
SET SCHEDULE "0 9 * * 1"  ' Every Monday at 9 AM

data = SELECT Region, SUM(Amount) as Total 
       FROM Sales 
       GROUP BY Region

img = CHART "bar", data
SEND FILE img, "Weekly Regional Sales"

Customizing Delivery

Send reports to specific users or channels:

' Send to specific user
SEND FILE img TO "manager@company.com", "Weekly Report"

' Send to WhatsApp
SEND FILE img TO "+1234567890", "Your monthly report"

' Send to team channel
TALK TO "sales-team", img

Scheduling Options

Integration Examples

With CRM

' Combine with CRM data
opportunities = FIND "opportunities.csv"
revenue = SELECT stage, SUM(amount) FROM opportunities GROUP BY stage

img = CHART "funnel", revenue
SEND FILE img, "Sales Pipeline"

With ERP

' Inventory analysis
inventory = FIND "inventory.csv"
low_stock = SELECT product, quantity FROM inventory WHERE quantity < reorder_level

img = CHART "bar", low_stock
SEND FILE img, "Low Stock Alert"

Best Practices

1. Schedule appropriately - Don’t run heavy reports too frequently
2. Filter data - Use date ranges to limit data volume
3. Cache results - Store computed metrics for faster access
4. Log activities - Track report generation for auditing
5. Handle errors - Wrap queries in error handling

Troubleshooting

Related Templates

• Platform Analytics - Platform metrics and monitoring
• Talk to Data - Natural language data queries
• CRM - CRM with built-in reporting

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Web Crawler Template (crawler.gbai)

A General Bots template for automated web crawling and content extraction for knowledge base population.

Overview

The Crawler template enables your bot to automatically fetch, parse, and index web content. It’s designed for building knowledge bases from websites, monitoring web pages for changes, and extracting structured data from online sources.

Features

• Automated Web Scraping - Fetch and parse web pages automatically
• Document Mode - Answer questions based on crawled content
• Configurable Depth - Control how many pages to crawl
• Content Indexing - Automatically add content to knowledge base
• LLM Integration - Use AI to understand and summarize crawled content

Package Structure

crawler.gbai/
├── crawler.gbkb/          # Knowledge base for crawled content
│   └── docs/              # Indexed documents
└── crawler.gbot/
    └── config.csv         # Crawler configuration

Configuration

Configure the crawler in crawler.gbot/config.csv:

Example config.csv

name,value
Website,https://pragmatismo.com.br/
website Max Documents,2
Answer Mode,document
Theme Color,purple
LLM Provider,openai

How It Works

1. Initialization - Bot reads the target website from configuration
2. Crawling - Fetches pages starting from the root URL
3. Extraction - Parses HTML and extracts meaningful text content
4. Indexing - Stores content in the knowledge base for RAG
5. Q&A - Users can ask questions about the crawled content

Usage

Basic Setup

1. Copy the template to your bot’s packages directory:

cp -r templates/crawler.gbai /path/to/your/bot/packages/

2. Edit crawler.gbot/config.csv with your target website:

name,value
Website,https://your-website.com/
website Max Documents,10
Answer Mode,document

3. Deploy and the bot will automatically crawl the configured site.

Querying Crawled Content

Once crawled, users can ask questions naturally:

• “What services does the company offer?”
• “Tell me about the pricing”
• “Summarize the about page”
• “What are the main features?”

Answer Modes

Sample Conversation

User: What does this company do?

Bot:  Based on the website content:
      
      Pragmatismo provides enterprise AI solutions 
      including:
      
      • General Bots platform
      • Custom AI development
      • Conversational AI consulting
      • Integration services
      
      📄 Source: pragmatismo.com.br/about

User: Do they have any case studies?

Bot:  Yes! According to the website, they have worked 
      with several enterprise clients:
      
      • Banking sector automation
      • Healthcare chatbots
      • E-commerce customer service
      
      📄 Source: pragmatismo.com.br/cases

User: How can I contact them?

Bot:  Contact information from the website:
      
      📧 Email: contact@pragmatismo.com.br
      📍 Location: São Paulo, Brazil
      🌐 Website: pragmatismo.com.br
      
      📄 Source: pragmatismo.com.br/contact

Advanced Configuration

Limiting Crawl Scope

Control which pages are crawled:

name,value
Website,https://example.com/docs/
website Max Documents,50
Website Include Pattern,/docs/*
Website Exclude Pattern,/docs/archive/*

Scheduling Recrawls

Set up periodic recrawling to keep content fresh:

name,value
Website Refresh Schedule,0 0 * * 0

This example recrawls every Sunday at midnight.

Authentication

For sites requiring authentication:

name,value
Website Auth Type,basic
Website Username,user
Website Password,secret

Customization

Creating Custom Crawl Logic

Create a BASIC dialog for custom crawling:

' custom-crawl.bas
urls = ["https://site1.com", "https://site2.com", "https://site3.com"]

FOR EACH url IN urls
    content = GET url
    
    IF content THEN
        SAVE "crawled_pages.csv", url, content, NOW()
        SET CONTEXT content
    END IF
NEXT

TALK "Crawled " + UBOUND(urls) + " pages successfully."

Processing Crawled Content

Use LLM to process and structure crawled data:

' process-crawled.bas
pages = FIND "crawled_pages.csv"

FOR EACH page IN pages
    summary = LLM "Summarize this content in 3 bullet points: " + page.content
    
    WITH processed
        url = page.url
        summary = summary
        processed_at = NOW()
    END WITH
    
    SAVE "processed_content.csv", processed
NEXT

Extracting Structured Data

Extract specific information from pages:

' extract-products.bas
SET CONTEXT "You are a data extraction assistant. Extract product information as JSON."

page_content = GET "https://store.example.com/products"

products = LLM "Extract all products with name, price, and description as JSON array: " + page_content

SAVE "products.json", products

Integration Examples

With Knowledge Base

' Add crawled content to KB
content = GET "https://docs.example.com/api"

IF content THEN
    USE KB "api-docs.gbkb"
    ADD TO KB content, "API Documentation"
END IF

With Notifications

' Monitor for changes
previous = GET BOT MEMORY "last_content"
current = GET "https://news.example.com"

IF current <> previous THEN
    SEND MAIL "admin@company.com", "Website Changed", "The monitored page has been updated.", []
    SET BOT MEMORY "last_content", current
END IF

Best Practices

1. Respect robots.txt - Only crawl pages allowed by the site’s robots.txt
2. Rate limiting - Don’t overwhelm target servers with requests
3. Set reasonable limits - Start with low Max Documents values
4. Monitor content quality - Review crawled content for accuracy
5. Keep content fresh - Schedule periodic recrawls for dynamic sites
6. Handle errors gracefully - Implement retry logic for failed requests

Troubleshooting

Limitations

• JavaScript-rendered content may not be fully captured
• Some sites block automated crawlers
• Large sites may take significant time to fully crawl
• Dynamic content may require special handling

Use Cases

• Documentation Bots - Index product docs for support
• Competitive Intelligence - Monitor competitor websites
• News Aggregation - Collect news from multiple sources
• Research Assistants - Build knowledge bases from academic sources
• FAQ Generators - Extract FAQs from help sites

Related Templates

• AI Search - AI-powered document search
• Talk to Data - Natural language data queries
• Law - Legal document processing with similar RAG approach

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbkb Reference - Knowledge base guide

Sales CRM Template (crm.gbai)

A comprehensive General Bots template for sales customer relationship management with lead tracking, opportunity management, and sales pipeline automation.

Overview

The CRM template provides a full-featured sales CRM system with conversational AI capabilities. It enables sales teams to manage leads, track opportunities through the pipeline, generate quotes, send proposals, and forecast revenue—all through natural conversation or automated workflows.

Features

• Lead Management - Capture, qualify, convert, and nurture leads
• Opportunity Pipeline - Track deals through customizable stages
• Account Management - Manage customer accounts and contacts
• Activity Tracking - Log calls, emails, meetings, and tasks
• Quote Generation - Create and send professional quotes
• Proposal Automation - Generate and deliver sales proposals
• Sales Forecasting - Pipeline analysis and revenue projections
• Email Integration - Receive and process emails automatically
• Sentiment Analysis - AI-powered customer sentiment tracking
• Data Enrichment - Automatic lead data enhancement

Package Structure

crm.gbai/
├── crm.gbdialog/
│   ├── lead-management.bas          # Lead lifecycle management
│   ├── opportunity-management.bas   # Opportunity pipeline
│   ├── account-management.bas       # Account/company management
│   ├── activity-tracking.bas        # Activity logging
│   ├── case-management.bas          # Support case handling
│   ├── analyze-customer-sentiment.bas # AI sentiment analysis
│   ├── data-enrichment.bas          # Lead data enhancement
│   ├── send-proposal.bas            # Proposal generation
│   ├── create-lead-from-draft.bas   # Email to lead conversion
│   ├── crm-jobs.bas                 # Scheduled background jobs
│   └── tables.bas                   # Database schema definitions
└── crm.gbot/
    └── config.csv                   # Bot configuration

Scripts

Data Schema

Leads Table

Opportunities Table

Accounts Table

Contacts Table

Activities Table

Pipeline Stages

Sample Conversations

Lead Capture

User: I just got a lead from the website

Bot:  Great! I'll help you capture it. What's their name?

User: John Smith from TechCorp

Bot:  What's their email?

User: john@techcorp.com

Bot:  ✅ Lead captured: John Smith (TechCorp)
      ID: LEAD-20240115-4821
      
      Would you like to qualify this lead now?

Lead Qualification (BANT)

User: Yes, qualify the lead

Bot:  I'll ask a few questions to qualify them.
      
      What is TechCorp's annual revenue range?
      1. Under $1M
      2. $1M - $10M
      3. $10M - $50M
      4. Over $50M

User: 3

Bot:  How many employees?

User: About 200

Bot:  What's their timeline for making a decision?

User: This quarter

Bot:  Do they have budget allocated?

User: Yes

Bot:  🔥 Hot Lead! Score: 85/100
      
      This lead is a great fit. I've:
      • Notified sales@company.com
      • Created a follow-up task
      
      Would you like to convert to an opportunity?

Opportunity Management

User: Create a new opportunity for Acme Corp

Bot:  What should we call this opportunity?

User: Enterprise License Deal

Bot:  What is the estimated value of this deal?

User: $50,000

Bot:  When do you expect to close this deal?

User: End of Q2

Bot:  ✅ Opportunity created: Enterprise License Deal
      
      Account: Acme Corp
      Value: $50,000
      Stage: Qualification (10%)
      Close Date: June 30, 2024

Pipeline Update

User: Update the Acme deal to proposal stage

Bot:  Current stage: value_proposition
      
      Select new stage:
      1. Qualification (10%)
      2. Needs Analysis (20%)
      3. Value Proposition (50%)
      4. Decision Makers (60%)
      5. Proposal (75%)
      6. Negotiation (90%)
      7. Closed Won (100%)
      8. Closed Lost (0%)

User: 5

Bot:  ✅ Stage updated to proposal (75%)
      
      Would you like to generate a quote for this opportunity?

Sales Forecast

User: Show me the sales forecast

Bot:  📊 SALES FORECAST
      ════════════════════════════════════════
      
      Total Pipeline: $425,000
      Weighted Pipeline: $187,500
      
      Quarterly Forecast:
      ├── Q1: $45,000
      ├── Q2: $82,500
      ├── Q3: $35,000
      └── Q4: $25,000
      
      Top Opportunities:
      1. Enterprise License - Acme Corp ($50,000) - 75%
      2. Platform Upgrade - TechStart ($35,000) - 60%
      3. Consulting Deal - DataFlow ($28,000) - 50%

Lead Qualification Scoring

The qualification process scores leads based on BANT criteria:

• Budget - Revenue range (up to 30 points)
• Authority - Employee count/company size (up to 25 points)
• Need - Timeline urgency (up to 30 points)
• Timeline - Budget allocation (up to 25 points)

Scoring Thresholds

Lead Nurturing

Automated nurture campaigns based on lead age:

Configuration

Configure in crm.gbot/config.csv:

Scheduled Jobs

Email Integration

Receiving Emails

' on-receive-email.bas
email_from = GET "email.from"
email_subject = GET "email.subject"
email_body = GET "email.body"

' Check if from existing contact
contact = FIND "contacts.csv", "email = '" + email_from + "'"

IF contact THEN
    ' Log activity against contact
    WITH activity
        type = "email"
        subject = email_subject
        contact_id = contact.id
    END WITH
    SAVE "activities.csv", activity
ELSE
    ' Create new lead from email
    CALL "create-lead-from-draft.bas"
END IF

Sending Proposals

' send-proposal.bas
proposal = GENERATE FROM TEMPLATE "proposal_template.docx" WITH {
    "company": account.name,
    "contact": contact.name,
    "products": opportunity_products,
    "total": quote.total,
    "valid_until": quote.valid_until
}

SEND MAIL contact.email, "Proposal: " + opportunity.name, 
    "Please find attached our proposal.", [proposal]

AI Features

Customer Sentiment Analysis

' analyze-customer-sentiment.bas
SET CONTEXT "Analyze customer communication for sentiment and buying signals."

communications = FIND "activities.csv", "contact_id = '" + contact_id + "'"

analysis = LLM "Analyze these customer communications and provide:
               1. Overall sentiment (positive, neutral, negative)
               2. Buying signals detected
               3. Concerns or objections
               4. Recommended next action
               
               Communications: " + JSON(communications)

TALK analysis

Data Enrichment

' data-enrichment.bas
' Enrich lead with external data
company_info = GET "https://api.enrichment.com/company/" + lead.company

IF company_info THEN
    lead.industry = company_info.industry
    lead.employee_count = company_info.employees
    lead.revenue_range = company_info.revenue
    lead.linkedin_url = company_info.linkedin
    
    UPDATE "leads.csv", lead
END IF

Best Practices

1. Qualify early - Use BANT scoring to prioritize leads
2. Track everything - Log all customer interactions
3. Follow up promptly - Hot leads within hours, warm within 24h
4. Use automation - Let nurture campaigns work cold leads
5. Clean pipeline - Archive stale opportunities regularly
6. Forecast accurately - Keep close dates and probabilities updated
7. Segment leads - Use tags and sources for better targeting

Troubleshooting

Use Cases

• Inside Sales - Lead qualification and opportunity management
• Field Sales - Account management and activity tracking
• Sales Management - Pipeline visibility and forecasting
• Business Development - Lead generation and nurturing
• Customer Success - Account health and expansion opportunities

Integration Points

• Email - Inbound/outbound email tracking
• Calendar - Meeting scheduling
• ERP - Order and billing sync
• Marketing Automation - Lead handoff
• Support Ticketing - Case management

Related Templates

• Contacts - Contact directory management
• Marketing - Marketing automation and campaigns
• Analytics - Sales analytics and reporting
• Reminder - Follow-up reminders

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Marketing Automation Template (marketing.gbai)

A General Bots template for marketing campaign management, content creation, and multi-channel broadcast messaging.

Overview

The Marketing template provides marketing automation capabilities including campaign management, content ideation, image generation, social media posting, and WhatsApp broadcast messaging. It enables marketing teams to create, schedule, and deliver campaigns through conversational AI.

Features

• Campaign Management - Create and organize marketing campaigns
• Content Ideation - AI-assisted content idea generation
• Image Generation - AI-powered marketing visuals
• Social Media Posting - Direct posting to Instagram and other platforms
• WhatsApp Broadcasts - Mass messaging with template support
• Contact Segmentation - Target specific audience segments
• Template Compliance - META-approved template validation
• Broadcast Logging - Track delivery and engagement

Package Structure

marketing.gbai/
├── marketing.gbdialog/
│   ├── add-new-idea.bas       # Content ideation tool
│   ├── broadcast.bas          # WhatsApp broadcast messaging
│   ├── get-image.bas          # AI image generation
│   ├── post-to-instagram.bas  # Instagram posting
│   ├── poster.bas             # Marketing poster creation
│   └── campaigns/             # Campaign templates
└── marketing.gbot/
    └── config.csv             # Bot configuration

Scripts

WhatsApp Broadcast

The broadcast.bas script enables mass WhatsApp messaging with template support:

Parameters

Template Compliance

The system validates messages for META WhatsApp template approval:

report = LLM "Esta mensagem será aprovada pelo WhatsApp META como Template? 
              Responda OK se sim, ou explique o problema: " + message

IF report <> "OK" THEN
    TALK "Atenção: " + report
END IF

Broadcast Execution

IF filter THEN
    list = FIND list_file, filter
ELSE
    list = FIND list_file
END IF

index = 1
sent = 0

DO WHILE index < UBOUND(list)
    row = list[index]
    
    SEND TEMPLATE TO row.telefone, template_file
    
    WAIT 0.1  ' Rate limiting
    
    ' Log delivery
    WITH logEntry
        timestamp = NOW()
        phone = row.telefone
        name = row.name
        status = "sent"
    END WITH
    
    SAVE "broadcast_log.csv", logEntry
    
    sent = sent + 1
    index = index + 1
LOOP

TALK "Broadcast enviado para " + sent + " contatos."

Contact List Format

The contact file should include:

Example contacts.xlsx

telefone,name,email,Perfil
+5511999999999,João Silva,joao@email.com,VIP
+5511888888888,Maria Santos,maria@email.com,Regular
+5511777777777,Pedro Costa,pedro@email.com,VIP

Sample Conversations

Creating a Broadcast

User: Send a broadcast to VIP customers

Bot:  I'll help you create a broadcast. What's the message?

User: Olá {name}, aproveite 20% de desconto esta semana!

Bot:  Checking template compliance...
      ✅ Message approved for WhatsApp template.
      
      Do you have a header image?

User: Yes, use promo-banner.jpg

Bot:  Which contact list should I use?

User: contacts.xlsx

Bot:  📤 Broadcast Preview:
      
      Message: Olá {name}, aproveite 20% de desconto esta semana!
      Image: promo-banner.jpg
      Recipients: 127 VIP customers
      
      Send now or schedule?

User: Send now

Bot:  📤 Broadcasting...
      ✅ Broadcast complete! Sent to 127 contacts.
      
      View delivery report in Analytics.

Content Ideation

User: I need content ideas for our new product launch

Bot:  What product are you launching?

User: Wireless headphones

Bot:  What platform are you targeting?

User: Instagram

Bot:  Here are 5 content ideas for your wireless headphones launch:

      1. "Experience Sound Like Never Before 🎧"
         Key message: Premium audio quality
         CTA: Shop now, link in bio
         Hashtags: #WirelessFreedom #AudioExperience #NewLaunch
      
      2. "Cut the Cord, Not the Quality"
         Key message: Freedom without compromise
         CTA: Pre-order today
         Hashtags: #WirelessAudio #TechLife #MusicLovers
      
      3. "Your Music. Your Freedom."
         Key message: Lifestyle integration
         CTA: Discover more
         Hashtags: #OnTheGo #Wireless #Premium
      
      4. "30 Hours of Pure Sound"
         Key message: Battery life
         CTA: Learn more
         Hashtags: #AllDayBattery #WirelessHeadphones
      
      5. "Studio Sound, Everywhere"
         Key message: Professional quality
         CTA: Experience now
         Hashtags: #StudioQuality #Audiophile #TechGear
      
      Would you like me to generate images for any of these?

Image Generation

User: Generate an image for idea 1

Bot:  Generating marketing image...
      
      Prompt: "Premium wireless headphones floating in space with 
      sound waves emanating, modern minimalist style, product 
      photography, dark background with purple accent lighting"
      
      [Generated Image]
      
      ✅ Image generated! Would you like to:
      1. Post to Instagram
      2. Use in a broadcast
      3. Generate variations
      4. Download

User: Post to Instagram

Bot:  What caption should I use?

User: Experience Sound Like Never Before 🎧 #WirelessFreedom #NewLaunch

Bot:  ✅ Posted to Instagram!
      
      Post ID: 12345678
      Time: May 15, 2025 at 2:30 PM
      
      Track engagement in Analytics.

Audience Segmentation

Filter Examples

Building Segments

' Create reusable segments
WITH segment
    id = "SEG-" + FORMAT(GUID())
    name = "VIP São Paulo"
    filter = "Perfil=VIP AND cidade=São Paulo"
    count = COUNT(FIND "contacts.xlsx", filter)
    created_at = NOW()
END WITH

SAVE "segments.csv", segment

Configuration

Configure in marketing.gbot/config.csv: