From 2615a0e891e4a85bc1aba130bd4e0b02b6ee14a6 Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Mon, 24 Nov 2025 13:36:09 -0300 Subject: [PATCH] - Almost done, documentation base for 6.1.0. --- docs/src/README.md | 20 ++-- docs/src/SUMMARY.md | 5 +- docs/src/appendix-i/README.md | 51 +++++----- docs/src/chapter-02/gbdialog.md | 8 +- docs/src/chapter-06-gbdialog/README.md | 2 +- docs/src/chapter-12-auth/README.md | 20 +--- docs/src/chapter-12-auth/bot-auth.md | 16 ++- .../compliance-requirements.md | 15 +-- docs/src/chapter-12-auth/security-features.md | 25 ++--- docs/src/chapter-12-auth/user-auth.md | 21 ++-- docs/src/chapter-13-community/README.md | 11 +-- .../chapter-13-community/ide-extensions.md | 67 +++++++------ docs/src/chapter-13-community/setup.md | 27 ++--- docs/src/contact/README.md | 61 ++++++++++++ docs/src/glossary.md | 98 ++++++++++++++++++- 15 files changed, 274 insertions(+), 173 deletions(-) create mode 100644 docs/src/contact/README.md diff --git a/docs/src/README.md b/docs/src/README.md index 792c4196b..494b4c8f1 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -1,12 +1,12 @@ -# BotServer Documentation +# General Bots Documentation -Welcome to the **BotServer** documentation. This guide explains how to install, configure, extend, and deploy conversational AI bots using BotServer's template-based package system and BASIC scripting language. +Welcome to the **General Bots** documentation. This guide explains how to install, configure, extend, and deploy conversational AI bots using General Bots' template-based package system and BASIC scripting language. --- ## About This Documentation -This documentation has been **recently updated** to accurately reflect the actual implementation of BotServer version 6.0.8. The following sections are now accurate: +This documentation has been **recently updated** to accurately reflect the actual implementation of General Bots version 6.0.8. The following sections are now accurate: ✅ **Accurate Documentation:** - Chapter 02: Package system (template-based `.gbai` structure) @@ -30,9 +30,9 @@ This documentation has been **recently updated** to accurately reflect the actua --- -## What is BotServer? +## What is General Bots? -BotServer is an open-source conversational AI platform written in Rust. It enables users to create intelligent chatbots using: +General Bots is an open-source conversational AI platform written in Rust. It enables users to create intelligent chatbots using: - **BASIC Scripting**: Simple `.bas` scripts for conversation flows - **Template Packages**: Organize bots as `.gbai` directories with dialogs, knowledge bases, and configuration @@ -50,7 +50,7 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl 3. **Create a Bot**: Copy a template and modify it 4. **Learn BASIC**: Read [Chapter 05: BASIC Reference](chapter-05/README.md) 5. **Configure**: Edit `config.csv` in your `.gbot/` directory -6. **Deploy**: Restart BotServer to activate changes +6. **Deploy**: Restart General Bots to activate changes --- @@ -81,7 +81,7 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl - [Chapter 06: gbdialog Reference](chapter-06-gbdialog/README.md) - Complete BASIC scripting reference - Keywords: `TALK`, `HEAR`, `LLM`, `SET CONTEXT`, `USE KB`, and more -### Part VII - Extending BotServer +### Part VII - Extending General Bots - [Chapter 07: gbapp Architecture Reference](chapter-07-gbapp/README.md) - Internal architecture - [Architecture Overview](chapter-07-gbapp/architecture.md) - Bootstrap process - [Building from Source](chapter-07-gbapp/building.md) - Compilation and features @@ -114,7 +114,7 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl ## Architecture Overview -BotServer is a **monolithic Rust application** (single crate) with the following structure: +General Bots is a **monolithic Rust application** (single crate) with the following structure: ### Core Modules - `auth` - Argon2 password hashing, session tokens @@ -159,7 +159,7 @@ BotServer is a **monolithic Rust application** (single crate) with the following - **Version**: 6.0.8 - **License**: AGPL-3.0 -- **Repository**: https://github.com/GeneralBots/BotServer +- **Repository**: https://github.com/GeneralBots/botserver - **Community**: Open-source contributors from Pragmatismo.com.br --- @@ -178,4 +178,4 @@ See [TODO.txt](TODO.txt) for known documentation gaps. ## Next Steps -Start with [Introduction](introduction.md) for a comprehensive overview, or jump directly to [Chapter 01: Run and Talk](chapter-01/README.md) to install and run BotServer. \ No newline at end of file +Start with [Introduction](introduction.md) for a comprehensive overview, or jump directly to [Chapter 01: Run and Talk](chapter-01/README.md) to install and run General Bots. \ No newline at end of file diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 67e681520..d14083ed3 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -174,7 +174,7 @@ - [Documentation](./chapter-13-community/documentation.md) - [Pull Requests](./chapter-13-community/pull-requests.md) - [Community Guidelines](./chapter-13-community/community.md) - - [IDE Extensions](./chapter-13-community/ide-extensions.md) + - [IDEs](./chapter-13-community/ide-extensions.md) # Appendices @@ -183,4 +183,5 @@ - [Tables](./appendix-i/tables.md) - [Relationships](./appendix-i/relationships.md) -[Glossary](./glossary.md) \ No newline at end of file +[Glossary](./glossary.md) +[Contact](./contact/README.md) \ No newline at end of file diff --git a/docs/src/appendix-i/README.md b/docs/src/appendix-i/README.md index 529ca02f2..8f0927005 100644 --- a/docs/src/appendix-i/README.md +++ b/docs/src/appendix-i/README.md @@ -1,6 +1,8 @@ -## Appendix I – Database Model +## Appendix I – Database Model -The core database schema for GeneralBots is defined in `src/shared/models.rs`. It uses **Diesel** with SQLite (or PostgreSQL) and includes the following primary tables: +![Database Schema Overview](./assets/schema-overview.svg) + +The core database schema for GeneralBots is defined in `src/shared/models.rs`. It uses **Diesel** with PostgreSQL and includes the following primary tables: | Table | Description | |-------|-------------| @@ -18,32 +20,27 @@ The core database schema for GeneralBots is defined in `src/shared/models.rs`. I - **Session ↔ Tools** – One‑to‑many: tools are scoped to the session that registers them. - **File ↔ KnowledgeBase** – Optional link for documents stored in a knowledge base. -### Key Fields (excerpt) +### Key Tables -```rust -pub struct User { - pub id: i32, - pub username: String, - pub email: String, - pub password_hash: String, - pub created_at: NaiveDateTime, -} +**User Table** +- id: Integer primary key +- username: String +- email: String +- password_hash: String +- created_at: Timestamp -pub struct Session { - pub id: i32, - pub user_id: i32, - pub started_at: NaiveDateTime, - pub last_active: NaiveDateTime, - pub knowledge_base_id: i32, -} +**Session Table** +- id: Integer primary key +- user_id: Foreign key to User +- started_at: Timestamp +- last_active: Timestamp +- knowledge_base_id: Integer -pub struct Message { - pub id: i32, - pub session_id: i32, - pub role: String, // "user" or "assistant" - pub content: String, - pub timestamp: NaiveDateTime, -} -``` +**Message Table** +- id: Integer primary key +- session_id: Foreign key to Session +- role: String ("user" or "assistant") +- content: Text +- timestamp: Timestamp -The schema is automatically migrated by Diesel when the server starts. For custom extensions, add new tables to `models.rs` and run `diesel migration generate `. +The schema is automatically migrated when the server starts. diff --git a/docs/src/chapter-02/gbdialog.md b/docs/src/chapter-02/gbdialog.md index 7a09760ab..4fc915ac3 100644 --- a/docs/src/chapter-02/gbdialog.md +++ b/docs/src/chapter-02/gbdialog.md @@ -19,8 +19,8 @@ Instead of complex logic, use the LLM's natural understanding: ```basic ' Example from announcements.gbai/update-summary.bas ' Generate summaries from documents -let text = GET "announcements.gbkb/news/news.pdf" -let resume = LLM "In a few words, resume this: " + text +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 @@ -136,8 +136,8 @@ TALK "Hello! I'm here to help." SET SCHEDULE "59 * * * *" ' Fetch and summarize documents ONCE for all users -let text = GET "announcements.gbkb/news/news.pdf" -let resume = LLM "In a few words, resume this: " + text +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 ``` diff --git a/docs/src/chapter-06-gbdialog/README.md b/docs/src/chapter-06-gbdialog/README.md index 01dc995a1..2c011a84a 100644 --- a/docs/src/chapter-06-gbdialog/README.md +++ b/docs/src/chapter-06-gbdialog/README.md @@ -83,7 +83,7 @@ TALK "The answer is: " + answer ### 2. HEAR - Input from User ```basic HEAR name -HEAR age AS NUMBER +HEAR age AS INTEGER HEAR confirm AS BOOLEAN ``` diff --git a/docs/src/chapter-12-auth/README.md b/docs/src/chapter-12-auth/README.md index 8e904ac3f..17fa573f7 100644 --- a/docs/src/chapter-12-auth/README.md +++ b/docs/src/chapter-12-auth/README.md @@ -20,13 +20,7 @@ General Bots provides robust authentication with: - All passwords are hashed using Argon2 (winner of Password Hashing Competition) - Random salt generation for each password - Secure password update mechanism - -```rust -// Example password hashing -let salt = SaltString::generate(&mut OsRng); -let argon2 = Argon2::default(); -let password_hash = argon2.hash_password(password.as_bytes(), &salt); -``` +- Password management delegated to Directory Service ## API Endpoints @@ -49,19 +43,13 @@ Authenticates user and returns session ## User Management ### Creating Users -```rust -auth_service.create_user(username, email, password); -``` +Users are created through the Directory Service with randomly generated initial passwords. ### Verifying Users -```rust -auth_service.verify_user(username, password); -``` +User verification is handled through the Directory Service OAuth2/OIDC flow. ### Updating Passwords -```rust -auth_service.update_user_password(user_id, new_password); -``` +Password updates are managed through the Directory Service's built-in password reset workflows. ## Bot Authentication diff --git a/docs/src/chapter-12-auth/bot-auth.md b/docs/src/chapter-12-auth/bot-auth.md index a72e73221..d1d3456d2 100644 --- a/docs/src/chapter-12-auth/bot-auth.md +++ b/docs/src/chapter-12-auth/bot-auth.md @@ -40,16 +40,12 @@ Configuration stored in `bot_configuration` table: ### Session Structure -```rust -// user_sessions table -{ - id: UUID, - user_id: UUID, // User reference - bot_id: UUID, // Bot reference - session_token: String, - expires_at: Timestamp -} -``` +The user_sessions table structure: +- id: UUID +- user_id: UUID (User reference) +- bot_id: UUID (Bot reference) +- session_token: String +- expires_at: Timestamp ## Bot Isolation diff --git a/docs/src/chapter-12-auth/compliance-requirements.md b/docs/src/chapter-12-auth/compliance-requirements.md index 69ee865e7..59bfe070c 100644 --- a/docs/src/chapter-12-auth/compliance-requirements.md +++ b/docs/src/chapter-12-auth/compliance-requirements.md @@ -109,7 +109,7 @@ app.example.com { | 🔄 | Automated Backups | PostgreSQL | All | Daily backups via pg_dump/pg_basebackup | | ✅ | Point-in-Time Recovery | PostgreSQL | HIPAA | WAL archiving enabled | -**Configuration File**: `/etc/postgresql/*/main/postgresql.conf` +**Configuration**: Installed and configured automatically via installer.rs ```sql -- Enable SSL @@ -150,16 +150,7 @@ log_statement = 'all' | 🔄 | Replication | Drive | HIPAA | Multi-site replication for DR | | ✅ | IAM Integration | Drive | All | Integration with Directory Service via OIDC | -**Environment Variables**: -```bash -DRIVE_ROOT_USER=admin -DRIVE_ROOT_PASSWORD=SecurePassword123! -DRIVE_SERVER_URL=https://drive.example.com -DRIVE_BROWSER=on -DRIVE_IDENTITY_OPENID_CONFIG_URL=http://localhost:8080/.well-known/openid-configuration -DRIVE_IDENTITY_OPENID_CLIENT_ID=drive -DRIVE_IDENTITY_OPENID_CLIENT_SECRET=secret -``` +**Configuration**: `/conf/drive/config.env` **Bucket Policy Example**: ```json @@ -192,7 +183,7 @@ DRIVE_IDENTITY_OPENID_CLIENT_SECRET=secret | ✅ | Authentication | Stalwart | All | OIDC integration with Directory Service | | 📝 | Retention Policy | Stalwart | GDPR/LGPD | Define and implement email retention | -**Configuration File**: `/etc/stalwart/config.toml` +**Configuration**: `/conf/mail/config.toml` ```toml [server.listener."smtp"] diff --git a/docs/src/chapter-12-auth/security-features.md b/docs/src/chapter-12-auth/security-features.md index 7cec987d8..f25788357 100644 --- a/docs/src/chapter-12-auth/security-features.md +++ b/docs/src/chapter-12-auth/security-features.md @@ -58,15 +58,12 @@ Enterprise-ready security features: General Bots uses the Directory Service (currently Zitadel, but can be migrated to Keycloak or other OIDC providers) as the primary identity provider: -```rust -// Location: src/auth/directory.rs -// Features: +Features: - OAuth2/OIDC authentication - JWT token validation - User/group management - Permission management - Session handling -``` ### Password Security @@ -98,17 +95,15 @@ General Bots uses the Directory Service (currently Zitadel, but can be migrated ### Data Encryption -```rust -// Encryption at rest +**Encryption at rest:** - Database: Column-level encryption for sensitive fields - File storage: AES-256-GCM for uploaded files - Configuration: Encrypted secrets with master key -// Encryption in transit +**Encryption in transit:** - TLS 1.3 for all external communications - mTLS for service-to-service communication - Certificate pinning for critical services -``` ## Network Security @@ -169,26 +164,24 @@ General Bots uses the Directory Service (currently Zitadel, but can be migrated - Temporary files: Secure deletion ### Memory Security +### Memory Protection -```rust -// Memory protection measures +Memory protection measures: - Zeroization of sensitive data - No logging of secrets - Secure random generation - Protected memory pages for crypto keys -``` ## Audit & Compliance ### Logging Configuration +### Log Security -```rust -// Structured logging with tracing +Structured logging configuration: - Level: INFO (production), DEBUG (development) - Format: JSON for machine parsing - Rotation: Daily with 30-day retention - Sensitive data: Redacted -``` ### Audit Events @@ -465,8 +458,8 @@ For security issues or questions: - [LiveKit Security](https://docs.livekit.io/realtime/server/security/) - Video conferencing ## References +## Resources - [OWASP Top 10](https://owasp.org/Top10/) - [CIS Controls](https://www.cisecurity.org/controls/) -- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) -- [Rust Security Guidelines](https://anssi-fr.github.io/rust-guide/) \ No newline at end of file +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) \ No newline at end of file diff --git a/docs/src/chapter-12-auth/user-auth.md b/docs/src/chapter-12-auth/user-auth.md index 80d8b806f..6e184210f 100644 --- a/docs/src/chapter-12-auth/user-auth.md +++ b/docs/src/chapter-12-auth/user-auth.md @@ -474,23 +474,16 @@ Located in `src/directory/mod.rs`: ### Creating Users -```rust -// Via Directory Client -client.create_user( - username: "john_doe", - email: "john@example.com", - first_name: "John", - last_name: "Doe" -) -// Password set through Directory UI or email flow -``` +Creating users via Directory Client: +- Username: john_doe +- Email: john@example.com +- First name: John +- Last name: Doe +- Password: Set through Directory UI or email flow ### Getting User Info -```rust -// Fetch from Directory service -let user_info = client.get_user(directory_id).await?; -``` +User information is fetched from the Directory service using the directory ID. ### Managing Sessions diff --git a/docs/src/chapter-13-community/README.md b/docs/src/chapter-13-community/README.md index 9e1009530..47760d966 100644 --- a/docs/src/chapter-13-community/README.md +++ b/docs/src/chapter-13-community/README.md @@ -1,10 +1,10 @@ -# Contributing to BotServer +# Contributing to General Bots -Welcome to the BotServer community! We appreciate your interest in contributing to this open-source project. This chapter provides comprehensive guidance for contributors. +Welcome to the General Bots community! We appreciate your interest in contributing to this open-source project. This chapter provides comprehensive guidance for contributors. ## Overview -BotServer is an open-source conversational AI platform built in Rust. We welcome contributions of all kinds: +General Bots is an open-source conversational AI platform built in Rust, actively used in production since 2018. We welcome contributions of all kinds: - Code improvements - Documentation updates - Bug reports @@ -18,16 +18,15 @@ BotServer is an open-source conversational AI platform built in Rust. We welcome Before contributing, ensure you have: - Rust 1.70 or later -- PostgreSQL 14 or later - Git experience -- Basic understanding of BotServer architecture +- Basic understanding of General Bots architecture ### First Steps 1. **Fork the Repository** ```bash git clone https://github.com/GeneralBots/BotServer.git - cd BotServer + cd botserver ``` 2. **Set Up Development Environment** diff --git a/docs/src/chapter-13-community/ide-extensions.md b/docs/src/chapter-13-community/ide-extensions.md index ef35be96e..915cca509 100644 --- a/docs/src/chapter-13-community/ide-extensions.md +++ b/docs/src/chapter-13-community/ide-extensions.md @@ -1,53 +1,52 @@ -# IDE Extensions +# IDEs -BotServer provides extensions and plugins for modern code editors to enhance the development experience with BASIC scripts, bot configurations, and platform integration. +General Bots supports development with any text editor or IDE. Choose the one that works best for your workflow. -## Zed Editor (Recommended) +## Zed Editor (Best for Rust Development) -Zed is a high-performance, collaborative code editor built for the modern developer. +Zed is a high-performance, collaborative code editor that excels at Rust development and is recommended for working with General Bots core. + +### Why Zed? +- Native Rust support with excellent syntax highlighting +- Fast performance and minimal resource usage +- Built-in collaboration features +- Modern, clean interface ### Installation ```bash # Install Zed curl https://zed.dev/install.sh | sh - -# Install BotServer extension -zed --install-extension botserver ``` -### Features +## Other Popular IDEs -#### Syntax Highlighting -- BASIC keywords and functions -- Configuration CSV files -- Bot package structure recognition -- Theme CSS variables +You can use any IDE or text editor you prefer: -#### Language Server Protocol (LSP) +### Visual Studio Code +- Extensive extension marketplace +- Good BASIC syntax highlighting with custom extensions +- Integrated terminal for running General Bots +- Git integration -Configure in `~/.config/zed/settings.json`: -```json -{ - "lsp": { - "botserver": { - "binary": { - "path": "/usr/local/bin/botserver", - "arguments": ["--lsp"] - }, - "initialization_options": { - "bot": "default", - "enableDebug": true - } - } - } -} -``` +### IntelliJ IDEA / RustRover +- Excellent Rust support +- Powerful refactoring tools +- Database tools for PostgreSQL integration -#### Key Bindings +### Neovim +- Lightweight and fast +- Highly customizable +- Terminal-based workflow -Add to `~/.config/zed/keymap.json`: -```json +### Sublime Text +- Fast and responsive +- Multiple cursors and powerful search +- Customizable syntax highlighting + +## BASIC Script Support + +For editing `.bas` files (General Bots dialog scripts): { "bindings": { "cmd-shift-b": "botserver:run-script", diff --git a/docs/src/chapter-13-community/setup.md b/docs/src/chapter-13-community/setup.md index af43abb75..15006ecbc 100644 --- a/docs/src/chapter-13-community/setup.md +++ b/docs/src/chapter-13-community/setup.md @@ -1,6 +1,6 @@ # Development Setup -This guide covers setting up a development environment for contributing to BotServer. +This guide covers setting up a development environment for contributing to General Bots. ## Prerequisites @@ -11,14 +11,7 @@ This guide covers setting up a development environment for contributing to BotSe curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` -- **PostgreSQL**: 14 or later - ```bash - # Ubuntu/Debian - sudo apt-get install postgresql postgresql-contrib - - # macOS - brew install postgresql - ``` +- **PostgreSQL**: Installed automatically during bootstrap - **Git**: For version control ```bash @@ -37,17 +30,16 @@ This guide covers setting up a development environment for contributing to BotSe ```bash git clone https://github.com/GeneralBots/BotServer.git -cd BotServer +cd botserver ``` ### 2. Environment Setup -Create a `.env` file in the project root: +The `.env` file is created automatically during bootstrap with secure random credentials. No manual configuration needed. ```bash -DATABASE_URL=postgres://gbuser:password@localhost:5432/botserver -DRIVE_SERVER=http://localhost:9000 -DRIVE_ACCESSKEY=minioadmin +# Bootstrap creates everything automatically +./botserver DRIVE_SECRET=minioadmin SERVER_HOST=127.0.0.1 SERVER_PORT=8080 @@ -153,8 +145,8 @@ If bootstrap doesn't create the database: psql -U postgres # Create user and database -CREATE USER gbuser WITH PASSWORD 'your_password'; -CREATE DATABASE botserver OWNER gbuser; +CREATE USER gbuser WITH PASSWORD 'SecurePassword123!'; +CREATE DATABASE generalbots OWNER gbuser; \q ``` @@ -234,13 +226,12 @@ ssh user@server 'tmux new -s botserver' ## Debugging -### Enable Debug Logging ### Debug Mode Run with verbose output to troubleshoot issues: ```bash -cargo run +RUST_LOG=trace cargo run ``` Check logs in the console output for debugging information. diff --git a/docs/src/contact/README.md b/docs/src/contact/README.md new file mode 100644 index 000000000..09fb9ea92 --- /dev/null +++ b/docs/src/contact/README.md @@ -0,0 +1,61 @@ +# Contact + +## Get in Touch + +General Bots has been powering conversational AI solutions since 2018. We're here to help you build intelligent automation and enhanced customer engagement. + +### Support + +For technical support and documentation: +- **Documentation**: [https://pragmatismo.com.br](https://pragmatismo.com.br) +- **GitHub**: [https://github.com/GeneralBots](https://github.com/GeneralBots) +- **Email**: support@pragmatismo.com.br + +### Business Inquiries + +Interested in implementing General Bots for your organization? + +**Pragmatismo Inovações Ltda.** +Avenida Rio Branco, 177, Sala 201 a 2201 +Rio de Janeiro - Brasil +CNPJ: 40.293.841/0001-59 + +📞 **Phone**: +55 21 4040-2160 (24h) +📧 **Email**: info@pragmatismo.com.br +🌐 **Website**: [pragmatismo.com.br](https://pragmatismo.com.br) + +### Schedule a Demo + +Want to see General Bots in action? Our team can demonstrate: +- Custom bot development +- LLM integration +- Knowledge base setup +- Multi-channel deployment +- Enterprise automation + +[Schedule a meeting](https://calendly.com/pragmatismo) to explore how General Bots can transform your business operations. + +### Data Protection + +**Data Protection Officer (DPO)** +Rodrigo Rodriguez +📧 security@pragmatismo.com.br + +### Open Source Community + +General Bots is open source and we welcome contributions: +- Report issues on GitHub +- Submit pull requests +- Join discussions +- Share your use cases + +### Legal + +- [Terms of Service](/terms) +- [Privacy Policy](/privacy) +- DUNS Number: 926754884 + +--- + +*General Bots® - Enterprise conversational AI platform* +*Copyright © 2016-2025 Pragmatismo Inovações Ltda.* \ No newline at end of file diff --git a/docs/src/glossary.md b/docs/src/glossary.md index b5f60b387..a00c1fc79 100644 --- a/docs/src/glossary.md +++ b/docs/src/glossary.md @@ -1,6 +1,6 @@ # Glossary -Quick lookup for BotServer terms. If you're lost, start here. +Quick lookup for General Bots terms. If you're lost, start here. ## A @@ -10,12 +10,14 @@ Quick lookup for BotServer terms. If you're lost, start here. ## B -**BASIC** - Yes, that programming language from 1964. We brought it back because `TALK "Hello"` beats `await ctx.send()` any day. Powers all conversation scripts. +**BASIC** - Yes, that programming language from 1964. We brought it back because `TALK "Hello"` beats `await ctx.send()` any day. Powers all conversation scripts. Used since 2018 in production systems. **Bot Package** - A folder ending in `.gbai` containing everything to run a bot. Scripts, documents, config. That's it. Copy folder = deploy bot. **BotSession** - The conversation between user and bot. Remembers everything - who you are, what you said, where you left off. Persists to database, cached for speed. +**Bootstrap** - Initial setup process that automatically installs all dependencies. Runs on first launch, creates configuration, sets up database, configures services. + ## C **Collection** - A folder of documents in `.gbkb/` that becomes searchable knowledge. Drop PDFs in `policies/`, bot answers policy questions. Zero configuration. @@ -48,6 +50,96 @@ Quick lookup for BotServer terms. If you're lost, start here. **.gbtheme** - Optional UI customization. CSS files, images, HTML templates. Most bots don't need this. +**.gbdrive** - File storage configuration. Maps to Drive (S3-compatible) buckets for document management. + +**General Bots** - The enterprise conversational AI platform. Combines LLMs with structured dialogs, knowledge bases, and multi-channel support. + +## H + +**HEAR** - BASIC keyword to get user input. `answer = HEAR "What's your name?"` waits for response. + +**Hot Reload** - Changes to BASIC scripts apply immediately. No restart needed. Edit, save, test - instant feedback loop. + +## I + +**Installer** - Component that auto-configures services. Manages PostgreSQL, Cache, Drive, Directory Service, LLM servers. Everything runs locally. + +**Intent** - What the user wants to do. Detected from natural language. "I want to reset my password" → password_reset intent. + +## K + +**Knowledge Base** - Documents that become searchable answers. PDFs, Word files, web pages. Automatically chunked, embedded, and indexed for semantic search. + +## L + +**LLM** - Large Language Model. The AI brain. Default uses llama.cpp with GGUF models. Supports OpenAI, Anthropic, local models. + +**Local-First** - Everything runs on your machine. No cloud dependencies. Database, storage, LLM - all local. Privacy by default. + +## M + +**Memory** - Bot and user memory storage. `SET BOT MEMORY "key", "value"` persists data. `GET BOT MEMORY "key"` retrieves it. + +**Multi-Channel** - Same bot works everywhere. WhatsApp, Teams, Web, API. Write once, deploy anywhere. + +## O + +**OIDC** - OpenID Connect authentication. Handled by Directory Service (Zitadel). No passwords stored in General Bots. + +## P + +**Package Manager** - System that installs bot packages. Drop `.gbai` folder, it's automatically loaded. Remove folder, bot stops. + +**PostgreSQL** - The database. Stores users, sessions, messages, memory. Auto-installed, auto-configured. Just works. + +**Pragmatismo** - Company behind General Bots. Brazilian software consultancy. Building bots since 2016. + +## Q + +**Qdrant** - Vector database for semantic search. Optional component for large-scale knowledge bases. Faster than PostgreSQL pgvector for millions of documents. + +## R + +**REPL** - Read-Eval-Print Loop. Interactive BASIC console for testing. Type commands, see results immediately. + +## S + +**Semantic Search** - Finding by meaning, not keywords. "How do I change my password?" finds "reset credentials" documentation. + +**Session** - Active conversation state. Tracks user, bot, context, memory. Expires after inactivity. Stored in PostgreSQL, cached in memory. + +**SET CONTEXT** - BASIC command to add information to LLM context. `SET CONTEXT "User is premium customer"` influences all responses. + +## T + +**TALK** - BASIC keyword for bot output. `TALK "Hello!"` sends message to user. Supports markdown, images, cards. + +**Token** - Unit of text for LLMs. Roughly 4 characters. Context windows measured in tokens. GPT-4: 8k tokens. Local models: 4k typically. + +**Tool** - Function the bot can call. Defined in BASIC with parameters. `PARAM "city"` then `weather = GET "weather"` calls weather API. + +## U + +**USE KB** - BASIC command to activate knowledge base. `USE KB "policies"` makes policy documents searchable in conversation. + +**USE TOOL** - Activate a tool for LLM to use. `USE TOOL "calculator"` lets bot do math. + +## V + +**Valkey** - Redis-compatible cache. Stores sessions, temporary data. Faster than database for frequently accessed data. + +**Vector** - Mathematical representation of text meaning. Used for semantic search. Created by embedding models. + +## W + +**WebSocket** - Real-time connection for chat. Enables streaming responses, live updates. No polling needed. + +**Workflow** - Sequence of dialog steps. Login → Verify → Action → Confirm. Defined in BASIC, no complex orchestration. + +## Z + +**Zitadel** - Current Directory Service implementation. Handles authentication, users, permissions. Can be replaced with Keycloak or other OIDC providers. + ## H **HEAR** - BASIC keyword to get user input. `name = HEAR` waits for user to type, stores response in variable. @@ -144,6 +236,6 @@ Quick lookup for BotServer terms. If you're lost, start here. **"Is BASIC really BASIC?"** - Inspired by BASIC, not strict implementation. Simpler, focused on conversations. -**"Can I use TypeScript/Python/etc?"** - No. BASIC only for conversation logic. Extend core in Rust if needed. +**"Can I use TypeScript/Python/etc?"** - BASIC is used for conversation logic. However, you can integrate with any language through APIs. See [API documentation](./chapter-10-api/README.md) for REST endpoints and integration options. **"Is it production-ready?"** - Yes. Used in production since 2016 (earlier versions), current Rust version since 2023. \ No newline at end of file